Botan  2.4.0
Crypto and TLS for C++11
Classes | Typedefs | Enumerations | Functions
Botan::TLS Namespace Reference

Classes

class  Alert
 
class  Application_Layer_Protocol_Notification
 
class  Blocking_Client
 
class  BSI_TR_02102_2
 
class  Callbacks
 
class  Certificate
 
class  Certificate_Req
 
class  Certificate_Status
 
class  Certificate_Status_Request
 
class  Certificate_Verify
 
class  Change_Cipher_Spec
 
class  Channel
 
class  Ciphersuite
 
class  Client
 
class  Client_Hello
 
class  Client_Key_Exchange
 
class  Compat_Callbacks
 
class  Connection_Cipher_State
 
class  Connection_Sequence_Numbers
 
class  Datagram_Handshake_IO
 
class  Datagram_Policy
 
class  Datagram_Sequence_Numbers
 
class  Encrypt_then_MAC
 
class  Extended_Master_Secret
 
class  Extension
 
class  Extensions
 
class  Finished
 
class  Handshake_Hash
 
class  Handshake_IO
 
class  Handshake_Message
 
class  Handshake_State
 
class  Hello_Request
 
class  Hello_Verify_Request
 
class  New_Session_Ticket
 
class  NSA_Suite_B_128
 
class  Policy
 
class  Protocol_Version
 
class  Record
 
class  Record_Message
 
class  Record_Raw_Input
 
class  Renegotiation_Extension
 
class  Server
 
class  Server_Hello
 
class  Server_Hello_Done
 
class  Server_Information
 
class  Server_Key_Exchange
 
class  Server_Name_Indicator
 
class  Session
 
class  Session_Keys
 
class  Session_Manager
 
class  Session_Manager_In_Memory
 
class  Session_Manager_Noop
 
class  Session_Manager_SQL
 
class  Session_Manager_SQLite
 
class  Session_Ticket
 
class  Signature_Algorithms
 
class  SRTP_Protection_Profiles
 
class  Stream_Handshake_IO
 
class  Stream_Sequence_Numbers
 
class  Strict_Policy
 
class  Supported_Groups
 
class  Supported_Point_Formats
 
class  Text_Policy
 
class  TLS_CBC_HMAC_AEAD_Decryption
 
class  TLS_CBC_HMAC_AEAD_Encryption
 
class  TLS_CBC_HMAC_AEAD_Mode
 
class  TLS_Data_Reader
 
class  TLS_Exception
 
class  Unexpected_Message
 

Typedefs

typedef std::function< std::shared_ptr< Connection_Cipher_State >uint16_t)> get_cipherstate_fn
 
using Supported_Elliptic_Curves = Supported_Groups
 

Enumerations

enum  { TLS_EMPTY_RENEGOTIATION_INFO_SCSV = 0x00FF, TLS_FALLBACK_SCSV = 0x5600 }
 
enum  Compression_Method { NO_COMPRESSION = 0x00, DEFLATE_COMPRESSION = 0x01 }
 
enum  Connection_Side { CLIENT = 1, SERVER = 2 }
 
enum  Handshake_Extension_Type {
  TLSEXT_SERVER_NAME_INDICATION = 0, TLSEXT_CERT_STATUS_REQUEST = 5, TLSEXT_CERTIFICATE_TYPES = 9, TLSEXT_USABLE_ELLIPTIC_CURVES = 10,
  TLSEXT_EC_POINT_FORMATS = 11, TLSEXT_SRP_IDENTIFIER = 12, TLSEXT_SIGNATURE_ALGORITHMS = 13, TLSEXT_USE_SRTP = 14,
  TLSEXT_ALPN = 16, TLSEXT_ENCRYPT_THEN_MAC = 22, TLSEXT_EXTENDED_MASTER_SECRET = 23, TLSEXT_SESSION_TICKET = 35,
  TLSEXT_SAFE_RENEGOTIATION = 65281
}
 
