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

Classes

class  Application_Layer_Protocol_Notification
 
class  Certificate
 
class  Certificate_Req
 
class  Certificate_Status
 
class  Certificate_Status_Request
 
class  Certificate_Verify
 
class  Change_Cipher_Spec
 
class  Client_Hello
 
class  Client_Key_Exchange
 
class  Connection_Cipher_State
 
class  Connection_Sequence_Numbers
 
class  Datagram_Handshake_IO
 
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_State
 
class  Hello_Request
 
class  Hello_Verify_Request
 
class  New_Session_Ticket
 
class  Record
 
class  Record_Message
 
class  Record_Raw_Input
 
class  Renegotiation_Extension
 
class  Server_Hello
 
class  Server_Hello_Done
 
class  Server_Key_Exchange
 
class  Server_Name_Indicator
 
class  Session_Keys
 
class  Session_Ticket
 
class  Signature_Algorithms
 
class  SRTP_Protection_Profiles
 
class  Stream_Handshake_IO
 
class  Stream_Sequence_Numbers
 
class  Supported_Groups
 
class  Supported_Point_Formats
 
class  TLS_CBC_HMAC_AEAD_Decryption
 
class  TLS_CBC_HMAC_AEAD_Encryption
 
class  TLS_CBC_HMAC_AEAD_Mode
 
class  TLS_Data_Reader
 
class  Unknown_Extension
 

Typedefs

typedef Policy Default_Policy
 
typedef std::function< std::shared_ptr< Connection_Cipher_State >uint16_t)> get_cipherstate_fn
 

Enumerations

enum  { TLS_EMPTY_RENEGOTIATION_INFO_SCSV = 0x00FF, TLS_FALLBACK_SCSV = 0x5600 }
 
enum  Auth_Method {
  Auth_Method::RSA, Auth_Method::DSA, Auth_Method::ECDSA, Auth_Method::IMPLICIT = 0x10000,
  Auth_Method::ANONYMOUS
}
 
enum  Cipher_Algo {
  Cipher_Algo::CHACHA20_POLY1305, Cipher_Algo::AES_128_CBC_HMAC_SHA1 = 100, Cipher_Algo::AES_128_CBC_HMAC_SHA256, Cipher_Algo::AES_128_CCM,
  Cipher_Algo::AES_128_CCM_8, Cipher_Algo::AES_128_GCM, Cipher_Algo::AES_128_OCB, Cipher_Algo::AES_256_CBC_HMAC_SHA1 = 200,
  Cipher_Algo::AES_256_CBC_HMAC_SHA256, Cipher_Algo::AES_256_CBC_HMAC_SHA384, Cipher_Algo::AES_256_CCM, Cipher_Algo::AES_256_CCM_8,
  Cipher_Algo::AES_256_GCM, Cipher_Algo::AES_256_OCB, Cipher_Algo::CAMELLIA_128_CBC_HMAC_SHA1 = 300, Cipher_Algo::CAMELLIA_128_CBC_HMAC_SHA256,
  Cipher_Algo::CAMELLIA_128_GCM, Cipher_Algo::CAMELLIA_256_CBC_HMAC_SHA1 = 400, Cipher_Algo::CAMELLIA_256_CBC_HMAC_SHA256, Cipher_Algo::CAMELLIA_256_CBC_HMAC_SHA384,
  Cipher_Algo::CAMELLIA_256_GCM, Cipher_Algo::ARIA_128_GCM = 500, Cipher_Algo::ARIA_256_GCM, Cipher_Algo::DES_EDE_CBC_HMAC_SHA1 = 1000,
  Cipher_Algo::SEED_CBC_HMAC_SHA1
}
 
enum  Connection_Side { CLIENT = 1, SERVER = 2 }
 
enum  Group_Params : uint16_t {
  Group_Params::NONE = 0, Group_Params::SECP256R1 = 23, Group_Params::SECP384R1 = 24, Group_Params::SECP521R1 = 25,
  Group_Params::BRAINPOOL256R1 = 26, Group_Params::BRAINPOOL384R1 = 27, Group_Params::BRAINPOOL512R1 = 28, Group_Params::X25519 = 29,
  Group_Params::FFDHE_2048 = 256, Group_Params::FFDHE_3072 = 257, Group_Params::FFDHE_4096 = 258, Group_Params::FFDHE_6144 = 259,
  Group_Params::FFDHE_8192 = 260
}
 
enum  Handshake_Extension_Type {
  TLSEXT_SERVER_NAME_INDICATION = 0, TLSEXT_CERT_STATUS_REQUEST = 5, TLSEXT_CERTIFICATE_TYPES = 9, TLSEXT_SUPPORTED_GROUPS = 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  KDF_Algo { KDF_Algo::SHA_1, KDF_Algo::SHA_256, KDF_Algo::SHA_384 }
 
enum  Kex_Algo {
  Kex_Algo::STATIC_RSA, Kex_Algo::DH, Kex_Algo::ECDH, Kex_Algo::CECPQ1,
  Kex_Algo::SRP_SHA, Kex_Algo::PSK, Kex_Algo::DHE_PSK, Kex_Algo::ECDHE_PSK
}
 
enum  Nonce_Format { Nonce_Format::CBC_MODE, Nonce_Format::AEAD_IMPLICIT_4, Nonce_Format::AEAD_XOR_12 }
 
enum  Record_Type {
  CHANGE_CIPHER_SPEC = 20, ALERT = 21, HANDSHAKE = 22, APPLICATION_DATA = 23,
  NO_RECORD = 256
}
 
enum  Signature_Scheme : uint16_t {
  Signature_Scheme::NONE = 0x0000, Signature_Scheme::RSA_PKCS1_SHA1 = 0x0201, Signature_Scheme::RSA_PKCS1_SHA256 = 0x0401, Signature_Scheme::RSA_PKCS1_SHA384 = 0x0501,
  Signature_Scheme::RSA_PKCS1_SHA512 = 0x0601, Signature_Scheme::DSA_SHA1 = 0x0202, Signature_Scheme::DSA_SHA256 = 0x0402, Signature_Scheme::DSA_SHA384 = 0x0502,
  Signature_Scheme::DSA_SHA512 = 0x0602, Signature_Scheme::ECDSA_SHA1 = 0x0203, Signature_Scheme::ECDSA_SHA256 = 0x0403, Signature_Scheme::ECDSA_SHA384 = 0x0503,
  Signature_Scheme::ECDSA_SHA512 = 0x0603, Signature_Scheme::RSA_PSS_SHA256 = 0x0804, Signature_Scheme::RSA_PSS_SHA384 = 0x0805, Signature_Scheme::RSA_PSS_SHA512 = 0x0806,
  Signature_Scheme::EDDSA_25519 = 0x0807, Signature_Scheme::EDDSA_448 = 0x0808
}
 
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

const std::vector< Signature_Scheme > & all_signature_schemes ()
 
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)
 
Auth_Method auth_method_from_string (const std::string &str)
 
std::string auth_method_to_string (Auth_Method method)
 
class BOTAN_PUBLIC_API (2, 0) Alert final
 
uint16_t check_tls_cbc_padding (const uint8_t record[], size_t record_len)
 
Group_Params group_param_from_string (const std::string &group_name)
 
bool group_param_is_dh (Group_Params group)
 
std::string group_param_to_string (Group_Params group)
 
const char * handshake_type_to_string (Handshake_Type type)
 
std::string hash_function_of_scheme (Signature_Scheme scheme)
 
std::string kdf_algo_to_string (KDF_Algo algo)
 
Kex_Algo kex_method_from_string (const std::string &str)
 
std::string kex_method_to_string (Kex_Algo method)
 
bool key_exchange_is_psk (Kex_Algo m)
 
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)
 
std::string padding_string_for_scheme (Signature_Scheme scheme)
 
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)
 
std::string sig_scheme_to_string (Signature_Scheme scheme)
 
std::string signature_algorithm_of_scheme (Signature_Scheme scheme)
 
bool signature_scheme_is_known (Signature_Scheme scheme)
 
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

◆ Default_Policy

Definition at line 307 of file tls_policy.h.

◆ get_cipherstate_fn

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

Definition at line 167 of file tls_record.h.

Enumeration Type Documentation

◆ anonymous enum

anonymous enum
Enumerator
TLS_EMPTY_RENEGOTIATION_INFO_SCSV 
TLS_FALLBACK_SCSV 

Definition at line 28 of file msg_client_hello.cpp.

◆ Auth_Method

Enumerator
RSA 
DSA 
ECDSA 
IMPLICIT 
ANONYMOUS 

Definition at line 68 of file tls_algos.h.

68  {
69  RSA,
70  DSA,
71  ECDSA,
72 
73  // These are placed outside the encodable range
74  IMPLICIT = 0x10000,
75  ANONYMOUS
76 };

◆ Cipher_Algo

Enumerator
CHACHA20_POLY1305 
AES_128_CBC_HMAC_SHA1 
AES_128_CBC_HMAC_SHA256 
AES_128_CCM 
AES_128_CCM_8 
AES_128_GCM 
AES_128_OCB 
AES_256_CBC_HMAC_SHA1 
AES_256_CBC_HMAC_SHA256 
AES_256_CBC_HMAC_SHA384 
AES_256_CCM 
AES_256_CCM_8 
AES_256_GCM 
AES_256_OCB 
CAMELLIA_128_CBC_HMAC_SHA1 
CAMELLIA_128_CBC_HMAC_SHA256 
CAMELLIA_128_GCM 
CAMELLIA_256_CBC_HMAC_SHA1 
CAMELLIA_256_CBC_HMAC_SHA256 
CAMELLIA_256_CBC_HMAC_SHA384 
CAMELLIA_256_GCM 
ARIA_128_GCM 
ARIA_256_GCM 
DES_EDE_CBC_HMAC_SHA1 
SEED_CBC_HMAC_SHA1 

