Botan 3.14.1
Crypto and TLS for C&
tls_record.h
Go to the documentation of this file.
1/*
2* TLS Record Handling
3* (C) 2004-2012 Jack Lloyd
4* 2016 Matthias Gierlings
5*
6* Botan is released under the Simplified BSD License (see license.txt)
7*/
8
9#ifndef BOTAN_TLS_RECORDS_H_
10#define BOTAN_TLS_RECORDS_H_
11
12#include <botan/assert.h>
13#include <botan/secmem.h>
14#include <botan/tls_algos.h>
15#include <botan/tls_magic.h>
16#include <botan/tls_version.h>
17#include <array>
18#include <functional>
19#include <memory>
20#include <span>
21#include <vector>
22
23namespace Botan {
24
25class AEAD_Mode;
27
28} // namespace Botan
29
30namespace Botan::TLS {
31
32class Ciphersuite;
33class Session_Keys;
34
36
37/**
38* A TLS record nonce, stored inline to avoid an allocation per record
39*/
40class Record_Nonce final {
41 public:
42 // The largest nonce is the 16 byte AES block for CBC mode suites
43 static constexpr size_t MAX_NONCE_LEN = 16;
44
45 Record_Nonce() = default;
46
47 explicit Record_Nonce(size_t len) : m_len(len) { BOTAN_ARG_CHECK(len <= MAX_NONCE_LEN, "Nonce is too long"); }
48
49 std::span<uint8_t> get() { return std::span{m_nonce}.first(m_len); }
50
51 std::span<const uint8_t> get() const { return std::span{m_nonce}.first(m_len); }
52
53 private:
54 std::array<uint8_t, MAX_NONCE_LEN> m_nonce{};
55 size_t m_len = 0;
56};
57
58/**
59* TLS Cipher State
60*/
62 public:
63 /**
64 * Initialize a new cipher state
65 */
67 Connection_Side which_side,
68 bool is_our_side,
69 const Ciphersuite& suite,
70 const Session_Keys& keys,
71 bool uses_encrypt_then_mac);
72
74
77
80
82 BOTAN_ASSERT_NONNULL(m_aead.get());
83 return *m_aead;
84 }
85
86 Record_Nonce aead_nonce(uint64_t seq, RandomNumberGenerator& rng) const;
87
88 Record_Nonce aead_nonce(const uint8_t record[], size_t record_len, uint64_t seq) const;
89
90 std::array<uint8_t, 13> format_ad(uint64_t seq,
91 Record_Type type,
92 Protocol_Version version,
93 uint16_t ptext_length);
94
95 size_t nonce_bytes_from_handshake() const { return m_nonce_bytes_from_handshake; }
96
97 size_t nonce_bytes_from_record() const { return m_nonce_bytes_from_record; }
98
99 Nonce_Format nonce_format() const { return m_nonce_format; }
100
101 private:
102 std::unique_ptr<AEAD_Mode> m_aead;
103
104 std::vector<uint8_t> m_nonce;
105 Nonce_Format m_nonce_format;
106 size_t m_nonce_bytes_from_handshake;
107 size_t m_nonce_bytes_from_record;
108};
109
110class Record_Header final {
111 public:
113 m_needed(0), m_sequence(sequence), m_version(version), m_type(type) {}
114
115 explicit Record_Header(size_t needed) : m_needed(needed), m_sequence(0), m_type(Record_Type::Invalid) {}
116
117 size_t needed() const { return m_needed; }
118
120 BOTAN_ASSERT_NOMSG(m_needed == 0);
121 return m_version;
122 }
123
124 uint64_t sequence() const {
125 BOTAN_ASSERT_NOMSG(m_needed == 0);
126 return m_sequence;
127 }
128
129 uint16_t epoch() const { return static_cast<uint16_t>(sequence() >> 48); }
130
132 BOTAN_ASSERT_NOMSG(m_needed == 0);
133 return m_type;
134 }
135
136 private:
137 size_t m_needed;
138 uint64_t m_sequence;
139 Protocol_Version m_version;
140 Record_Type m_type;
141};
142
143/**
144* Create an initial (unencrypted) TLS handshake record
145* @param write_buffer the output record is placed here
146* @param record_type the record layer type
147* @param record_version the record layer version
148* @param record_sequence the record layer sequence number
149* @param message the record contents
150* @param message_len is size of message
151*/
153 Record_Type record_type,
154 Protocol_Version record_version,
155 uint64_t record_sequence,
156 const uint8_t* message,
157 size_t message_len);
158
159/**
160* Create a TLS record
161* @param write_buffer the output record is placed here
162* @param record_type the record layer type
163* @param record_version the record layer version
164* @param record_sequence the record layer sequence number
165* @param message the record contents
166* @param message_len is size of message
167* @param cipherstate is the writing cipher state
168* @param rng is a random number generator
169*/
170void write_record(secure_vector<uint8_t>& write_buffer,
171 Record_Type record_type,
172 Protocol_Version record_version,
173 uint64_t record_sequence,
174 const uint8_t* message,
175 size_t message_len,
176 Connection_Cipher_State& cipherstate,
178
179// epoch -> cipher state
180typedef std::function<std::shared_ptr<Connection_Cipher_State>(uint16_t)> get_cipherstate_fn;
181
182/**
183* Decode a TLS record
184* @return zero if full message, else number of bytes still needed
185*/
187 secure_vector<uint8_t>& read_buffer,
188 const uint8_t input[],
189 size_t input_len,
190 size_t& consumed,
191 secure_vector<uint8_t>& record_buf,
192 Connection_Sequence_Numbers* sequence_numbers,
193 const get_cipherstate_fn& get_cipherstate,
194 bool allow_epoch0_restart);
195
196} // namespace Botan::TLS
197
198#endif
#define BOTAN_ASSERT_NOMSG(expr)
Definition assert.h:82
#define BOTAN_ASSERT_NONNULL(ptr)
Definition assert.h:121
#define BOTAN_ARG_CHECK(expr, msg)
Definition assert.h:33
Record_Nonce aead_nonce(uint64_t seq, RandomNumberGenerator &rng) const
Connection_Cipher_State(const Connection_Cipher_State &other)=delete
Nonce_Format nonce_format() const
Definition tls_record.h:99
size_t nonce_bytes_from_handshake() const
Definition tls_record.h:95
Connection_Cipher_State & operator=(Connection_Cipher_State &&other)=delete
std::array< uint8_t, 13 > format_ad(uint64_t seq, Record_Type type, Protocol_Version version, uint16_t ptext_length)
Connection_Cipher_State(Protocol_Version version, Connection_Side which_side, bool is_our_side, const Ciphersuite &suite, const Session_Keys &keys, bool uses_encrypt_then_mac)
Connection_Cipher_State(Connection_Cipher_State &&other)=delete
Connection_Cipher_State & operator=(const Connection_Cipher_State &other)=delete
Protocol_Version version() const
Definition tls_record.h:119
Record_Type type() const
Definition tls_record.h:131
Record_Header(size_t needed)
Definition tls_record.h:115
uint64_t sequence() const
Definition tls_record.h:124
uint16_t epoch() const
Definition tls_record.h:129
Record_Header(uint64_t sequence, Protocol_Version version, Record_Type type)
Definition tls_record.h:112
static constexpr size_t MAX_NONCE_LEN
Definition tls_record.h:43
std::span< const uint8_t > get() const
Definition tls_record.h:51
std::span< uint8_t > get()
Definition tls_record.h:49
void write_unencrypted_record(secure_vector< uint8_t > &output, Record_Type record_type, Protocol_Version version, uint64_t record_sequence, const uint8_t *message, size_t message_len)
std::function< std::shared_ptr< Connection_Cipher_State >(uint16_t)> get_cipherstate_fn
Definition tls_record.h:180
void write_record(secure_vector< uint8_t > &output, Record_Type record_type, Protocol_Version version, uint64_t record_sequence, const uint8_t *message, size_t message_len, Connection_Cipher_State &cs, RandomNumberGenerator &rng)
Record_Header read_record(TLS_Flavor flavor, secure_vector< uint8_t > &readbuf, const uint8_t input[], size_t input_len, size_t &consumed, secure_vector< uint8_t > &recbuf, Connection_Sequence_Numbers *sequence_numbers, const get_cipherstate_fn &get_cipherstate, bool allow_epoch0_restart)
std::vector< T, secure_allocator< T > > secure_vector
Definition secmem.h:128