enum  Handshake_Type {
  HELLO_REQUEST = 0, CLIENT_HELLO = 1, SERVER_HELLO = 2, HELLO_VERIFY_REQUEST = 3,
  NEW_SESSION_TICKET = 4, CERTIFICATE = 11, SERVER_KEX = 12, CERTIFICATE_REQUEST = 13,
  SERVER_HELLO_DONE = 14, CERTIFICATE_VERIFY = 15, CLIENT_KEX = 16, FINISHED = 20,
  CERTIFICATE_URL = 21, CERTIFICATE_STATUS = 22, HANDSHAKE_CCS = 254, HANDSHAKE_NONE = 255
}
 
enum  Record_Type {
  CHANGE_CIPHER_SPEC = 20, ALERT = 21, HANDSHAKE = 22, APPLICATION_DATA = 23,
  NO_RECORD = 256
}
 
enum  Size_Limits {
  TLS_HEADER_SIZE = 5, DTLS_HEADER_SIZE = TLS_HEADER_SIZE + 8, MAX_PLAINTEXT_SIZE = 16*1024, MAX_COMPRESSED_SIZE = MAX_PLAINTEXT_SIZE + 1024,
  MAX_CIPHERTEXT_SIZE = MAX_COMPRESSED_SIZE + 1024
}
 

Functions

template<typename T , typename Alloc >
void append_tls_length_value (std::vector< uint8_t, Alloc > &buf, const T *vals, size_t vals_size, size_t tag_size)
 
template<typename T , typename Alloc , typename Alloc2 >
void append_tls_length_value (std::vector< uint8_t, Alloc > &buf, const std::vector< T, Alloc2 > &vals, size_t tag_size)
 
template<typename Alloc >
void append_tls_length_value (std::vector< uint8_t, Alloc > &buf, const std::string &str, size_t tag_size)
 
uint16_t check_tls_cbc_padding (const uint8_t record[], size_t record_len)
 
const char * handshake_type_to_string (Handshake_Type type)
 
std::vector< uint8_t > make_hello_random (RandomNumberGenerator &rng, const Policy &policy)
 
bool operator!= (const Server_Information &a, const Server_Information &b)
 
bool operator< (const Server_Information &a, const Server_Information &b)
 
bool operator== (const Server_Information &a, const Server_Information &b)
 
size_t read_record (secure_vector< uint8_t > &readbuf, Record_Raw_Input &raw_input, Record &rec, Connection_Sequence_Numbers *sequence_numbers, get_cipherstate_fn get_cipherstate)
 
void write_record (secure_vector< uint8_t > &output, Record_Message msg, Protocol_Version version, uint64_t seq, Connection_Cipher_State *cs, RandomNumberGenerator &rng)
 

Typedef Documentation

◆ get_cipherstate_fn

typedef std::function<std::shared_ptr<Connection_Cipher_State>uint16_t)> Botan::TLS::get_cipherstate_fn

Definition at line 165 of file tls_record.h.

◆ Supported_Elliptic_Curves

Definition at line 263 of file tls_extensions.h.

Enumeration Type Documentation

◆ anonymous enum

anonymous enum
Enumerator
TLS_EMPTY_RENEGOTIATION_INFO_SCSV 
TLS_FALLBACK_SCSV 

Definition at line 27 of file msg_client_hello.cpp.

◆ Compression_Method

Enumerator
NO_COMPRESSION 
DEFLATE_COMPRESSION 

Definition at line 61 of file tls_magic.h.

◆ Connection_Side

Enumerator
CLIENT 
SERVER 

Definition at line 27 of file tls_magic.h.

◆ Handshake_Extension_Type

Enumerator
TLSEXT_SERVER_NAME_INDICATION 
TLSEXT_CERT_STATUS_REQUEST 
TLSEXT_CERTIFICATE_TYPES 
TLSEXT_USABLE_ELLIPTIC_CURVES 
TLSEXT_EC_POINT_FORMATS 
TLSEXT_SRP_IDENTIFIER 
TLSEXT_SIGNATURE_ALGORITHMS 
TLSEXT_USE_SRTP 
TLSEXT_ALPN 
TLSEXT_ENCRYPT_THEN_MAC 
TLSEXT_EXTENDED_MASTER_SECRET 
TLSEXT_SESSION_TICKET 
TLSEXT_SAFE_RENEGOTIATION 

Definition at line 26 of file tls_extensions.h.

◆ Handshake_Type