Definition at line 18 of file tls_algos.h.

18  {
20 
27 
35 
39 
44 
45  ARIA_128_GCM = 500,
47 
48  DES_EDE_CBC_HMAC_SHA1 = 1000,
50 };

◆ Connection_Side

Enumerator
CLIENT 
SERVER 

Definition at line 27 of file tls_magic.h.

◆ Group_Params

enum Botan::TLS::Group_Params : uint16_t
strong
Enumerator
NONE 
SECP256R1 
SECP384R1 
SECP521R1 
BRAINPOOL256R1 
BRAINPOOL384R1 
BRAINPOOL512R1 
X25519 
FFDHE_2048 
FFDHE_3072 
FFDHE_4096 
FFDHE_6144 
FFDHE_8192 

Definition at line 121 of file tls_algos.h.

◆ Handshake_Extension_Type

Enumerator
TLSEXT_SERVER_NAME_INDICATION 
TLSEXT_CERT_STATUS_REQUEST 
TLSEXT_CERTIFICATE_TYPES 
TLSEXT_SUPPORTED_GROUPS 
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 27 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.

◆ KDF_Algo

enum Botan::TLS::KDF_Algo
strong
Enumerator
SHA_1 
SHA_256 
SHA_384 

Definition at line 52 of file tls_algos.h.

52  {
53  SHA_1,
54  SHA_256,
55  SHA_384,
56 };
class BOTAN_PUBLIC_API(2, 0) SHA_160 final typedef SHA_160 SHA_1
Definition: sha160.h:18

◆ Kex_Algo

enum Botan::TLS::Kex_Algo
strong
Enumerator
STATIC_RSA 
DH 
ECDH 
CECPQ1 
SRP_SHA 
PSK 
DHE_PSK 
ECDHE_PSK 

Definition at line 144 of file tls_algos.h.

◆ Nonce_Format

Enumerator
CBC_MODE 
AEAD_IMPLICIT_4 
AEAD_XOR_12 

Definition at line 60 of file tls_algos.h.

◆ Record_Type

Enumerator
CHANGE_CIPHER_SPEC 
ALERT 
HANDSHAKE 
APPLICATION_DATA 
NO_RECORD 

Definition at line 29 of file tls_magic.h.

◆ Signature_Scheme

enum Botan::TLS::Signature_Scheme : uint16_t
strong
Enumerator
NONE 
RSA_PKCS1_SHA1 
RSA_PKCS1_SHA256 
RSA_PKCS1_SHA384 
RSA_PKCS1_SHA512 
DSA_SHA1 
DSA_SHA256 
DSA_SHA384 
DSA_SHA512 
ECDSA_SHA1 
ECDSA_SHA256 
ECDSA_SHA384 
ECDSA_SHA512 
RSA_PSS_SHA256 
RSA_PSS_SHA384 
RSA_PSS_SHA512 
EDDSA_25519 
EDDSA_448 

Definition at line 84 of file tls_algos.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

◆ all_signature_schemes()

BOTAN_UNSTABLE_API const std::vector< Signature_Scheme > & Botan::TLS::all_signature_schemes ( )

Definition at line 229 of file tls_algos.cpp.

230  {
231  /*
232  * This is ordered in some approximate order of preference
233  */
234  static const std::vector<Signature_Scheme> all_schemes = {
235  //Signature_Scheme::EDDSA_448,
236  //Signature_Scheme::EDDSA_25519,
237 
238  Signature_Scheme::RSA_PSS_SHA384,
239  Signature_Scheme::RSA_PSS_SHA256,
240  Signature_Scheme::RSA_PSS_SHA512,
241 
242  Signature_Scheme::RSA_PKCS1_SHA384,
243  Signature_Scheme::RSA_PKCS1_SHA512,
244  Signature_Scheme::RSA_PKCS1_SHA256,
245 
246  Signature_Scheme::ECDSA_SHA384,
247  Signature_Scheme::ECDSA_SHA512,
248  Signature_Scheme::ECDSA_SHA256,
249 
250  Signature_Scheme::DSA_SHA384,
251  Signature_Scheme::DSA_SHA512,
252  Signature_Scheme::DSA_SHA256,
253 
254  Signature_Scheme::RSA_PKCS1_SHA1,
255  Signature_Scheme::ECDSA_SHA1,
256  Signature_Scheme::DSA_SHA1,
257  };
258 
259  return all_schemes;
260  }

References DSA_SHA1, DSA_SHA256, DSA_SHA384, DSA_SHA512, ECDSA_SHA1, ECDSA_SHA256, ECDSA_SHA384, ECDSA_SHA512, RSA_PKCS1_SHA1, RSA_PKCS1_SHA256, RSA_PKCS1_SHA384, RSA_PKCS1_SHA512, RSA_PSS_SHA256, RSA_PSS_SHA384, and RSA_PSS_SHA512.

◆ 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.

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  }
size_t * tag_size
Definition: ffi.h:447
const uint8_t * buf
Definition: ffi.h:368
constexpr uint8_t get_byte(size_t byte_num, T input)
Definition: loadstor.h:39
fe T
Definition: ge.cpp:37

References buf, Botan::get_byte(), T, and tag_size.

Referenced by append_tls_length_value(), Botan::TLS::Client_Key_Exchange::Client_Key_Exchange(), Botan::TLS::Renegotiation_Extension::serialize(), Botan::TLS::Application_Layer_Protocol_Notification::serialize(), and Botan::TLS::Server_Key_Exchange::Server_Key_Exchange().

◆ 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.

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

References append_tls_length_value(), buf, and tag_size.

◆ 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.

220  {
222  cast_char_ptr_to_uint8(str.data()),
223  str.size(),
224  tag_size);
225  }
size_t * tag_size
Definition: ffi.h:447
const uint8_t * buf
Definition: ffi.h:368
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:159
const char * str
Definition: ffi.h:763

References append_tls_length_value(), buf, Botan::cast_char_ptr_to_uint8(), str, and tag_size.

◆ auth_method_from_string()

Auth_Method BOTAN_TEST_API Botan::TLS::auth_method_from_string ( const std::string &  str)

Definition at line 102 of file tls_algos.cpp.

103  {
104  if(str == "RSA")
105  return Auth_Method::RSA;
106  if(str == "DSA")
107  return Auth_Method::DSA;
108  if(str == "ECDSA")
109  return Auth_Method::ECDSA;
110  if(str == "IMPLICIT")
111  return Auth_Method::IMPLICIT;
112  if(str == "ANONYMOUS" || str == "")
113  return Auth_Method::ANONYMOUS;
114 
115  throw Invalid_Argument("Bad signature method " + str);
116  }
const char * str
Definition: ffi.h:763

References ANONYMOUS, DSA, ECDSA, IMPLICIT, RSA, and str.

◆ auth_method_to_string()

std::string BOTAN_TEST_API Botan::TLS::auth_method_to_string ( Auth_Method  method)

Definition at line 83 of file tls_algos.cpp.

84  {
85  switch(method)
86  {
87  case Auth_Method::RSA:
88  return "RSA";
89  case Auth_Method::DSA:
90  return "DSA";
91  case Auth_Method::ECDSA:
92  return "ECDSA";
93  case Auth_Method::IMPLICIT:
94  return "IMPLICIT";
95  case Auth_Method::ANONYMOUS:
96  return "ANONYMOUS";
97  }
98 
99  throw Invalid_State("auth_method_to_string unknown enum value");
100  }

References ANONYMOUS, DSA, ECDSA, IMPLICIT, and RSA.

◆ BOTAN_PUBLIC_API()

class Botan::TLS::BOTAN_PUBLIC_API ( ,
 
)
final

SSL/TLS Alert Message

Blocking TLS Client Can be used directly, or subclass to get handshake and alert notifications

Encapsulates the callbacks that a TLS channel will make which are due to channel specific operations.

Generic interface for TLS endpoint

Ciphersuite Information

TLS Handshake Message Base Class

TLS Policy Base Class Inherit and overload as desired to suit local policy concerns

Represents information known about a TLS server.

Class representing a TLS session state

Session_Manager is an interface to systems which can save session parameters for supporting session resumption.

Saving sessions is done on a best-effort basis; an implementation is allowed to drop sessions due to space constraints.

Implementations should strive to be thread safe

TLS Protocol Version

Type codes for TLS alerts

Returns
true iff this alert is non-empty
if this alert is a fatal one or not
type of alert
type of alert

Serialize an alert

Deserialize an Alert message

Parameters
bufthe serialized alert

Create a new Alert

Parameters
type_codethe type of alert
fatalspecifies if this is a fatal alert

Completes full handshake then returns

Number of bytes pending read in the plaintext buffer (bytes readable without blocking)

Blocking read, will return at least 1 byte (eventually) or else 0 if the connection is closed.

Application can override to get the handshake complete notification

Application can override to get notification of alerts

Mandatory callback: output function The channel will call this with data which needs to be sent to the peer (eg, over a socket or some other form of IPC). The array will be overwritten when the function returns so a copy must be made if the data cannot be sent immediately.