Enumerator
HELLO_REQUEST 
CLIENT_HELLO 
SERVER_HELLO 
HELLO_VERIFY_REQUEST 
NEW_SESSION_TICKET 
CERTIFICATE 
SERVER_KEX 
CERTIFICATE_REQUEST 
SERVER_HELLO_DONE 
CERTIFICATE_VERIFY 
CLIENT_KEX 
FINISHED 
CERTIFICATE_URL 
CERTIFICATE_STATUS 
HANDSHAKE_CCS 
HANDSHAKE_NONE 

Definition at line 38 of file tls_magic.h.

◆ Record_Type

Enumerator
CHANGE_CIPHER_SPEC 
ALERT 
HANDSHAKE 
APPLICATION_DATA 
NO_RECORD 

Definition at line 29 of file tls_magic.h.

◆ Size_Limits

Protocol Constants for SSL/TLS

Enumerator
TLS_HEADER_SIZE 
DTLS_HEADER_SIZE 
MAX_PLAINTEXT_SIZE 
MAX_COMPRESSED_SIZE 
MAX_CIPHERTEXT_SIZE 

Definition at line 18 of file tls_magic.h.

Function Documentation

◆ append_tls_length_value() [1/3]

template<typename T , typename Alloc >
void Botan::TLS::append_tls_length_value ( std::vector< uint8_t, Alloc > &  buf,
const T vals,
size_t  vals_size,
size_t  tag_size 
)

Helper function for encoding length-tagged vectors

Definition at line 185 of file tls_reader.h.

References Botan::TLS::TLS_Data_Reader::get_byte(), and T.

Referenced by append_tls_length_value(), Botan::TLS::Certificate_Req::Certificate_Req(), Botan::TLS::Client_Key_Exchange::Client_Key_Exchange(), Botan::TLS::New_Session_Ticket::New_Session_Ticket(), Botan::TLS::Server_Name_Indicator::serialize(), Botan::TLS::Renegotiation_Extension::serialize(), Botan::TLS::Application_Layer_Protocol_Notification::serialize(), Botan::TLS::Server_Hello::Server_Hello(), Botan::TLS::Server_Key_Exchange::Server_Key_Exchange(), and Botan::TLS::Client_Hello::update_hello_cookie().

189  {
190  const size_t T_size = sizeof(T);
191  const size_t val_bytes = T_size * vals_size;
192 
193  if(tag_size != 1 && tag_size != 2)
194  throw Invalid_Argument("append_tls_length_value: invalid tag size");
195 
196  if((tag_size == 1 && val_bytes > 255) ||
197  (tag_size == 2 && val_bytes > 65535))
198  throw Invalid_Argument("append_tls_length_value: value too large");
199 
200  for(size_t i = 0; i != tag_size; ++i)
201  buf.push_back(get_byte(sizeof(val_bytes)-tag_size+i, val_bytes));
202 
203  for(size_t i = 0; i != vals_size; ++i)
204  for(size_t j = 0; j != T_size; ++j)
205  buf.push_back(get_byte(j, vals[i]));
206  }
fe T
Definition: ge.cpp:37
uint8_t get_byte(size_t byte_num, T input)
Definition: loadstor.h:39

◆ append_tls_length_value() [2/3]

template<typename T , typename Alloc , typename Alloc2 >
void Botan::TLS::append_tls_length_value ( std::vector< uint8_t, Alloc > &  buf,
const std::vector< T, Alloc2 > &  vals,
size_t  tag_size 
)

Definition at line 209 of file tls_reader.h.

References append_tls_length_value().

212  {
213  append_tls_length_value(buf, vals.data(), vals.size(), tag_size);
214  }
void append_tls_length_value(std::vector< uint8_t, Alloc > &buf, const std::string &str, size_t tag_size)
Definition: tls_reader.h:217

◆ append_tls_length_value() [3/3]

template<typename Alloc >
void Botan::TLS::append_tls_length_value ( std::vector< uint8_t, Alloc > &  buf,
const std::string &  str,
size_t  tag_size 
)

Definition at line 217 of file tls_reader.h.

References append_tls_length_value(), and Botan::cast_char_ptr_to_uint8().