Parameters
datathe vector of data to send
sizethe number of bytes to send

Mandatory callback: process application data Called when application data record is received from the peer. Again the array is overwritten immediately after the function returns.

Parameters
seq_nothe underlying TLS/DTLS record sequence number
datathe vector containing the received record
sizethe length of the received record, in bytes

Mandatory callback: alert received Called when an alert is received from the peer If fatal, the connection is closing. If not fatal, the connection may still be closing (depending on the error and the peer).

Parameters
alertthe source of the alert

Mandatory callback: session established Called when a session is established. Throw an exception to abort the connection.

Parameters
sessionthe session descriptor
Returns
return false to prevent the session from being cached, return true to cache the session in the configured session manager

Optional callback: session activated Called when a session is active and can be written to

Optional callback with default impl: verify cert chain

Default implementation performs a standard PKIX validation and initiates network OCSP request for end-entity cert. Override to provide different behavior.

Check the certificate chain is valid up to a trusted root, and optionally (if hostname != "") that the hostname given is consistent with the leaf certificate.

This function should throw an exception derived from std::exception with an informative what() result if the certificate chain cannot be verified.

Parameters
cert_chainspecifies a certificate chain leading to a trusted root CA certificate.
ocsp_responsesthe server may have provided some
trusted_rootsthe list of trusted certificates
usagewhat this cert chain is being used for Usage_Type::TLS_SERVER_AUTH for server chains, Usage_Type::TLS_CLIENT_AUTH for client chains, Usage_Type::UNSPECIFIED for other uses
hostnamewhen authenticating a server, this is the hostname the client requested (eg via SNI). When authenticating a client, this is the server name the client is authenticating to. Empty in other cases or if no hostname was used.
policythe TLS policy associated with the session being authenticated using the certificate chain

Called by default tls_verify_cert_chain to get the timeout to use for OCSP requests. Return 0 to disable online OCSP checks.

Optional callback with default impl: sign a message

Default implementation uses PK_Signer::sign_message(). Override to provide a different approach, e.g. using an external device.

Parameters
keythe private key of the signer
rnga random number generator
emsathe encoding method to be applied to the message
formatthe signature format
msgthe input data for the signature
Returns
the signature

Optional callback with default impl: verify a message signature

Default implementation uses PK_Verifier::verify_message(). Override to provide a different approach, e.g. using an external device.

Parameters
keythe public key of the signer
emsathe encoding method to be applied to the message
formatthe signature format
msgthe input data for the signature
sigthe signature to be checked
Returns
true if the signature is valid, false otherwise

Optional callback with default impl: client side DH agreement

Default implementation uses PK_Key_Agreement::derive_key(). Override to provide a different approach, e.g. using an external device.

Parameters
modulusthe modulus p of the discrete logarithm group
generatorthe generator of the DH subgroup
peer_public_valuethe public value of the peer
policythe TLS policy associated with the session being established
rnga random number generator
Returns
a pair consisting of the agreed raw secret and our public value

Optional callback with default impl: client side ECDH agreement

Default implementation uses PK_Key_Agreement::derive_key(). Override to provide a different approach, e.g. using an external device.

Parameters
curve_namethe name of the elliptic curve
peer_public_valuethe public value of the peer
policythe TLS policy associated with the session being established
rnga random number generator
compressedthe compression preference for our public value
Returns
a pair consisting of the agreed raw secret and our public value

Optional callback: inspect handshake message Throw an exception to abort the handshake. Default simply ignores the message.

Parameters
messagethe handshake message

Optional callback for server: choose ALPN protocol ALPN (RFC 7301) works by the client sending a list of application protocols it is willing to negotiate. The server then selects which protocol to use, which is not necessarily even on the list that the client sent.

Parameters
client_protosthe vector of protocols the client is willing to negotiate
Returns
the protocol selected by the server, which need not be on the list that the client sent; if this is the empty string, the server ignores the client ALPN extension. Default return value is empty string.

Optional callback: examine/modify Extensions before sending.

Both client and server will call this callback on the Extensions object before serializing it in the client/server hellos. This allows an application to modify which extensions are sent during the handshake.

Default implementation does nothing.

Parameters
extnthe extensions
which_sidewill be CLIENT or SERVER which is the current applications role in the exchange.

Optional callback: examine peer extensions.

Both client and server will call this callback with the Extensions object after receiving it from the peer. This allows examining the Extensions, for example to implement a custom extension. It also allows an application to require that a particular extension be implemented; throw an exception from this function to abort the handshake.

Default implementation does nothing.

Parameters
extnthe extensions
which_sidewill be CLIENT if these are are the clients extensions (ie we are the server) or SERVER if these are the server extensions (we are the client).

Optional callback: decode TLS group ID

TLS uses a 16-bit field to identify ECC and DH groups. This callback handles the decoding. You only need to implement this if you are using a custom ECC or DH group (this is extremely uncommon).

Default implementation uses the standard (IETF-defined) mappings.

Optional callback: error logging. (not currently called)

Parameters
errAn error message related to this connection.

Optional callback: debug logging. (not currently called)

Parameters
whatSome hopefully informative string

Optional callback: debug logging taking a buffer. (not currently called)

Parameters
descrWhat this buffer is
valthe bytes
val_lenlength of val

Set up a new TLS session

Parameters
callbackscontains a set of callback function references required by the TLS endpoint.
session_managermanages session state
rnga random number generator
policyspecifies other connection policy information
is_datagramwhether this is a DTLS session
io_buf_szThis many bytes of memory will be preallocated for the read and write buffers. Smaller values just mean reallocations and copies are more likely.

DEPRECATED. This constructor is only provided for backward compatibility and should not be used in new implementations. (Not marked deprecated since it is only called internally, by other deprecated constructors)

Inject TLS traffic received from counterparty

Returns
a hint as the how many more bytes we need to process the current record (this may be 0 if on a record boundary)

Inject TLS traffic received from counterparty

Returns
a hint as the how many more bytes we need to process the current record (this may be 0 if on a record boundary)

Inject plaintext intended for counterparty Throws an exception if is_active() is false

Inject plaintext intended for counterparty Throws an exception if is_active() is false

Inject plaintext intended for counterparty Throws an exception if is_active() is false

Send a TLS alert message. If the alert is fatal, the internal state (keys, etc) will be reset.

Parameters
alertthe Alert to send

Send a warning alert

Send a fatal alert

Send a close notification alert

Returns
true iff the connection is active for sending application data
true iff the connection has been definitely closed
certificate chain of the peer (may be empty)

Key material export (RFC 5705)

Parameters
labela disambiguating label string
contexta per-association context value
lengththe length of the desired key in bytes
Returns
key of length bytes

Attempt to renegotiate the session

Parameters
force_full_renegotiationif true, require a full renegotiation, otherwise allow session resumption
Returns
true iff the counterparty supports the secure renegotiation extensions.

Perform a handshake timeout check. This does nothing unless this is a DTLS channel with a pending handshake state, in which case we check for timeout and potentially retransmit handshake packets.

Convert an SSL/TLS ciphersuite to algorithm fields

Parameters
suitethe ciphersuite code number
Returns
ciphersuite object

Returns true iff this suite is a known SCSV

Generate a static list of all known ciphersuites and return it.

Returns
list of all known ciphersuites

Formats the ciphersuite back to an RFC-style ciphersuite string

Returns
RFC ciphersuite string identifier
ciphersuite number
true if this is a PSK ciphersuite
true if this is an ECC ciphersuite
true if this suite uses a CBC cipher
key exchange algorithm used by this ciphersuite
signature algorithm used by this ciphersuite
symmetric cipher algorithm used by this ciphersuite
message authentication algorithm used by this ciphersuite
cipher key length used by this ciphersuite
true if this is a valid/known ciphersuite
string representation of this message type
the message type
DER representation of this message

Returns a list of ciphers we are willing to negotiate, in order of preference.

Returns a list of hash algorithms we are willing to use for signatures, in order of preference.

Returns a list of MAC algorithms we are willing to use.

Returns a list of key exchange algorithms we are willing to use, in order of preference. Allowed values: DH, empty string (representing RSA using server certificate key)

Returns a list of signature algorithms we are willing to use, in order of preference. Allowed values RSA and DSA.

The minimum signature strength we will accept Returning 80 allows RSA 1024 and SHA-1. Values larger than 80 disable SHA-1 support. Returning 110 allows RSA 2048. Return 128 to force ECC (P-256) or large (~3000 bit) RSA keys. Default is 110

Return if cert revocation info (CRL/OCSP) is required If true, validation will fail unless a valid CRL or OCSP response was examined.

Return list of ECC curves and FFDHE groups we are willing to use in order of preference.

Request that ECC curve points are sent compressed

Select a key exchange group to use, from the list of groups sent by the peer. If none are acceptable, return Group_Params::NONE

Allow renegotiation even if the counterparty doesn't support the secure renegotiation extension.

Warning
Changing this to true exposes you to injected plaintext attacks. Read RFC 5746 for background.

The protocol dictates that the first 32 bits of the random field are the current time in seconds. However this allows client fingerprinting attacks. Set to false to disable, in which case random bytes will be used instead.

Consulted by server side. If true, allows clients to initiate a new handshake

Consulted by client side. If true, allows servers to initiate a new handshake

Allow TLS v1.0

Allow TLS v1.1

Allow TLS v1.2

Allow DTLS v1.0

Allow DTLS v1.2

Return the minimum DH group size we're willing to use Default is currently 1024 (insecure), should be 2048

For ECDSA authenticated ciphersuites, the smallest key size the client will accept. This policy is currently only enforced on the server by the client.

Return the minimum ECDH group size we're willing to use for key exchange

Default 255, allowing x25519 and larger x25519 is the smallest curve we will negotiate P-521 is the largest

Return the minimum bit size we're willing to accept for RSA key exchange or server signatures.

It does not place any requirements on the size of any RSA signature(s) which were used to check the server certificate. This is only concerned with the server's public key.

Default is 2048 which is smallest RSA key size still secure for medium term security.

Minimum DSA group size, default 2048 bits

Throw an exception if you don't like the peer's key. Default impl checks the key size against minimum_rsa_bits, minimum_ecdsa_group_size, or minimum_ecdh_group_size depending on the key's type. Override if you'd like to perform some other kind of test on (or logging of) the peer's keys.

If this function returns false, unknown SRP/PSK identifiers will be rejected with an unknown_psk_identifier alert as soon as the non-existence is identified. Otherwise, a false identifier value will be used and the protocol allowed to proceed, causing the handshake to eventually fail without revealing that the username does not exist on this system.

Return the allowed lifetime of a session ticket. If 0, session tickets do not expire until the session ticket key rolls over. Expired session tickets cannot be used to resume a session.

If this returns a non-empty vector, and DTLS is negotiated, then we will also attempt to negotiate the SRTP extension from RFC 5764 using the returned values as the profile ids.

Returns
true if and only if we are willing to accept this version Default accepts TLS v1.0 and later or DTLS v1.2 or later.

Returns the more recent protocol version we are willing to use, for either TLS or DTLS depending on datagram param. Shouldn't ever need to override this unless you want to allow a user to disable use of TLS v1.2 (which is not recommended)

When offering this version, should we send a fallback SCSV? Default returns true iff version is not the latest version the policy allows, exists to allow override in case of interop problems.

Allows policy to reject any ciphersuites which are undesirable for whatever reason without having to reimplement ciphersuite_list

Returns
true if servers should choose the ciphersuite matching their highest preference, rather than the clients. Has no effect on client side.

Indicates whether the encrypt-then-MAC extension should be negotiated (RFC 7366)

Indicates whether certificate status messages should be supported

Return allowed ciphersuites, in order of preference

Returns
the default MTU for DTLS
the initial timeout for DTLS
the maximum timeout for DTLS

Convert this policy to a printable format.

Parameters
ostream to be printed to

Convert this policy to a printable format. Same as calling print on a ostringstream and reading o.str()

An empty server info - nothing known

Parameters
hostnamethe host's DNS name, if known
portspecifies the protocol port of the server (eg for TCP/UDP). Zero represents unknown.
hostnamethe host's DNS name, if known
serviceis a text string of the service type (eg "https", "tor", or "git")
portspecifies the protocol port of the server (eg for TCP/UDP). Zero represents unknown.
Returns
the host's DNS name, if known
text string of the service type, e.g., "https", "tor", or "git"
the protocol port of the server, or zero if unknown
whether the hostname is known

Uninitialized session

New session (sets session start time)

Load a session from DER representation (created by DER_encode)

Parameters
berDER representation buffer
ber_lensize of buffer in bytes

Load a session from PEM representation (created by PEM_encode)

Parameters
pemPEM representation

Encode this session data for storage

Warning
if the master secret is compromised so is the session traffic

Encrypt a session (useful for serialization or session tickets)

Decrypt a session created by encrypt

Parameters
ctextthe ciphertext returned by encrypt
ctext_sizethe size of ctext in bytes
keythe same key used by the encrypting side

Decrypt a session created by encrypt

Parameters
ctextthe ciphertext returned by encrypt
keythe same key used by the encrypting side

Encode this session data for storage

Warning
if the master secret is compromised so is the session traffic

Get the version of the saved session

Get the ciphersuite code of the saved session

Get the ciphersuite info of the saved session

Get which side of the connection the resumed session we are/were acting as.

Get the SRP identity (if sent by the client in the initial handshake)

Get the saved master secret

Get the session identifier

Get the negotiated DTLS-SRTP algorithm (RFC 5764)

Return the certificate chain of the peer (possibly empty)

Get the wall clock time this session began

Return how long this session has existed (in seconds)

Return the session ticket the server gave us

Returns
information about the TLS server

Try to load a saved session (using session ID)

Parameters
session_idthe session identifier we are trying to resume
sessionwill be set to the saved session data (if found), or not modified if not found
Returns
true if session was modified

Try to load a saved session (using info about server)

Parameters
infothe information about the server
sessionwill be set to the saved session data (if found), or not modified if not found
Returns
true if session was modified

Remove this session id from the cache, if it exists

Remove all sessions from the cache, return number of sessions deleted

Save a session on a best effort basis; the manager may not in fact be able to save the session for whatever reason; this is not an error. Caller cannot assume that calling save followed immediately by load_from_* will result in a successful lookup.

Parameters
sessionto save

Return the allowed lifetime of a session; beyond this time, sessions are not resumed. Returns 0 if unknown/no explicit expiration policy.

Returns
latest known TLS version
latest known DTLS version
Parameters
named_versiona specific named version of the protocol
majorthe major version
minorthe minor version
Returns
true if this is a valid protocol version
true if this is a protocol version we know about
major version of the protocol version
minor version of the protocol version
human-readable description of this version
true iff this is a DTLS version
true if this version supports negotiable signature algorithms
true if this version uses explicit IVs for block ciphers
true if this version uses a ciphersuite specific PRF
if this version is equal to other
if this version is not equal to other
if this version is later than other
if this version is later than or equal to other

Completes full handshake then returns

Number of bytes pending read in the plaintext buffer (bytes readable without blocking)

Blocking read, will return at least 1 byte (eventually) or else 0 if the connection is closed.

Application can override to get the handshake complete notification

Application can override to get notification of alerts

Mandatory callback: output function The channel will call this with data which needs to be sent to the peer (eg, over a socket or some other form of IPC). The array will be overwritten when the function returns so a copy must be made if the data cannot be sent immediately.

Parameters
datathe vector of data to send
sizethe number of bytes to send

Mandatory callback: process application data Called when application data record is received from the peer. Again the array is overwritten immediately after the function returns.

Parameters
seq_nothe underlying TLS/DTLS record sequence number
datathe vector containing the received record
sizethe length of the received record, in bytes

Mandatory callback: alert received Called when an alert is received from the peer If fatal, the connection is closing. If not fatal, the connection may still be closing (depending on the error and the peer).

Parameters
alertthe source of the alert

Mandatory callback: session established Called when a session is established. Throw an exception to abort the connection.

Parameters
sessionthe session descriptor
Returns
return false to prevent the session from being cached, return true to cache the session in the configured session manager

Optional callback: session activated Called when a session is active and can be written to

Optional callback with default impl: verify cert chain

Default implementation performs a standard PKIX validation and initiates network OCSP request for end-entity cert. Override to provide different behavior.

Check the certificate chain is valid up to a trusted root, and optionally (if hostname != "") that the hostname given is consistent with the leaf certificate.

This function should throw an exception derived from std::exception with an informative what() result if the certificate chain cannot be verified.

Parameters
cert_chainspecifies a certificate chain leading to a trusted root CA certificate.
ocsp_responsesthe server may have provided some
trusted_rootsthe list of trusted certificates
usagewhat this cert chain is being used for Usage_Type::TLS_SERVER_AUTH for server chains, Usage_Type::TLS_CLIENT_AUTH for client chains, Usage_Type::UNSPECIFIED for other uses
hostnamewhen authenticating a server, this is the hostname the client requested (eg via SNI). When authenticating a client, this is the server name the client is authenticating to. Empty in other cases or if no hostname was used.
policythe TLS policy associated with the session being authenticated using the certificate chain

Called by default tls_verify_cert_chain to get the timeout to use for OCSP requests. Return 0 to disable online OCSP checks.

Optional callback with default impl: sign a message

Default implementation uses PK_Signer::sign_message(). Override to provide a different approach, e.g. using an external device.

Parameters
keythe private key of the signer
rnga random number generator
emsathe encoding method to be applied to the message
formatthe signature format
msgthe input data for the signature
Returns
the signature

Optional callback with default impl: verify a message signature

Default implementation uses PK_Verifier::verify_message(). Override to provide a different approach, e.g. using an external device.

Parameters
keythe public key of the signer
emsathe encoding method to be applied to the message
formatthe signature format
msgthe input data for the signature
sigthe signature to be checked
Returns
true if the signature is valid, false otherwise

Optional callback with default impl: client side DH agreement

Default implementation uses PK_Key_Agreement::derive_key(). Override to provide a different approach, e.g. using an external device.

Parameters
modulusthe modulus p of the discrete logarithm group
generatorthe generator of the DH subgroup
peer_public_valuethe public value of the peer
policythe TLS policy associated with the session being established
rnga random number generator
Returns
a pair consisting of the agreed raw secret and our public value

Optional callback with default impl: client side ECDH agreement

Default implementation uses PK_Key_Agreement::derive_key(). Override to provide a different approach, e.g. using an external device.