220  {
222  cast_char_ptr_to_uint8(str.data()),
223  str.size(),
224  tag_size);
225  }
void append_tls_length_value(std::vector< uint8_t, Alloc > &buf, const std::string &str, size_t tag_size)
Definition: tls_reader.h:217
const uint8_t * cast_char_ptr_to_uint8(const char *s)
Definition: mem_ops.h:120

◆ check_tls_cbc_padding()

BOTAN_TEST_API uint16_t Botan::TLS::check_tls_cbc_padding ( const uint8_t  record[],
size_t  record_len 
)

Check the TLS padding of a record

Parameters
recordthe record bits
record_lenlength of record
Returns
0 if padding is invalid, otherwise padding_bytes + 1

Definition at line 223 of file tls_cbc.cpp.

References Botan::TLS::TLS_CBC_HMAC_AEAD_Mode::block_size(), Botan::TLS::TLS_CBC_HMAC_AEAD_Mode::cbc(), Botan::TLS::TLS_CBC_HMAC_AEAD_Mode::cbc_state(), Botan::Cipher_Mode::process(), and Botan::Cipher_Mode::start().

Referenced by Botan::TLS::TLS_CBC_HMAC_AEAD_Decryption::finish(), and Botan::TLS::TLS_CBC_HMAC_AEAD_Decryption::minimum_final_size().

224  {
225  if(record_len == 0 || record_len > 0xFFFF)
226  return 0;
227 
228  const uint16_t rec16 = static_cast<uint16_t>(record_len);
229 
230  /*
231  * TLS v1.0 and up require all the padding bytes be the same value
232  * and allows up to 255 bytes.
233  */
234 
235  const uint16_t to_check = std::min<uint16_t>(256, record_len);
236  const uint8_t pad_byte = record[record_len-1];
237  const uint16_t pad_bytes = 1 + pad_byte;
238 
239  uint16_t pad_invalid = CT::is_less<uint16_t>(rec16, pad_bytes);
240 
241  for(uint16_t i = rec16 - to_check; i != rec16; ++i)
242  {
243  const uint16_t offset = rec16 - i;
244  const uint16_t in_pad_range = CT::is_lte<uint16_t>(offset, pad_bytes);
245  pad_invalid |= (in_pad_range & (record[i] ^ pad_byte));
246  }
247 
248  const uint16_t pad_invalid_mask = CT::expand_mask<uint16_t>(pad_invalid);
249  return CT::select<uint16_t>(pad_invalid_mask, 0, pad_byte + 1);
250  }

◆ handshake_type_to_string()

const char * Botan::TLS::handshake_type_to_string ( Handshake_Type  type)

Definition at line 24 of file tls_handshake_state.cpp.

References CERTIFICATE, CERTIFICATE_REQUEST, CERTIFICATE_STATUS, CERTIFICATE_URL, CERTIFICATE_VERIFY, CLIENT_HELLO, CLIENT_KEX, FINISHED, HANDSHAKE_CCS, HANDSHAKE_NONE, HELLO_REQUEST, HELLO_VERIFY_REQUEST, NEW_SESSION_TICKET, SERVER_HELLO, SERVER_HELLO_DONE, SERVER_KEX, Botan::ASN1::to_string(), Botan::TLS::Handshake_Message::type(), and Botan::TLS::Alert::UNEXPECTED_MESSAGE.

Referenced by Botan::TLS::Handshake_Message::type_string().

25  {
26  switch(type)
27  {
29  return "hello_verify_request";
30 
31  case HELLO_REQUEST:
32  return "hello_request";
33 
34  case CLIENT_HELLO:
35  return "client_hello";
36 
37  case SERVER_HELLO:
38  return "server_hello";
39 
40  case CERTIFICATE:
41  return "certificate";
42 
43  case CERTIFICATE_URL:
44  return "certificate_url";
45 
46  case CERTIFICATE_STATUS:
47  return "certificate_status";
48 
49  case SERVER_KEX:
50  return "server_key_exchange";
51 
53  return "certificate_request";
54 
55  case SERVER_HELLO_DONE:
56  return "server_hello_done";
57 
58  case CERTIFICATE_VERIFY:
59  return "certificate_verify";
60 
61  case CLIENT_KEX:
62  return "client_key_exchange";
63 
64  case NEW_SESSION_TICKET:
65  return "new_session_ticket";
66 
67  case HANDSHAKE_CCS:
68  return "change_cipher_spec";
69 
70  case FINISHED:
71  return "finished";
72 
73  case HANDSHAKE_NONE:
74  return "invalid";
75  }
76 
77  throw TLS_Exception(Alert::UNEXPECTED_MESSAGE,
78  "Unknown TLS handshake message type " + std::to_string(type));
79  }
std::string to_string(const BER_Object &obj)
Definition: asn1_obj.cpp:108
MechanismType type

◆ make_hello_random()

std::vector< uint8_t > Botan::TLS::make_hello_random ( RandomNumberGenerator rng,
const Policy policy 
)

Definition at line 32 of file msg_client_hello.cpp.

References Botan::HashFunction::create_or_throw(), Botan::TLS::Policy::include_time_in_hello_random(), Botan::RandomNumberGenerator::randomize(), and Botan::store_be().

Referenced by Botan::TLS::Client::Client(), and Botan::TLS::Server::Server().

34  {
35  std::vector<uint8_t> buf(32);
36  rng.randomize(buf.data(), buf.size());
37 
38  std::unique_ptr<HashFunction> sha256 = HashFunction::create_or_throw("SHA-256");
39  sha256->update(buf);
40  sha256->final(buf);
41 
42  if(policy.include_time_in_hello_random())
43  {
44  const uint32_t time32 = static_cast<uint32_t>(
45  std::chrono::system_clock::to_time_t(std::chrono::system_clock::now()));
46 
47  store_be(time32, buf.data());
48  }
49 
50  return buf;
51  }
void store_be(uint16_t in, uint8_t out[2])
Definition: loadstor.h:434

◆ operator!=()

bool Botan::TLS::operator!= ( const Server_Information a,
const Server_Information b 
)
inline

Definition at line 84 of file tls_server_info.h.

85  {
86  return !(a == b);
87  }

◆ operator<()

bool Botan::TLS::operator< ( const Server_Information a,
const Server_Information b 
)
inline

Definition at line 89 of file tls_server_info.h.

References Botan::TLS::Server_Information::hostname(), Botan::TLS::Server_Information::port(), and Botan::TLS::Server_Information::service().

90  {
91  if(a.hostname() != b.hostname())
92  return (a.hostname() < b.hostname());
93  if(a.service() != b.service())
94  return (a.service() < b.service());
95  if(a.port() != b.port())
96  return (a.port() < b.port());
97  return false; // equal
98  }

◆ operator==()

bool Botan::TLS::operator== ( const Server_Information a,
const Server_Information b 
)
inline

Definition at line 76 of file tls_server_info.h.

References Botan::TLS::Server_Information::hostname(), Botan::TLS::Server_Information::port(), and Botan::TLS::Server_Information::service().

77  {
78  return (a.hostname() == b.hostname()) &&
79  (a.service() == b.service()) &&
80  (a.port() == b.port());
81 
82  }

◆ read_record()

size_t Botan::TLS::read_record ( secure_vector< uint8_t > &  read_buffer,
Record_Raw_Input raw_input,
Record rec,
Connection_Sequence_Numbers sequence_numbers,
get_cipherstate_fn  get_cipherstate 
)

Decode a TLS record

Returns
zero if full message, else number of bytes still needed

Definition at line 500 of file tls_record.cpp.

References Botan::TLS::Record_Raw_Input::is_datagram().

Referenced by Botan::TLS::Channel::received_data().

505  {
506  if(raw_input.is_datagram())
507  return read_dtls_record(readbuf, raw_input, rec,
508  sequence_numbers, get_cipherstate);
509  else
510  return read_tls_record(readbuf, raw_input, rec,
511  sequence_numbers, get_cipherstate);
512  }

◆ write_record()

void Botan::TLS::write_record ( secure_vector< uint8_t > &  write_buffer,
Record_Message  rec_msg,
Protocol_Version  version,
uint64_t  msg_sequence,
Connection_Cipher_State cipherstate,
RandomNumberGenerator rng 
)

Create a TLS record

Parameters
write_bufferthe output record is placed here
rec_msgis the plaintext message
versionis the protocol version
msg_sequenceis the sequence number
cipherstateis the writing cipher state
rngis a random number generator