Parameters
curve_namethe name of the elliptic curve
peer_public_valuethe public value of the peer
policythe TLS policy associated with the session being established
rnga random number generator
compressedthe compression preference for our public value
Returns
a pair consisting of the agreed raw secret and our public value

Optional callback: inspect handshake message Throw an exception to abort the handshake. Default simply ignores the message.

Parameters
messagethe handshake message

Optional callback for server: choose ALPN protocol ALPN (RFC 7301) works by the client sending a list of application protocols it is willing to negotiate. The server then selects which protocol to use, which is not necessarily even on the list that the client sent.

Parameters
client_protosthe vector of protocols the client is willing to negotiate
Returns
the protocol selected by the server, which need not be on the list that the client sent; if this is the empty string, the server ignores the client ALPN extension. Default return value is empty string.

Optional callback: examine/modify Extensions before sending.

Both client and server will call this callback on the Extensions object before serializing it in the client/server hellos. This allows an application to modify which extensions are sent during the handshake.

Default implementation does nothing.

Parameters
extnthe extensions
which_sidewill be CLIENT or SERVER which is the current applications role in the exchange.

Optional callback: examine peer extensions.

Both client and server will call this callback with the Extensions object after receiving it from the peer. This allows examining the Extensions, for example to implement a custom extension. It also allows an application to require that a particular extension be implemented; throw an exception from this function to abort the handshake.

Default implementation does nothing.

Parameters
extnthe extensions
which_sidewill be CLIENT if these are are the clients extensions (ie we are the server) or SERVER if these are the server extensions (we are the client).

Optional callback: decode TLS group ID

TLS uses a 16-bit field to identify ECC and DH groups. This callback handles the decoding. You only need to implement this if you are using a custom ECC or DH group (this is extremely uncommon).

Default implementation uses the standard (IETF-defined) mappings.

Optional callback: error logging. (not currently called)

Parameters
errAn error message related to this connection.

Optional callback: debug logging. (not currently called)

Parameters
whatSome hopefully informative string

Optional callback: debug logging taking a buffer. (not currently called)

Parameters
descrWhat this buffer is
valthe bytes
val_lenlength of val

Set up a new TLS session

Parameters
callbackscontains a set of callback function references required by the TLS endpoint.
session_managermanages session state
rnga random number generator
policyspecifies other connection policy information
is_datagramwhether this is a DTLS session
io_buf_szThis many bytes of memory will be preallocated for the read and write buffers. Smaller values just mean reallocations and copies are more likely.

DEPRECATED. This constructor is only provided for backward compatibility and should not be used in new implementations. (Not marked deprecated since it is only called internally, by other deprecated constructors)

Inject TLS traffic received from counterparty

Returns
a hint as the how many more bytes we need to process the current record (this may be 0 if on a record boundary)

Inject TLS traffic received from counterparty

Returns
a hint as the how many more bytes we need to process the current record (this may be 0 if on a record boundary)

Inject plaintext intended for counterparty Throws an exception if is_active() is false

Inject plaintext intended for counterparty Throws an exception if is_active() is false

Inject plaintext intended for counterparty Throws an exception if is_active() is false

Send a TLS alert message. If the alert is fatal, the internal state (keys, etc) will be reset.

Parameters
alertthe Alert to send

Send a warning alert

Send a fatal alert

Send a close notification alert

Returns
true iff the connection is active for sending application data
true iff the connection has been definitely closed
certificate chain of the peer (may be empty)

Key material export (RFC 5705)

Parameters
labela disambiguating label string
contexta per-association context value
lengththe length of the desired key in bytes
Returns
key of length bytes

Attempt to renegotiate the session

Parameters
force_full_renegotiationif true, require a full renegotiation, otherwise allow session resumption
Returns
true iff the counterparty supports the secure renegotiation extensions.

Perform a handshake timeout check. This does nothing unless this is a DTLS channel with a pending handshake state, in which case we check for timeout and potentially retransmit handshake packets.

Convert an SSL/TLS ciphersuite to algorithm fields

Parameters
suitethe ciphersuite code number
Returns
ciphersuite object

Returns true iff this suite is a known SCSV

Generate a static list of all known ciphersuites and return it.

Returns
list of all known ciphersuites

Formats the ciphersuite back to an RFC-style ciphersuite string

Returns
RFC ciphersuite string identifier
ciphersuite number
true if this is a PSK ciphersuite
true if this is an ECC ciphersuite
true if this suite uses a CBC cipher
key exchange algorithm used by this ciphersuite
signature algorithm used by this ciphersuite
symmetric cipher algorithm used by this ciphersuite
message authentication algorithm used by this ciphersuite
cipher key length used by this ciphersuite
true if this is a valid/known ciphersuite
string representation of this message type
the message type
DER representation of this message

Returns a list of ciphers we are willing to negotiate, in order of preference.

Returns a list of hash algorithms we are willing to use for signatures, in order of preference.

Returns a list of MAC algorithms we are willing to use.

Returns a list of key exchange algorithms we are willing to use, in order of preference. Allowed values: DH, empty string (representing RSA using server certificate key)

Returns a list of signature algorithms we are willing to use, in order of preference. Allowed values RSA and DSA.

The minimum signature strength we will accept Returning 80 allows RSA 1024 and SHA-1. Values larger than 80 disable SHA-1 support. Returning 110 allows RSA 2048. Return 128 to force ECC (P-256) or large (~3000 bit) RSA keys. Default is 110

Return if cert revocation info (CRL/OCSP) is required If true, validation will fail unless a valid CRL or OCSP response was examined.

Return list of ECC curves and FFDHE groups we are willing to use in order of preference.

Request that ECC curve points are sent compressed

Select a key exchange group to use, from the list of groups sent by the peer. If none are acceptable, return Group_Params::NONE

Allow renegotiation even if the counterparty doesn't support the secure renegotiation extension.

Warning
Changing this to true exposes you to injected plaintext attacks. Read RFC 5746 for background.

The protocol dictates that the first 32 bits of the random field are the current time in seconds. However this allows client fingerprinting attacks. Set to false to disable, in which case random bytes will be used instead.

Consulted by server side. If true, allows clients to initiate a new handshake

Consulted by client side. If true, allows servers to initiate a new handshake

Allow TLS v1.0

Allow TLS v1.1

Allow TLS v1.2

Allow DTLS v1.0

Allow DTLS v1.2

Return the minimum DH group size we're willing to use Default is currently 1024 (insecure), should be 2048

For ECDSA authenticated ciphersuites, the smallest key size the client will accept. This policy is currently only enforced on the server by the client.

Return the minimum ECDH group size we're willing to use for key exchange

Default 255, allowing x25519 and larger x25519 is the smallest curve we will negotiate P-521 is the largest

Return the minimum bit size we're willing to accept for RSA key exchange or server signatures.

It does not place any requirements on the size of any RSA signature(s) which were used to check the server certificate. This is only concerned with the server's public key.

Default is 2048 which is smallest RSA key size still secure for medium term security.

Minimum DSA group size, default 2048 bits

Throw an exception if you don't like the peer's key. Default impl checks the key size against minimum_rsa_bits, minimum_ecdsa_group_size, or minimum_ecdh_group_size depending on the key's type. Override if you'd like to perform some other kind of test on (or logging of) the peer's keys.

If this function returns false, unknown SRP/PSK identifiers will be rejected with an unknown_psk_identifier alert as soon as the non-existence is identified. Otherwise, a false identifier value will be used and the protocol allowed to proceed, causing the handshake to eventually fail without revealing that the username does not exist on this system.

Return the allowed lifetime of a session ticket. If 0, session tickets do not expire until the session ticket key rolls over. Expired session tickets cannot be used to resume a session.

If this returns a non-empty vector, and DTLS is negotiated, then we will also attempt to negotiate the SRTP extension from RFC 5764 using the returned values as the profile ids.

Returns
true if and only if we are willing to accept this version Default accepts TLS v1.0 and later or DTLS v1.2 or later.

Returns the more recent protocol version we are willing to use, for either TLS or DTLS depending on datagram param. Shouldn't ever need to override this unless you want to allow a user to disable use of TLS v1.2 (which is not recommended)

When offering this version, should we send a fallback SCSV? Default returns true iff version is not the latest version the policy allows, exists to allow override in case of interop problems.

Allows policy to reject any ciphersuites which are undesirable for whatever reason without having to reimplement ciphersuite_list

Returns
true if servers should choose the ciphersuite matching their highest preference, rather than the clients. Has no effect on client side.

Indicates whether the encrypt-then-MAC extension should be negotiated (RFC 7366)

Indicates whether certificate status messages should be supported

Return allowed ciphersuites, in order of preference

Returns
the default MTU for DTLS
the initial timeout for DTLS
the maximum timeout for DTLS

Convert this policy to a printable format.

Parameters
ostream to be printed to

Convert this policy to a printable format. Same as calling print on a ostringstream and reading o.str()

An empty server info - nothing known

Parameters
hostnamethe host's DNS name, if known
portspecifies the protocol port of the server (eg for TCP/UDP). Zero represents unknown.
hostnamethe host's DNS name, if known
serviceis a text string of the service type (eg "https", "tor", or "git")
portspecifies the protocol port of the server (eg for TCP/UDP). Zero represents unknown.
Returns
the host's DNS name, if known
text string of the service type, e.g., "https", "tor", or "git"
the protocol port of the server, or zero if unknown
whether the hostname is known

Uninitialized session

New session (sets session start time)

Load a session from DER representation (created by DER_encode)

Parameters
berDER representation buffer
ber_lensize of buffer in bytes

Load a session from PEM representation (created by PEM_encode)

Parameters
pemPEM representation

Encode this session data for storage

Warning
if the master secret is compromised so is the session traffic

Encrypt a session (useful for serialization or session tickets)

Decrypt a session created by encrypt

Parameters
ctextthe ciphertext returned by encrypt
ctext_sizethe size of ctext in bytes
keythe same key used by the encrypting side

Decrypt a session created by encrypt

Parameters
ctextthe ciphertext returned by encrypt
keythe same key used by the encrypting side

Encode this session data for storage

Warning
if the master secret is compromised so is the session traffic

Get the version of the saved session

Get the ciphersuite code of the saved session

Get the ciphersuite info of the saved session

Get which side of the connection the resumed session we are/were acting as.

Get the SRP identity (if sent by the client in the initial handshake)

Get the saved master secret

Get the session identifier

Get the negotiated DTLS-SRTP algorithm (RFC 5764)

Return the certificate chain of the peer (possibly empty)

Get the wall clock time this session began

Return how long this session has existed (in seconds)

Return the session ticket the server gave us

Returns
information about the TLS server

Try to load a saved session (using session ID)

Parameters
session_idthe session identifier we are trying to resume
sessionwill be set to the saved session data (if found), or not modified if not found
Returns
true if session was modified

Try to load a saved session (using info about server)

Parameters
infothe information about the server
sessionwill be set to the saved session data (if found), or not modified if not found
Returns
true if session was modified

Remove this session id from the cache, if it exists

Remove all sessions from the cache, return number of sessions deleted

Save a session on a best effort basis; the manager may not in fact be able to save the session for whatever reason; this is not an error. Caller cannot assume that calling save followed immediately by load_from_* will result in a successful lookup.

Parameters
sessionto save

Return the allowed lifetime of a session; beyond this time, sessions are not resumed. Returns 0 if unknown/no explicit expiration policy.

Returns
latest known TLS version
latest known DTLS version
Parameters
named_versiona specific named version of the protocol
majorthe major version
minorthe minor version
Returns
true if this is a valid protocol version
true if this is a protocol version we know about
major version of the protocol version
minor version of the protocol version
human-readable description of this version
true iff this is a DTLS version
true if this version supports negotiable signature algorithms
true if this version uses explicit IVs for block ciphers
true if this version uses a ciphersuite specific PRF
if this version is equal to other
if this version is not equal to other
if this version is later than other
if this version is later than or equal to other

Definition at line 21 of file tls_alert.h.

22  {
23  public:
24  /**
25  * Type codes for TLS alerts
26  */
27  enum Type {
28  CLOSE_NOTIFY = 0,
29  UNEXPECTED_MESSAGE = 10,
30  BAD_RECORD_MAC = 20,
31  DECRYPTION_FAILED = 21,
32  RECORD_OVERFLOW = 22,
33  DECOMPRESSION_FAILURE = 30,
34  HANDSHAKE_FAILURE = 40,
35  NO_CERTIFICATE = 41, // SSLv3 only
36  BAD_CERTIFICATE = 42,
37  UNSUPPORTED_CERTIFICATE = 43,
38  CERTIFICATE_REVOKED = 44,
39  CERTIFICATE_EXPIRED = 45,
40  CERTIFICATE_UNKNOWN = 46,
41  ILLEGAL_PARAMETER = 47,
42  UNKNOWN_CA = 48,
43  ACCESS_DENIED = 49,
44  DECODE_ERROR = 50,
45  DECRYPT_ERROR = 51,
46  EXPORT_RESTRICTION = 60,
47  PROTOCOL_VERSION = 70,
48  INSUFFICIENT_SECURITY = 71,
49  INTERNAL_ERROR = 80,
50  INAPPROPRIATE_FALLBACK = 86,
51  USER_CANCELED = 90,
52  NO_RENEGOTIATION = 100,
53  UNSUPPORTED_EXTENSION = 110,
54  CERTIFICATE_UNOBTAINABLE = 111,
55  UNRECOGNIZED_NAME = 112,
56  BAD_CERTIFICATE_STATUS_RESPONSE = 113,
57  BAD_CERTIFICATE_HASH_VALUE = 114,
58  UNKNOWN_PSK_IDENTITY = 115,
59 
60  NO_APPLICATION_PROTOCOL = 120, // RFC 7301
61 
62  // pseudo alert values
63  NULL_ALERT = 256
64  };
65 
66  /**
67  * @return true iff this alert is non-empty
68  */
69  bool is_valid() const { return (m_type_code != NULL_ALERT); }
70 
71  /**
72  * @return if this alert is a fatal one or not
73  */
74  bool is_fatal() const { return m_fatal; }
75 
76  /**
77  * @return type of alert
78  */
79  Type type() const { return m_type_code; }
80 
81  /**
82  * @return type of alert
83  */
84  std::string type_string() const;
85 
86  /**
87  * Serialize an alert
88  */
89  std::vector<uint8_t> serialize() const;
90 
91  /**
92  * Deserialize an Alert message
93  * @param buf the serialized alert
94  */
95  explicit Alert(const secure_vector<uint8_t>& buf);
96 
97  /**
98  * Create a new Alert
99  * @param type_code the type of alert
100  * @param fatal specifies if this is a fatal alert
101  */
102  Alert(Type type_code, bool fatal = false) :
103  m_fatal(fatal), m_type_code(type_code) {}
104 
105  Alert() : m_fatal(false), m_type_code(NULL_ALERT) {}
106  private:
107  bool m_fatal;
108  Type m_type_code;
109  };
const uint8_t * buf
Definition: ffi.h:368
MechanismType type

References buf, and type.

◆ 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 222 of file tls_cbc.cpp.

223  {
224  if(record_len == 0 || record_len > 0xFFFF)
225  return 0;
226 
227  const uint16_t rec16 = static_cast<uint16_t>(record_len);
228 
229  /*
230  * TLS v1.0 and up require all the padding bytes be the same value
231  * and allows up to 255 bytes.
232  */
233 
234  const uint16_t to_check = std::min<uint16_t>(256, static_cast<uint16_t>(record_len));
235  const uint8_t pad_byte = record[record_len-1];
236  const uint16_t pad_bytes = 1 + pad_byte;
237 
238  auto pad_invalid = CT::Mask<uint16_t>::is_lt(rec16, pad_bytes);
239 
240  for(uint16_t i = rec16 - to_check; i != rec16; ++i)
241  {
242  const uint16_t offset = rec16 - i;
243  const auto in_pad_range = CT::Mask<uint16_t>::is_lte(offset, pad_bytes);
244  const auto pad_correct = CT::Mask<uint16_t>::is_equal(record[i], pad_byte);
245  pad_invalid |= in_pad_range & ~pad_correct;
246  }
247 
248  return pad_invalid.if_not_set_return(pad_bytes);
249  }
bool BigInt BigInt size_t size_t const std::vector< uint8_t > size_t offset
Definition: numthry.h:271

References Botan::CT::Mask< T >::is_equal(), Botan::CT::Mask< T >::is_lt(), Botan::CT::Mask< T >::is_lte(), and Botan::offset.

Referenced by Botan::TLS::TLS_CBC_HMAC_AEAD_Decryption::finish().

◆ group_param_from_string()

Group_Params Botan::TLS::group_param_from_string ( const std::string &  group_name)

Definition at line 124 of file tls_algos.cpp.

125  {
126  if(group_name == "secp256r1")
127  return Group_Params::SECP256R1;
128  if(group_name == "secp384r1")
129  return Group_Params::SECP384R1;
130  if(group_name == "secp521r1")
131  return Group_Params::SECP521R1;
132  if(group_name == "brainpool256r1")
133  return Group_Params::BRAINPOOL256R1;
134  if(group_name == "brainpool384r1")
135  return Group_Params::BRAINPOOL384R1;
136  if(group_name == "brainpool512r1")
137  return Group_Params::BRAINPOOL512R1;
138  if(group_name == "x25519")
139  return Group_Params::X25519;
140 
141  if(group_name == "ffdhe/ietf/2048")
142  return Group_Params::FFDHE_2048;
143  if(group_name == "ffdhe/ietf/3072")
144  return Group_Params::FFDHE_3072;
145  if(group_name == "ffdhe/ietf/4096")
146  return Group_Params::FFDHE_4096;
147  if(group_name == "ffdhe/ietf/6144")
148  return Group_Params::FFDHE_6144;
149  if(group_name == "ffdhe/ietf/8192")
150  return Group_Params::FFDHE_8192;
151 
152  return Group_Params::NONE; // unknown
153  }

References BRAINPOOL256R1, BRAINPOOL384R1, BRAINPOOL512R1, FFDHE_2048, FFDHE_3072, FFDHE_4096, FFDHE_6144, FFDHE_8192, NONE, SECP256R1, SECP384R1, SECP521R1, and X25519.

◆ group_param_is_dh()

bool Botan::TLS::group_param_is_dh ( Group_Params  group)

Definition at line 118 of file tls_algos.cpp.

119  {
120  uint16_t group_id = static_cast<uint16_t>(group);
121  return (group_id >= 256 && group_id < 512);
122  }

Referenced by Botan::TLS::Supported_Groups::dh_groups(), Botan::TLS::Supported_Groups::ec_groups(), and Botan::TLS::Server_Key_Exchange::Server_Key_Exchange().