Definition at line 213 of file tls_record.cpp.

References Botan::TLS::Connection_Cipher_State::aead(), Botan::TLS::Connection_Cipher_State::aead_nonce(), Botan::TLS::Connection_Sequence_Numbers::already_seen(), BOTAN_ASSERT, BOTAN_ASSERT_EQUAL, Botan::TLS::Connection_Cipher_State::cbc_nonce(), Botan::TLS::Connection_Sequence_Numbers::current_read_epoch(), Botan::TLS::Alert::DECODE_ERROR, DTLS_HEADER_SIZE, Botan::Cipher_Mode::finish(), Botan::TLS::Connection_Cipher_State::format_ad(), Botan::get_byte(), Botan::TLS::Record_Raw_Input::get_consumed(), Botan::TLS::Record::get_data(), Botan::TLS::Record_Message::get_data(), Botan::TLS::Record_Raw_Input::get_data(), Botan::TLS::Record::get_protocol_version(), Botan::TLS::Record::get_sequence(), Botan::TLS::Record_Message::get_size(), Botan::TLS::Record_Raw_Input::get_size(), Botan::TLS::Record::get_type(), Botan::TLS::Record_Message::get_type(), Botan::TLS::Protocol_Version::is_datagram_protocol(), Botan::load_be< uint64_t >(), Botan::TLS::Protocol_Version::major_version(), Botan::make_uint16(), MAX_CIPHERTEXT_SIZE, Botan::TLS::Protocol_Version::minor_version(), Botan::TLS::Connection_Sequence_Numbers::next_read_sequence(), NO_RECORD, Botan::TLS::Connection_Cipher_State::nonce_bytes_from_handshake(), Botan::TLS::Connection_Cipher_State::nonce_bytes_from_record(), Botan::Cipher_Mode::output_length(), Botan::TLS::Connection_Sequence_Numbers::read_accept(), Botan::TLS::Alert::RECORD_OVERFLOW, Botan::AEAD_Mode::set_ad(), Botan::AEAD_Mode::set_associated_data_vec(), Botan::Cipher_Mode::start(), and TLS_HEADER_SIZE.

Referenced by Botan::TLS::Channel::callbacks(), Botan::TLS::Record_Raw_Input::is_datagram(), and Botan::TLS::Channel::received_data().

219  {
220  output.clear();
221 
222  output.push_back(msg.get_type());
223  output.push_back(version.major_version());
224  output.push_back(version.minor_version());
225 
226  if(version.is_datagram_protocol())
227  {
228  for(size_t i = 0; i != 8; ++i)
229  output.push_back(get_byte(i, seq));
230  }
231 
232  if(!cs) // initial unencrypted handshake records
233  {
234  append_u16_len(output, msg.get_size());
235  output.insert(output.end(), msg.get_data(), msg.get_data() + msg.get_size());
236  return;
237  }
238 
239  AEAD_Mode* aead = cs->aead();
240  std::vector<uint8_t> aad = cs->format_ad(seq, msg.get_type(), version, static_cast<uint16_t>(msg.get_size()));
241 
242  const size_t ctext_size = aead->output_length(msg.get_size());
243 
244  const size_t rec_size = ctext_size + cs->nonce_bytes_from_record();
245 
246  aead->set_ad(aad);
247 
248  const std::vector<uint8_t> nonce = cs->aead_nonce(seq, rng);
249 
250  append_u16_len(output, rec_size);
251 
252  if(cs->nonce_bytes_from_record() > 0)
253  {
254  if(cs->cbc_nonce())
255  output += nonce;
256  else
257  output += std::make_pair(&nonce[cs->nonce_bytes_from_handshake()], cs->nonce_bytes_from_record());
258  }
259 
260  const size_t header_size = output.size();
261  output += std::make_pair(msg.get_data(), msg.get_size());
262 
263  aead->start(nonce);
264  aead->finish(output, header_size);
265 
266  BOTAN_ASSERT(output.size() < MAX_CIPHERTEXT_SIZE,
267  "Produced ciphertext larger than protocol allows");
268  }
#define BOTAN_ASSERT(expr, assertion_made)
Definition: assert.h:29
uint8_t get_byte(size_t byte_num, T input)
Definition: loadstor.h:39