◆ group_param_to_string()

std::string Botan::TLS::group_param_to_string ( Group_Params  group)

Definition at line 155 of file tls_algos.cpp.

156  {
157  switch(group)
158  {
159  case Group_Params::SECP256R1:
160  return "secp256r1";
161  case Group_Params::SECP384R1:
162  return "secp384r1";
163  case Group_Params::SECP521R1:
164  return "secp521r1";
165  case Group_Params::BRAINPOOL256R1:
166  return "brainpool256r1";
167  case Group_Params::BRAINPOOL384R1:
168  return "brainpool384r1";
169  case Group_Params::BRAINPOOL512R1:
170  return "brainpool512r1";
171  case Group_Params::X25519:
172  return "x25519";
173 
174  case Group_Params::FFDHE_2048:
175  return "ffdhe/ietf/2048";
176  case Group_Params::FFDHE_3072:
177  return "ffdhe/ietf/3072";
178  case Group_Params::FFDHE_4096:
179  return "ffdhe/ietf/4096";
180  case Group_Params::FFDHE_6144:
181  return "ffdhe/ietf/6144";
182  case Group_Params::FFDHE_8192:
183  return "ffdhe/ietf/8192";
184 
185  default:
186  return "";
187  }
188  }

References BRAINPOOL256R1, BRAINPOOL384R1, BRAINPOOL512R1, FFDHE_2048, FFDHE_3072, FFDHE_4096, FFDHE_6144, FFDHE_8192, SECP256R1, SECP384R1, SECP521R1, and X25519.

◆ 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.

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:210
MechanismType type

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(), and type.

◆ hash_function_of_scheme()

std::string Botan::TLS::hash_function_of_scheme ( Signature_Scheme  scheme)

Definition at line 191 of file tls_algos.cpp.

192  {
193  switch(scheme)
194  {
195  case Signature_Scheme::DSA_SHA1:
196  case Signature_Scheme::ECDSA_SHA1:
197  case Signature_Scheme::RSA_PKCS1_SHA1:
198  return "SHA-1";
199 
200  case Signature_Scheme::DSA_SHA256:
201  case Signature_Scheme::ECDSA_SHA256:
202  case Signature_Scheme::RSA_PKCS1_SHA256:
203  case Signature_Scheme::RSA_PSS_SHA256:
204  return "SHA-256";
205 
206  case Signature_Scheme::DSA_SHA384:
207  case Signature_Scheme::ECDSA_SHA384:
208  case Signature_Scheme::RSA_PKCS1_SHA384:
209  case Signature_Scheme::RSA_PSS_SHA384:
210  return "SHA-384";
211 
212  case Signature_Scheme::DSA_SHA512:
213  case Signature_Scheme::ECDSA_SHA512:
214  case Signature_Scheme::RSA_PKCS1_SHA512:
215  case Signature_Scheme::RSA_PSS_SHA512:
216  return "SHA-512";
217 
218  case Signature_Scheme::EDDSA_25519:
219  case Signature_Scheme::EDDSA_448:
220  return "Pure";
221 
223  return "";
224  }
225 
226  throw Invalid_State("hash_function_of_scheme: Unknown signature algorithm enum");
227  }

References DSA_SHA1, DSA_SHA256, DSA_SHA384, DSA_SHA512, ECDSA_SHA1, ECDSA_SHA256, ECDSA_SHA384, ECDSA_SHA512, EDDSA_25519, EDDSA_448, NONE, RSA_PKCS1_SHA1, RSA_PKCS1_SHA256, RSA_PKCS1_SHA384, RSA_PKCS1_SHA512, RSA_PSS_SHA256, RSA_PSS_SHA384, and RSA_PSS_SHA512.

Referenced by Botan::TLS::Handshake_State::choose_sig_format(), and Botan::TLS::Handshake_State::parse_sig_format().

◆ kdf_algo_to_string()

std::string BOTAN_DLL Botan::TLS::kdf_algo_to_string ( KDF_Algo  algo)

Definition at line 14 of file tls_algos.cpp.

15  {
16  switch(algo)
17  {
18  case KDF_Algo::SHA_1:
19  return "SHA-1";
20  case KDF_Algo::SHA_256:
21  return "SHA-256";
22  case KDF_Algo::SHA_384:
23  return "SHA-384";
24  }
25 
26  throw Invalid_State("kdf_algo_to_string unknown enum value");
27  }
class BOTAN_PUBLIC_API(2, 0) SHA_160 final typedef SHA_160 SHA_1
Definition: sha160.h:18

References SHA_1, SHA_256, and SHA_384.

◆ kex_method_from_string()

Kex_Algo BOTAN_TEST_API Botan::TLS::kex_method_from_string ( const std::string &  str)

Definition at line 54 of file tls_algos.cpp.

55  {
56  if(str == "RSA")
57  return Kex_Algo::STATIC_RSA;
58 
59  if(str == "DH")
60  return Kex_Algo::DH;
61 
62  if(str == "ECDH")
63  return Kex_Algo::ECDH;
64 
65  if(str == "CECPQ1")
66  return Kex_Algo::CECPQ1;
67 
68  if(str == "SRP_SHA")
69  return Kex_Algo::SRP_SHA;
70 
71  if(str == "PSK")
72  return Kex_Algo::PSK;
73 
74  if(str == "DHE_PSK")
75  return Kex_Algo::DHE_PSK;
76 
77  if(str == "ECDHE_PSK")
78  return Kex_Algo::ECDHE_PSK;
79 
80  throw Invalid_Argument("Unknown kex method " + str);
81  }
const char * str
Definition: ffi.h:763

References CECPQ1, DH, DHE_PSK, ECDH, ECDHE_PSK, PSK, SRP_SHA, STATIC_RSA, and str.

◆ kex_method_to_string()

std::string BOTAN_TEST_API Botan::TLS::kex_method_to_string ( Kex_Algo  method)

Definition at line 29 of file tls_algos.cpp.

30  {
31  switch(method)
32  {
33  case Kex_Algo::STATIC_RSA:
34  return "RSA";
35  case Kex_Algo::DH:
36  return "DH";
37  case Kex_Algo::ECDH:
38  return "ECDH";
39  case Kex_Algo::CECPQ1:
40  return "CECPQ1";
41  case Kex_Algo::SRP_SHA:
42  return "SRP_SHA";
43  case Kex_Algo::PSK:
44  return "PSK";
45  case Kex_Algo::DHE_PSK:
46  return "DHE_PSK";
47  case Kex_Algo::ECDHE_PSK:
48  return "ECDHE_PSK";
49  }
50 
51  throw Invalid_State("kex_method_to_string unknown enum value");
52  }

References CECPQ1, DH, DHE_PSK, ECDH, ECDHE_PSK, PSK, SRP_SHA, and STATIC_RSA.

Referenced by Botan::TLS::Server_Key_Exchange::Server_Key_Exchange().

◆ key_exchange_is_psk()

bool Botan::TLS::key_exchange_is_psk ( Kex_Algo  m)
inline

Definition at line 158 of file tls_algos.h.

159  {
160  return (m == Kex_Algo::PSK ||
161  m == Kex_Algo::DHE_PSK ||
162  m == Kex_Algo::ECDHE_PSK);
163  }
BigInt const BigInt & m
Definition: bigint.h:1094

References DHE_PSK, ECDHE_PSK, Botan::m, and PSK.

Referenced by Botan::TLS::Client_Key_Exchange::Client_Key_Exchange().

◆ make_hello_random()

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

Definition at line 33 of file msg_client_hello.cpp.

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

References buf, Botan::rng, and Botan::store_be().

◆ 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  }
bool const OID & b
Definition: asn1_oid.h:109
size_t const BigInt & a
Definition: numthry.h:111

References Botan::a, and Botan::b.

◆ operator<()

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

Definition at line 89 of file tls_server_info.h.

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  }
bool const OID & b
Definition: asn1_oid.h:109
size_t const BigInt & a
Definition: numthry.h:111

References Botan::a, and Botan::b.

◆ operator==()

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

Definition at line 76 of file tls_server_info.h.

77  {
78  return (a.hostname() == b.hostname()) &&
79  (a.service() == b.service()) &&
80  (a.port() == b.port());
81 
82  }
bool const OID & b
Definition: asn1_oid.h:109
size_t const BigInt & a
Definition: numthry.h:111

References Botan::a, and Botan::b.

◆ padding_string_for_scheme()

std::string Botan::TLS::padding_string_for_scheme ( Signature_Scheme  scheme)

Definition at line 379 of file tls_algos.cpp.

380  {
381  switch(scheme)
382  {
383  case Signature_Scheme::RSA_PKCS1_SHA1:
384  return "EMSA_PKCS1(SHA-1)";
385  case Signature_Scheme::RSA_PKCS1_SHA256:
386  return "EMSA_PKCS1(SHA-256)";
387  case Signature_Scheme::RSA_PKCS1_SHA384:
388  return "EMSA_PKCS1(SHA-384)";
389  case Signature_Scheme::RSA_PKCS1_SHA512:
390  return "EMSA_PKCS1(SHA-512)";
391 
392  case Signature_Scheme::DSA_SHA1:
393  case Signature_Scheme::ECDSA_SHA1:
394  return "EMSA1(SHA-1)";
395  case Signature_Scheme::DSA_SHA256:
396  case Signature_Scheme::ECDSA_SHA256:
397  return "EMSA1(SHA-256)";
398  case Signature_Scheme::DSA_SHA384:
399  case Signature_Scheme::ECDSA_SHA384:
400  return "EMSA1(SHA-384)";
401  case Signature_Scheme::DSA_SHA512:
402  case Signature_Scheme::ECDSA_SHA512:
403  return "EMSA1(SHA-512)";
404 
405  case Signature_Scheme::RSA_PSS_SHA256:
406  return "PSSR(SHA-256,MGF1,32)";
407  case Signature_Scheme::RSA_PSS_SHA384:
408  return "PSSR(SHA-384,MGF1,48)";
409  case Signature_Scheme::RSA_PSS_SHA512:
410  return "PSSR(SHA-512,MGF1,64)";
411 
412  case Signature_Scheme::EDDSA_25519:
413  return "Pure";
414  case Signature_Scheme::EDDSA_448:
415  return "Pure";
416 
418  return "";
419  }
420 
421  throw Invalid_State("padding_string_for_scheme: Unknown signature algorithm enum");
422  }

References DSA_SHA1, DSA_SHA256, DSA_SHA384, DSA_SHA512, ECDSA_SHA1, ECDSA_SHA256, ECDSA_SHA384, ECDSA_SHA512, EDDSA_25519, EDDSA_448, NONE, RSA_PKCS1_SHA1, RSA_PKCS1_SHA256, RSA_PKCS1_SHA384, RSA_PKCS1_SHA512, RSA_PSS_SHA256, RSA_PSS_SHA384, and RSA_PSS_SHA512.

Referenced by Botan::TLS::Handshake_State::choose_sig_format(), and Botan::TLS::Handshake_State::parse_sig_format().

◆ 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 504 of file tls_record.cpp.

509  {
510  if(raw_input.is_datagram())
511  return read_dtls_record(readbuf, raw_input, rec,
512  sequence_numbers, get_cipherstate);
513  else
514  return read_tls_record(readbuf, raw_input, rec,
515  sequence_numbers, get_cipherstate);
516  }

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

◆ sig_scheme_to_string()

std::string BOTAN_UNSTABLE_API Botan::TLS::sig_scheme_to_string ( Signature_Scheme  scheme)

Definition at line 329 of file tls_algos.cpp.

330  {
331  switch(scheme)
332  {
333  case Signature_Scheme::RSA_PKCS1_SHA1:
334  return "RSA_PKCS1_SHA1";
335  case Signature_Scheme::RSA_PKCS1_SHA256:
336  return "RSA_PKCS1_SHA256";
337  case Signature_Scheme::RSA_PKCS1_SHA384:
338  return "RSA_PKCS1_SHA384";
339  case Signature_Scheme::RSA_PKCS1_SHA512:
340  return "RSA_PKCS1_SHA512";
341 
342  case Signature_Scheme::DSA_SHA1:
343  return "DSA_SHA1";
344  case Signature_Scheme::DSA_SHA256:
345  return "DSA_SHA256";
346  case Signature_Scheme::DSA_SHA384:
347  return "DSA_SHA384";
348  case Signature_Scheme::DSA_SHA512:
349  return "DSA_SHA512";
350 
351  case Signature_Scheme::ECDSA_SHA1:
352  return "ECDSA_SHA1";
353  case Signature_Scheme::ECDSA_SHA256:
354  return "ECDSA_SHA256";
355  case Signature_Scheme::ECDSA_SHA384:
356  return "ECDSA_SHA384";
357  case Signature_Scheme::ECDSA_SHA512:
358  return "ECDSA_SHA512";
359 
360  case Signature_Scheme::RSA_PSS_SHA256:
361  return "RSA_PSS_SHA256";
362  case Signature_Scheme::RSA_PSS_SHA384:
363  return "RSA_PSS_SHA384";
364  case Signature_Scheme::RSA_PSS_SHA512:
365  return "RSA_PSS_SHA512";
366 
367  case Signature_Scheme::EDDSA_25519:
368  return "EDDSA_25519";
369  case Signature_Scheme::EDDSA_448:
370  return "EDDSA_448";
371 
373  return "";
374  }
375 
376  throw Invalid_State("sig_scheme_to_string: Unknown signature algorithm enum");
377  }

References DSA_SHA1, DSA_SHA256, DSA_SHA384, DSA_SHA512, ECDSA_SHA1, ECDSA_SHA256, ECDSA_SHA384, ECDSA_SHA512, EDDSA_25519, EDDSA_448, NONE, RSA_PKCS1_SHA1, RSA_PKCS1_SHA256, RSA_PKCS1_SHA384, RSA_PKCS1_SHA512, RSA_PSS_SHA256, RSA_PSS_SHA384, and RSA_PSS_SHA512.

◆ signature_algorithm_of_scheme()

std::string Botan::TLS::signature_algorithm_of_scheme ( Signature_Scheme  scheme)

Definition at line 291 of file tls_algos.cpp.

292  {
293  switch(scheme)
294  {
295  case Signature_Scheme::RSA_PKCS1_SHA1:
296  case Signature_Scheme::RSA_PKCS1_SHA256:
297  case Signature_Scheme::RSA_PKCS1_SHA384:
298  case Signature_Scheme::RSA_PKCS1_SHA512:
299  case Signature_Scheme::RSA_PSS_SHA256:
300  case Signature_Scheme::RSA_PSS_SHA384:
301  case Signature_Scheme::RSA_PSS_SHA512:
302  return "RSA";
303 
304  case Signature_Scheme::DSA_SHA1:
305  case Signature_Scheme::DSA_SHA256:
306  case Signature_Scheme::DSA_SHA384:
307  case Signature_Scheme::DSA_SHA512:
308  return "DSA";
309 
310  case Signature_Scheme::ECDSA_SHA1:
311  case Signature_Scheme::ECDSA_SHA256:
312  case Signature_Scheme::ECDSA_SHA384:
313  case Signature_Scheme::ECDSA_SHA512:
314  return "ECDSA";
315 
316  case Signature_Scheme::EDDSA_25519:
317  return "Ed25519";
318 
319  case Signature_Scheme::EDDSA_448:
320  return "Ed448";
321 
323  return "";
324  }
325 
326  throw Invalid_State("signature_algorithm_of_scheme: Unknown signature algorithm enum");
327  }

References DSA_SHA1, DSA_SHA256, DSA_SHA384, DSA_SHA512, ECDSA_SHA1, ECDSA_SHA256, ECDSA_SHA384, ECDSA_SHA512, EDDSA_25519, EDDSA_448, NONE, RSA_PKCS1_SHA1, RSA_PKCS1_SHA256, RSA_PKCS1_SHA384, RSA_PKCS1_SHA512, RSA_PSS_SHA256, RSA_PSS_SHA384, and RSA_PSS_SHA512.

Referenced by Botan::TLS::Handshake_State::choose_sig_format(), and Botan::TLS::Handshake_State::parse_sig_format().

◆ signature_scheme_is_known()

bool Botan::TLS::signature_scheme_is_known ( Signature_Scheme  scheme)

Definition at line 262 of file tls_algos.cpp.

263  {
264  switch(scheme)
265  {
266  case Signature_Scheme::RSA_PKCS1_SHA1:
267  case Signature_Scheme::RSA_PKCS1_SHA256:
268  case Signature_Scheme::RSA_PKCS1_SHA384:
269  case Signature_Scheme::RSA_PKCS1_SHA512:
270  case Signature_Scheme::RSA_PSS_SHA256:
271  case Signature_Scheme::RSA_PSS_SHA384:
272  case Signature_Scheme::RSA_PSS_SHA512:
273 
274  case Signature_Scheme::DSA_SHA1:
275  case Signature_Scheme::DSA_SHA256:
276  case Signature_Scheme::DSA_SHA384:
277  case Signature_Scheme::DSA_SHA512:
278 
279  case Signature_Scheme::ECDSA_SHA1:
280  case Signature_Scheme::ECDSA_SHA256:
281  case Signature_Scheme::ECDSA_SHA384:
282  case Signature_Scheme::ECDSA_SHA512:
283  return true;
284 
285  default:
286  return false;
287  }
288 
289  }

References DSA_SHA1, DSA_SHA256, DSA_SHA384, DSA_SHA512, ECDSA_SHA1, ECDSA_SHA256, ECDSA_SHA384, ECDSA_SHA512, RSA_PKCS1_SHA1, RSA_PKCS1_SHA256, RSA_PKCS1_SHA384, RSA_PKCS1_SHA512, RSA_PSS_SHA256, RSA_PSS_SHA384, and RSA_PSS_SHA512.

Referenced by Botan::TLS::Handshake_State::choose_sig_format().

◆ 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 210 of file tls_record.cpp.

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

References Botan::aead, Botan::TLS::Connection_Cipher_State::aead(), Botan::TLS::Connection_Cipher_State::aead_nonce(), BOTAN_ASSERT, CBC_MODE, Botan::TLS::Connection_Cipher_State::format_ad(), Botan::get_byte(), Botan::TLS::Record_Message::get_data(), Botan::TLS::Record_Message::get_size(), Botan::TLS::Record_Message::get_type(), MAX_CIPHERTEXT_SIZE, nonce, Botan::TLS::Connection_Cipher_State::nonce_bytes_from_handshake(), Botan::TLS::Connection_Cipher_State::nonce_bytes_from_record(), Botan::TLS::Connection_Cipher_State::nonce_format(), Botan::output, and Botan::rng.