Botan 3.14.1
Crypto and TLS for C&
Botan::TLS Namespace Reference

Namespaces

namespace  detail
namespace  Internal

Classes

class  Active_Connection_State_12
class  Active_Connection_State_13
class  Alert
struct  Alert_Record
class  Application_Layer_Protocol_Notification
struct  ApplicationData_Record
class  BSI_TR_02102_2
class  Callbacks
class  Certificate_12
class  Certificate_13
class  Certificate_Authorities
class  Certificate_Request_12
class  Certificate_Request_13
class  Certificate_Status
class  Certificate_Status_12
class  Certificate_Status_Request
class  Certificate_Type_Base
class  Certificate_Verify
class  Certificate_Verify_12
class  Certificate_Verify_13
class  Change_Cipher_Spec
struct  ChangeCipherSpec_Record
class  Channel
class  Channel_Impl
class  Channel_Impl_12
class  Channel_Impl_13
class  Channel_IO
class  Cipher_State
class  Ciphersuite
class  Client
class  Client_Certificate_Type
class  Client_Hello
class  Client_Hello_12
class  Client_Hello_12_Shim
class  Client_Hello_13
class  Client_Hello_Internal
class  Client_Impl_12
class  Client_Impl_13
class  Client_Key_Exchange
class  Connection_Cipher_State
class  Connection_Sequence_Numbers
class  Datagram_Handshake_IO
class  Datagram_Policy
class  Datagram_Sequence_Numbers
class  EarlyDataIndication
class  Encrypt_then_MAC
class  Encrypted_Extensions
struct  Epoch0_SequenceNumbers
class  Extended_Master_Secret
class  Extension
class  Extensions
class  ExternalPSK
class  Finished
class  Finished_12
class  Finished_13
class  Flight
class  Group_Params
class  Handshake_Hash
class  Handshake_IO
class  Handshake_Layer
class  Handshake_Message
struct  Handshake_Record
class  Handshake_State
class  Handshake_State_13
class  Handshake_Transitions
class  Hello_Request
class  Hello_Retry_Request
class  Hello_Verify_Request
class  Hybrid_KEM_PrivateKey
class  Hybrid_KEM_PublicKey
class  Key_Share
class  Key_Update
class  New_Session_Ticket_12
class  New_Session_Ticket_13
class  NSA_Suite_B_128
class  NSA_Suite_B_192
class  Policy
class  PostHandshakeFlight
class  Protocol_Version
class  PSK
class  PSK_Key_Exchange_Modes
class  PskIdentity
class  PSKImporter
struct  Record_Content
class  Record_Header
class  Record_Layer
class  Record_Nonce
class  Record_Size_Limit
class  Record_TLS
class  Renegotiation_Extension
class  Server
class  Server_Certificate_Type
class  Server_Hello
class  Server_Hello_12
class  Server_Hello_12_Shim
class  Server_Hello_13
class  Server_Hello_Done
class  Server_Hello_Internal
class  Server_Impl_12
class  Server_Impl_13
class  Server_Information
class  Server_Key_Exchange
class  Server_Name_Indicator
class  Session
class  Session_Base
class  Session_Handle
 Helper class to embody a session handle in all protocol versions. More...
class  Session_Keys
class  Session_Manager
class  Session_Manager_Hybrid
class  Session_Manager_In_Memory
class  Session_Manager_Noop
class  Session_Manager_SQL
class  Session_Manager_SQLite
class  Session_Manager_Stateless
class  Session_Summary
class  Session_Ticket_Extension
class  Session_with_Handle
class  Signature_Algorithms
class  Signature_Algorithms_Cert
class  Signature_Scheme
class  SRTP_Protection_Profiles
class  Stream_Handshake_IO
class  Stream_Sequence_Numbers
class  Strict_Policy
class  Supported_Groups
class  Supported_Point_Formats
class  Supported_Versions
class  Text_Policy
class  TLS_CBC_HMAC_AEAD_Decryption
class  TLS_CBC_HMAC_AEAD_Encryption
class  TLS_CBC_HMAC_AEAD_Mode
class  TLS_Cipher_State
class  TLS_Data_Reader
class  TLS_Exception
class  TLS_Handshake_Layer
class  TLS_NULL_HMAC_AEAD_Decryption
class  TLS_NULL_HMAC_AEAD_Encryption
class  TLS_NULL_HMAC_AEAD_Mode
class  TLS_Record_Layer
class  Transcript_Hash_State
class  Unexpected_Message
class  Unknown_Extension

Typedefs

using BytesNeeded = size_t
using Client_Handshake_13_Message
using Client_Handshake_13_Message_Ref = detail::as_wrapped_references_t<Client_Handshake_13_Message>
using Client_Handshake_State_13
using Client_Post_Handshake_13_Message = std::variant<Key_Update>
typedef Policy Default_Policy
typedef std::function< std::shared_ptr< Connection_Cipher_State >(uint16_t)> get_cipherstate_fn
using Handshake_Message_13
using Handshake_Message_13_Ref = detail::as_wrapped_references_t<Handshake_Message_13>
using HandshakeProtocolHeader = Strong<std::array<uint8_t, 4>, struct HandshakeProtocolHeader_>
 Holds the serialization of a TLS 1.3 handshake protocol header.
using MarshalledHandshakeMessageFlight = Strong<std::vector<uint8_t>, struct MarshalledHandshakeMessageFlight_>
using Named_Group = Group_Params
using Opaque_Session_Handle = Strong<std::vector<uint8_t>, struct Opaque_Session_Handle_>
 holds an opaque session handle as used in TLS 1.3 that could be either a ticket for stateless resumption or a database handle.
using Post_Handshake_Message_13 = std::variant<New_Session_Ticket_13, Key_Update>
using PresharedKeyID = Strong<std::string, struct PresharedKeyID_>
 holds a PSK identity as used in TLS 1.3
using Record = std::variant<ChangeCipherSpec_Record, Alert_Record, Handshake_Record, ApplicationData_Record>
using SecretLoggerFn = std::function<void(std::string_view label, std::span<const uint8_t> secret)>
using SerializedHandshakeMessage = Strong<std::vector<uint8_t>, struct SerializedHandshakeMessage_>
using Server_Handshake_13_Message
using Server_Handshake_13_Message_Ref = detail::as_wrapped_references_t<Server_Handshake_13_Message>
using Server_Handshake_State_13
using Server_Post_Handshake_13_Message = std::variant<New_Session_Ticket_13, Key_Update>
using Session_ID = Strong<std::vector<uint8_t>, struct Session_ID_>
 holds a TLS 1.2 session ID for stateful resumption
using Session_Ticket = Strong<std::vector<uint8_t>, struct Session_Ticket_>
 holds a TLS 1.2 session ticket for stateless resumption
typedef PskIdentity Ticket
using Ticket_Nonce = Strong<std::vector<uint8_t>, struct Ticket_Nonce_>
 Used to derive the ticket's PSK from the resumption_master_secret.
using Transcript_Hash = std::vector<uint8_t>

Enumerations

enum class  AlertType : uint16_t {
  CloseNotify = 0 , UnexpectedMessage = 10 , BadRecordMac = 20 , DecryptionFailed = 21 ,
  RecordOverflow = 22 , DecompressionFailure = 30 , HandshakeFailure = 40 , NoCertificate = 41 ,
  BadCertificate = 42 , UnsupportedCertificate = 43 , CertificateRevoked = 44 , CertificateExpired = 45 ,
  CertificateUnknown = 46 , IllegalParameter = 47 , UnknownCA = 48 , AccessDenied = 49 ,
  DecodeError = 50 , DecryptError = 51 , ExportRestriction = 60 , ProtocolVersion = 70 ,
  InsufficientSecurity = 71 , InternalError = 80 , InappropriateFallback = 86 , UserCanceled = 90 ,
  NoRenegotiation = 100 , MissingExtension = 109 , UnsupportedExtension = 110 , CertificateUnobtainable = 111 ,
  UnrecognizedName = 112 , BadCertificateStatusResponse = 113 , BadCertificateHashValue = 114 , UnknownPSKIdentity = 115 ,
  CertificateRequired = 116 , GeneralError = 117 , NoApplicationProtocol = 120 , None = 256 ,
  CLOSE_NOTIFY = CloseNotify , NO_APPLICATION_PROTOCOL = NoApplicationProtocol , PROTOCOL_VERSION = ProtocolVersion
}
enum class  Auth_Method : uint32_t { RSA = 0 , ECDSA = 1 , UNDEFINED = 2 , IMPLICIT = 0x10000 }
enum class  Certificate_Type : uint8_t { X509 = 0 , RawPublicKey = 2 }
enum class  Cipher_Algo : uint8_t {
  CHACHA20_POLY1305 , AES_128_GCM , AES_256_GCM , AES_256_OCB ,
  CAMELLIA_128_GCM , CAMELLIA_256_GCM , ARIA_128_GCM , ARIA_256_GCM ,
  AES_128_CCM , AES_256_CCM , AES_128_CCM_8 , AES_256_CCM_8 ,
  AES_128_CBC_HMAC_SHA1 , AES_128_CBC_HMAC_SHA256 , AES_256_CBC_HMAC_SHA1 , AES_256_CBC_HMAC_SHA256 ,
  AES_256_CBC_HMAC_SHA384 , DES_EDE_CBC_HMAC_SHA1
}
enum class  Connection_Side : uint8_t { Client = 1 , Server = 2 , CLIENT = Client , SERVER = Server }
enum class  Extension_Code : uint16_t {
  ServerNameIndication = 0 , CertificateStatusRequest = 5 , SupportedGroups = 10 , EcPointFormats = 11 ,
  SignatureAlgorithms = 13 , CertSignatureAlgorithms = 50 , UseSrtp = 14 , ApplicationLayerProtocolNegotiation = 16 ,
  ClientCertificateType = 19 , ServerCertificateType = 20 , Padding = 21 , EncryptThenMac = 22 ,
  ExtendedMasterSecret = 23 , RecordSizeLimit = 28 , SessionTicket = 35 , SupportedVersions = 43 ,
  PresharedKey = 41 , EarlyData = 42 , Cookie = 44 , PskKeyExchangeModes = 45 ,
  CertificateAuthorities = 47 , KeyShare = 51 , SafeRenegotiation = 65281
}
enum class  Group_Params_Code : uint16_t {
  NONE = 0 , SECP256R1 = 23 , SECP384R1 = 24 , SECP521R1 = 25 ,
  BRAINPOOL256R1 = 26 , BRAINPOOL384R1 = 27 , BRAINPOOL512R1 = 28 , X25519 = 29 ,
  X448 = 30 , BRAINPOOL256R1TLS13 = 31 , BRAINPOOL384R1TLS13 = 32 , BRAINPOOL512R1TLS13 = 33 ,
  FFDHE_2048 = 256 , FFDHE_3072 = 257 , FFDHE_4096 = 258 , FFDHE_6144 = 259 ,
  FFDHE_8192 = 260 , ML_KEM_512 = 0x0200 , ML_KEM_768 = 0x0201 , ML_KEM_1024 = 0x0202 ,
  eFRODOKEM_640_SHAKE_OQS = 0xFE03 , eFRODOKEM_976_SHAKE_OQS = 0xFE09 , eFRODOKEM_1344_SHAKE_OQS = 0xFE0E , eFRODOKEM_640_AES_OQS = 0xFE00 ,
  eFRODOKEM_976_AES_OQS = 0xFE06 , eFRODOKEM_1344_AES_OQS = 0xFE0C , HYBRID_SECP256R1_ML_KEM_768 = 0x11EB , HYBRID_SECP384R1_ML_KEM_1024 = 0x11ED ,
  HYBRID_X25519_ML_KEM_768 = 0x11EC , HYBRID_X25519_eFRODOKEM_640_SHAKE_OQS = 0xFE05 , HYBRID_X25519_eFRODOKEM_640_AES_OQS = 0xFE02 , HYBRID_X448_eFRODOKEM_976_SHAKE_OQS = 0xFE0B ,
  HYBRID_X448_eFRODOKEM_976_AES_OQS = 0xFE08 , HYBRID_SECP256R1_eFRODOKEM_640_SHAKE_OQS = 0xFE04 , HYBRID_SECP256R1_eFRODOKEM_640_AES_OQS = 0xFE01 , HYBRID_SECP384R1_eFRODOKEM_976_SHAKE_OQS = 0xFE0A ,
  HYBRID_SECP384R1_eFRODOKEM_976_AES_OQS = 0xFE07 , HYBRID_SECP521R1_eFRODOKEM_1344_SHAKE_OQS = 0xFE0F , HYBRID_SECP521R1_eFRODOKEM_1344_AES_OQS = 0xFE0D
}
enum class  Handshake_Type : uint8_t {
  HelloRequest = 0 , ClientHello = 1 , ServerHello = 2 , HelloVerifyRequest = 3 ,
  NewSessionTicket = 4 , EndOfEarlyData = 5 , EncryptedExtensions = 8 , Certificate = 11 ,
  ServerKeyExchange = 12 , CertificateRequest = 13 , ServerHelloDone = 14 , CertificateVerify = 15 ,
  ClientKeyExchange = 16 , Finished = 20 , CertificateUrl = 21 , CertificateStatus = 22 ,
  KeyUpdate = 24 , HandshakeCCS = 252 , HelloRetryRequest = 253 , MessageHash = 254 ,
  None = 255
}
enum class  KDF_Algo : uint8_t { SHA_1 , SHA_256 , SHA_384 }
enum class  Kex_Algo : uint8_t {
  STATIC_RSA , DH , ECDH , PSK ,
  ECDHE_PSK , DHE_PSK , KEM , KEM_PSK ,
  HYBRID , HYBRID_PSK , UNDEFINED
}
enum class  Nonce_Format : uint8_t { CBC_MODE , AEAD_IMPLICIT_4 , AEAD_XOR_12 , NULL_CIPHER }
enum class  PSK_Key_Exchange_Mode : uint8_t { PSK_KE = 0 , PSK_DHE_KE = 1 }
enum class  Record_Type : uint8_t {
  Invalid = 0 , ChangeCipherSpec = 20 , Alert = 21 , Handshake = 22 ,
  ApplicationData = 23 , Heartbeat = 24
}
enum  Size_Limits : size_t {
  TLS_HEADER_SIZE = 5 , DTLS_HEADER_SIZE = TLS_HEADER_SIZE + 8 , TLS_HANDSHAKE_HEADER_LENGTH = 4 , MAX_PLAINTEXT_SIZE = 16 * 1024 ,
  MAX_COMPRESSED_SIZE = MAX_PLAINTEXT_SIZE + 1024 , MAX_CIPHERTEXT_SIZE = MAX_COMPRESSED_SIZE + 1024 , MAX_AEAD_EXPANSION_SIZE_TLS13 = 255 , MAX_CIPHERTEXT_SIZE_TLS13 = MAX_PLAINTEXT_SIZE + MAX_AEAD_EXPANSION_SIZE_TLS13 + 1
}
enum class  TLS_Flavor : bool { TLS , DTLS }
enum class  Version_Code : uint16_t {
  TLS_V10 = 0x0301 , TLS_V11 = 0x0302 , TLS_V12 = 0x0303 , TLS_V13 = 0x0304 ,
  DTLS_V10 = 0xFEFF , DTLS_V12 = 0xFEFD , DTLS_V13 = 0xFEFC
}

Functions

Record annotate_record_type (Record_Content &&record)
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 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>
void append_tls_length_value (std::vector< uint8_t, Alloc > &buf, std::span< const T > vals, size_t tag_size)
template<typename Alloc>
void append_tls_length_value (std::vector< uint8_t, Alloc > &buf, std::string_view str, size_t tag_size)
TLS_Cipher_State * as_tls_cipher_state (Cipher_State *cs)
Auth_Method auth_method_from_string (std::string_view str)
std::string auth_method_to_string (Auth_Method method)
std::vector< uint8_t > calculate_cookie (std::span< const uint8_t > client_hello_bits, std::string_view client_identity, std::span< const uint8_t > cookie_secret)
Certificate_Type certificate_type_from_string (const std::string &type_str)
std::string certificate_type_to_string (Certificate_Type type)
uint16_t check_tls_cbc_padding (const uint8_t record[], size_t record_len)
std::vector< std::string > filter_signature_schemes (const std::vector< Signature_Scheme > &schemes, const Protocol_Version &version)
bool group_may_be_ecc (Group_Params group)
bool group_usable_in_version (Group_Params group, Protocol_Version version)
std::vector< Group_Params > groups_usable_in_version (std::span< const Group_Params > groups, Protocol_Version version)
const char * handshake_type_to_string (Handshake_Type type)
std::string kdf_algo_to_string (KDF_Algo algo)
Kex_Algo kex_method_from_string (std::string_view str)
std::string kex_method_to_string (Kex_Algo method)
bool key_exchange_is_psk (Kex_Algo m)
std::unique_ptr< Extension > make_certificate_status_request (TLS_Data_Reader &reader, uint16_t extension_size, Handshake_Type message_type, Connection_Side from)
std::vector< uint8_t > make_hello_random (RandomNumberGenerator &rng, Callbacks &cb, const Policy &policy)
std::vector< uint8_t > make_server_hello_random (RandomNumberGenerator &rng, Protocol_Version offered_version, Callbacks &cb, const Policy &policy, TLS_Flavor flavor)
bool operator!= (const Server_Information &a, const Server_Information &b)
bool operator< (const Server_Information &a, const Server_Information &b)
auto operator< (const Session_ID &id1, const Session_ID &id2)
bool operator== (const Server_Information &a, const Server_Information &b)
Record_Header read_record (TLS_Flavor flavor, secure_vector< uint8_t > &readbuf, const uint8_t input[], size_t input_len, size_t &consumed, secure_vector< uint8_t > &recbuf, Connection_Sequence_Numbers *sequence_numbers, const get_cipherstate_fn &get_cipherstate, bool allow_epoch0_restart)
std::vector< AlgorithmIdentifier > to_algorithm_identifiers (const std::vector< Signature_Scheme > &schemes)
void write_record (secure_vector< uint8_t > &output, Record_Type record_type, Protocol_Version version, uint64_t record_sequence, const uint8_t *message, size_t message_len, Connection_Cipher_State &cs, RandomNumberGenerator &rng)
void write_unencrypted_record (secure_vector< uint8_t > &output, Record_Type record_type, Protocol_Version version, uint64_t record_sequence, const uint8_t *message, size_t message_len)

Variables

constexpr uint64_t DOWNGRADE_TLS11 = 0x444F574E47524400
constexpr uint64_t DOWNGRADE_TLS12 = 0x444F574E47524401
constexpr std::array< uint8_t, 32 > HELLO_RETRY_REQUEST_MARKER

Detailed Description

Cipher_State state machine adapted from RFC 8446 7.1.

                                0
                                |
                                v
                      PSK ->  HKDF-Extract = Early Secret
                                |
                                +-----> Derive-Secret(., "ext binder" | "res binder" | "imp binder", "")
                                |                     = binder_key
                         STATE PSK BINDER

This state is reached by constructing the Cipher_State using init_with_psk(). The state can then be further advanced using advance_with_client_hello() once the initial Client Hello is fully generated. | +-----> Derive-Secret(., "c e traffic", ClientHello) | = client_early_traffic_secret | +-----> Derive-Secret(., "e exp master", ClientHello) | = early_exporter_master_secret v Derive-Secret(., "derived", "") |

  • STATE EARLY TRAFFIC This state is reached by calling advance_with_client_hello(). In this state the early data traffic secrets are available. TODO: implement early data. The state can then be further advanced using advance_with_server_hello().
  • | v (EC)DHE -> HKDF-Extract = Handshake Secret | +-----> Derive-Secret(., "c hs traffic", | ClientHello...ServerHello) | = client_handshake_traffic_secret | +-----> Derive-Secret(., "s hs traffic", | ClientHello...ServerHello) | = server_handshake_traffic_secret v Derive-Secret(., "derived", "") |
  • STATE HANDSHAKE TRAFFIC This state is reached by constructing Cipher_State using init_with_server_hello() or advance_with_server_hello(). In this state the handshake traffic secrets are available. The state can then be further advanced using advance_with_server_finished().
  • | v 0 -> HKDF-Extract = Master Secret | +-----> Derive-Secret(., "c ap traffic", | ClientHello...server Finished) | = client_application_traffic_secret_0 | +-----> Derive-Secret(., "s ap traffic", | ClientHello...server Finished) | = server_application_traffic_secret_0 | +-----> Derive-Secret(., "exp master", | ClientHello...server Finished) | = exporter_master_secret
  • STATE SERVER APPLICATION TRAFFIC This state is reached by calling advance_with_server_finished(). It allows the server to send application traffic and the client to receive it. The opposite direction is not yet possible in this state. The state can then be further advanced using advance_with_client_finished().
  • | +-----> Derive-Secret(., "res master", ClientHello...client Finished) = resumption_master_secret STATE COMPLETED Once this state is reached the handshake is finished, both client and server can exchange application data and no further cipher state advances are possible.

TLS 1.3 Preshared Key identity and importer (C) 2023 Jack Lloyd 2023 René Meusel - Rohde & Schwarz Cybersecurity 2023 Fabian Albert, René Meusel - Rohde & Schwarz Cybersecurity 2025,2026 Jack Lloyd

Botan is released under the Simplified BSD License (see license.txt)

Wrapper type for a TLS 1.3 session ticket (C) 2023 Jack Lloyd 2023 René Meusel - Rohde & Schwarz Cybersecurity

Botan is released under the Simplified BSD License (see license.txt)

TLS 1.3 Strong Type Wrappers (C) 2026 Jack Lloyd 2026 Amos Treiber, René Meusel - Rohde & Schwarz Networks and Cybersecurity

Botan is released under the Simplified BSD License (see license.txt)

Composite key pair that exposes the Public/Private key API but combines multiple key agreement schemes into a hybrid algorithm.

(C) 2023 Jack Lloyd 2023 Fabian Albert, René Meusel - Rohde & Schwarz Cybersecurity

Botan is released under the Simplified BSD License (see license.txt)

TLS Session Manger base class implementations (C) 2011-2023 Jack Lloyd 2022-2023 René Meusel - Rohde & Schwarz Cybersecurity

Botan is released under the Simplified BSD License (see license.txt)

Hybrid Session Manager that emits both IDs and Tickets (C) 2023 Jack Lloyd 2023 René Meusel - Rohde & Schwarz Cybersecurity

Botan is released under the Simplified BSD License (see license.txt)

TLS Session Management (C) 2011,2012 Jack Lloyd 2023 René Meusel - Rohde & Schwarz Cybersecurity

Botan is released under the Simplified BSD License (see license.txt)

TLS Stateless Session Manager for stateless servers (C) 2023 Jack Lloyd 2023 René Meusel - Rohde & Schwarz Cybersecurity

Botan is released under the Simplified BSD License (see license.txt)

Typedef Documentation

◆ BytesNeeded

using Botan::TLS::BytesNeeded = size_t

Definition at line 18 of file tls_types_13.h.

◆ Client_Handshake_13_Message

◆ Client_Handshake_13_Message_Ref

◆ Client_Handshake_State_13

Initial value:
std::variant< Server_Hello_13, Server_Hello_12_Shim, Hello_Retry_Request, Encrypted_Extensions, Certificate_13, Certificate_Request_13, Certificate_Verify_13, Finished_13 > Server_Handshake_13_Message
std::variant< Client_Hello_13, Client_Hello_12_Shim, Certificate_13, Certificate_Verify_13, Finished_13 > Client_Handshake_13_Message
std::variant< New_Session_Ticket_13, Key_Update > Server_Post_Handshake_13_Message

Definition at line 201 of file tls_handshake_state_13.h.

◆ Client_Post_Handshake_13_Message

Definition at line 467 of file tls_messages_13.h.

◆ Default_Policy

Definition at line 724 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 180 of file tls_record.h.

◆ Handshake_Message_13

◆ Handshake_Message_13_Ref

◆ HandshakeProtocolHeader

using Botan::TLS::HandshakeProtocolHeader = Strong<std::array<uint8_t, 4>, struct HandshakeProtocolHeader_>

Holds the serialization of a TLS 1.3 handshake protocol header.

Definition at line 27 of file tls_types_13.h.

◆ MarshalledHandshakeMessageFlight

using Botan::TLS::MarshalledHandshakeMessageFlight = Strong<std::vector<uint8_t>, struct MarshalledHandshakeMessageFlight_>

Holds the serialization of a TLS 1.3 handshake message flight containing multiple handshake messages along with their handshake protocol headers.

Definition at line 31 of file tls_types_13.h.

◆ Named_Group

Definition at line 432 of file tls_extensions.h.

◆ Opaque_Session_Handle

using Botan::TLS::Opaque_Session_Handle = Strong<std::vector<uint8_t>, struct Opaque_Session_Handle_>

holds an opaque session handle as used in TLS 1.3 that could be either a ticket for stateless resumption or a database handle.

Definition at line 29 of file tls_session_id.h.

◆ Post_Handshake_Message_13

◆ PresharedKeyID

using Botan::TLS::PresharedKeyID = Strong<std::string, struct PresharedKeyID_>

holds a PSK identity as used in TLS 1.3

Definition at line 28 of file tls_psk_13.h.

◆ Record

◆ SecretLoggerFn

using Botan::TLS::SecretLoggerFn = std::function<void(std::string_view label, std::span<const uint8_t> secret)>

Definition at line 20 of file tls_types_13.h.

◆ SerializedHandshakeMessage

using Botan::TLS::SerializedHandshakeMessage = Strong<std::vector<uint8_t>, struct SerializedHandshakeMessage_>

Holds the serialization of a single TLS 1.3 handshake message without the handshake protocol header.

Definition at line 24 of file tls_types_13.h.

◆ Server_Handshake_13_Message

◆ Server_Handshake_13_Message_Ref

◆ Server_Handshake_State_13

◆ Server_Post_Handshake_13_Message

◆ Session_ID

using Botan::TLS::Session_ID = Strong<std::vector<uint8_t>, struct Session_ID_>

holds a TLS 1.2 session ID for stateful resumption

Definition at line 22 of file tls_session_id.h.

◆ Session_Ticket

using Botan::TLS::Session_Ticket = Strong<std::vector<uint8_t>, struct Session_Ticket_>

holds a TLS 1.2 session ticket for stateless resumption

Definition at line 25 of file tls_session_id.h.

◆ Ticket

Botan 3.0.0 used the class name "Ticket". In Botan 3.1.0 we decided to re-name it to the more generic term "PskIdentity" to better reflect its dual use case for resumption and externally provided PSKs.

Definition at line 77 of file tls_psk_13.h.

◆ Ticket_Nonce

using Botan::TLS::Ticket_Nonce = Strong<std::vector<uint8_t>, struct Ticket_Nonce_>

Used to derive the ticket's PSK from the resumption_master_secret.

Definition at line 108 of file tls_magic.h.

◆ Transcript_Hash

using Botan::TLS::Transcript_Hash = std::vector<uint8_t>

Definition at line 105 of file tls_magic.h.

Enumeration Type Documentation

◆ AlertType

enum class Botan::TLS::AlertType : uint16_t
strong

Type codes for TLS alerts

The enumeration value matches the wire encoding

Enumerator
CloseNotify 
UnexpectedMessage 
BadRecordMac 
DecryptionFailed 
RecordOverflow 
DecompressionFailure 
HandshakeFailure 
NoCertificate 
BadCertificate 
UnsupportedCertificate 
CertificateRevoked 
CertificateExpired 
CertificateUnknown 
IllegalParameter 
UnknownCA 
AccessDenied 
DecodeError 
DecryptError 
ExportRestriction 
ProtocolVersion 
InsufficientSecurity 
InternalError 
InappropriateFallback 
UserCanceled 
NoRenegotiation 
MissingExtension 
UnsupportedExtension 
CertificateUnobtainable 
UnrecognizedName 
BadCertificateStatusResponse 
BadCertificateHashValue 
UnknownPSKIdentity 
CertificateRequired 
GeneralError 
NoApplicationProtocol 
None 
CLOSE_NOTIFY 
NO_APPLICATION_PROTOCOL 
PROTOCOL_VERSION 

Definition at line 21 of file tls_alert.h.

21 : uint16_t {
22 CloseNotify = 0,
24 BadRecordMac = 20,
25 DecryptionFailed = 21, // Not specified in TLS 1.3 (RFC 9846)
26 RecordOverflow = 22,
27 DecompressionFailure = 30, // Not specified in TLS 1.3 (RFC 9846)
29 NoCertificate = 41, // SSLv3 only
30 BadCertificate = 42,
36 UnknownCA = 48,
37 AccessDenied = 49,
38 DecodeError = 50,
39 DecryptError = 51,
40 ExportRestriction = 60, // Not specified in TLS 1.3 (RFC 9846)
41 ProtocolVersion = 70,
43 InternalError = 80,
45 UserCanceled = 90,
46 NoRenegotiation = 100, // Not specified in TLS 1.3 (RFC 9846)
47 MissingExtension = 109,
49 CertificateUnobtainable = 111, // Not specified in TLS 1.3 (RFC 9846)
50 UnrecognizedName = 112,
52 BadCertificateHashValue = 114, // Not specified in TLS 1.3 (RFC 9846)
55 GeneralError = 117,
57
58 // pseudo alert values
59 None = 256,
60
61 // Compat enum variants, will be removed in a future major release
62 // TODO(Botan4): remove these
63 CLOSE_NOTIFY BOTAN_DEPRECATED("Use CloseNotify") = CloseNotify,
65 PROTOCOL_VERSION BOTAN_DEPRECATED("Use ProtocolVersion") = ProtocolVersion,
66};
#define BOTAN_DEPRECATED(msg)
Definition api.h:73

◆ Auth_Method

enum class Botan::TLS::Auth_Method : uint32_t
strong
Enumerator
RSA 
ECDSA 
UNDEFINED 
IMPLICIT 

Definition at line 63 of file tls_algos.h.

63 : uint32_t {
64 RSA = 0,
65 ECDSA = 1,
66
67 // To support TLS 1.3 ciphersuites, which do not determine the auth method
68 UNDEFINED = 2,
69
70 // These are placed outside the encodable range
71 IMPLICIT = 0x10000
72};

◆ Certificate_Type

enum class Botan::TLS::Certificate_Type : uint8_t
strong
Enumerator
X509 
RawPublicKey 

Definition at line 289 of file tls_algos.h.

◆ Cipher_Algo

enum class Botan::TLS::Cipher_Algo : uint8_t
strong
Enumerator
CHACHA20_POLY1305 
AES_128_GCM 
AES_256_GCM 
AES_256_OCB 
CAMELLIA_128_GCM 
CAMELLIA_256_GCM 
ARIA_128_GCM 
ARIA_256_GCM 
AES_128_CCM 
AES_256_CCM 
AES_128_CCM_8 
AES_256_CCM_8 
AES_128_CBC_HMAC_SHA1 
AES_128_CBC_HMAC_SHA256 
AES_256_CBC_HMAC_SHA1 
AES_256_CBC_HMAC_SHA256 
AES_256_CBC_HMAC_SHA384 
DES_EDE_CBC_HMAC_SHA1 

Definition at line 18 of file tls_algos.h.

18 : uint8_t {
20
23
25
28
31
36
42
44};

◆ Connection_Side

enum class Botan::TLS::Connection_Side : uint8_t
strong
Enumerator
Client 
Server 
CLIENT 
SERVER 

Definition at line 50 of file tls_magic.h.

50 : uint8_t {
51 Client = 1,
52 Server = 2,
53
54 CLIENT BOTAN_DEPRECATED("Use Connection_Side::Client") = Client,
55 SERVER BOTAN_DEPRECATED("Use Connection_Side::Server") = Server,
56};

◆ Extension_Code

enum class Botan::TLS::Extension_Code : uint16_t
strong
Enumerator
ServerNameIndication 
CertificateStatusRequest 
SupportedGroups 
EcPointFormats 
SignatureAlgorithms 
CertSignatureAlgorithms 
UseSrtp 
ApplicationLayerProtocolNegotiation 
ClientCertificateType 
ServerCertificateType 
Padding 
EncryptThenMac 
ExtendedMasterSecret 
RecordSizeLimit 
SessionTicket 
SupportedVersions 
PresharedKey 
EarlyData 
Cookie 
PskKeyExchangeModes 
CertificateAuthorities 
KeyShare 
SafeRenegotiation 

Definition at line 39 of file tls_extensions.h.

39 : uint16_t {
42
43 SupportedGroups = 10,
44 EcPointFormats = 11, // TLS 1.2 exclusive
47 UseSrtp = 14,
49
50 // SignedCertificateTimestamp = 18, // NYI
51
52 // RFC 7250 (Raw Public Keys in TLS)
55
56 Padding = 21, // RFC 7685; not implemented but recognized so it can be
57 // explicitly carved out of strict-mutation checks.
58
59 EncryptThenMac = 22, // TLS 1.2 exclusive
60 ExtendedMasterSecret = 23, // TLS 1.2 exclusive
61
62 RecordSizeLimit = 28,
63
64 SessionTicket = 35, // TLS 1.2 exclusive
65
67
68 PresharedKey = 41, // TLS 1.3 exclusive
69 EarlyData = 42, // TLS 1.3 exclusive
70 Cookie = 44, // TLS 1.3 exclusive
71 PskKeyExchangeModes = 45, // TLS 1.3 exclusive
72 CertificateAuthorities = 47, // TLS 1.3 exclusive
73 KeyShare = 51, // TLS 1.3 exclusive
74
75 SafeRenegotiation = 65281, // TLS 1.2 exclusive
76};

◆ Group_Params_Code

enum class Botan::TLS::Group_Params_Code : uint16_t
strong
Enumerator
NONE 
SECP256R1 
SECP384R1 
SECP521R1 
BRAINPOOL256R1 
BRAINPOOL384R1 
BRAINPOOL512R1 
X25519 
X448 
BRAINPOOL256R1TLS13 
BRAINPOOL384R1TLS13 
BRAINPOOL512R1TLS13 
FFDHE_2048 
FFDHE_3072 
FFDHE_4096 
FFDHE_6144 
FFDHE_8192 
ML_KEM_512 
ML_KEM_768 
ML_KEM_1024 
eFRODOKEM_640_SHAKE_OQS 
eFRODOKEM_976_SHAKE_OQS 
eFRODOKEM_1344_SHAKE_OQS 
eFRODOKEM_640_AES_OQS 
eFRODOKEM_976_AES_OQS 
eFRODOKEM_1344_AES_OQS 
HYBRID_SECP256R1_ML_KEM_768 
HYBRID_SECP384R1_ML_KEM_1024 
HYBRID_X25519_ML_KEM_768 
HYBRID_X25519_eFRODOKEM_640_SHAKE_OQS 
HYBRID_X25519_eFRODOKEM_640_AES_OQS 
HYBRID_X448_eFRODOKEM_976_SHAKE_OQS 
HYBRID_X448_eFRODOKEM_976_AES_OQS 
HYBRID_SECP256R1_eFRODOKEM_640_SHAKE_OQS 
HYBRID_SECP256R1_eFRODOKEM_640_AES_OQS 
HYBRID_SECP384R1_eFRODOKEM_976_SHAKE_OQS 
HYBRID_SECP384R1_eFRODOKEM_976_AES_OQS 
HYBRID_SECP521R1_eFRODOKEM_1344_SHAKE_OQS 
HYBRID_SECP521R1_eFRODOKEM_1344_AES_OQS 

Definition at line 80 of file tls_algos.h.

80 : uint16_t {
81 NONE = 0,
82
83 SECP256R1 = 23,
84 SECP384R1 = 24,
85 SECP521R1 = 25,
86 BRAINPOOL256R1 = 26,
87 BRAINPOOL384R1 = 27,
88 BRAINPOOL512R1 = 28,
89
90 X25519 = 29,
91 X448 = 30,
92
96
97 FFDHE_2048 = 256,
98 FFDHE_3072 = 257,
99 FFDHE_4096 = 258,
100 FFDHE_6144 = 259,
101 FFDHE_8192 = 260,
102
103 // https://datatracker.ietf.org/doc/draft-connolly-tls-mlkem-key-agreement/05/
104 ML_KEM_512 = 0x0200,
105 ML_KEM_768 = 0x0201,
106 ML_KEM_1024 = 0x0202,
107
108 // libOQS defines those in:
109 // https://github.com/open-quantum-safe/oqs-provider/blob/main/ALGORITHMS.md
110 // (last update: 6th June 2025 - matching oqs commit 9447f68)
114 eFRODOKEM_640_AES_OQS = 0xFE00,
115 eFRODOKEM_976_AES_OQS = 0xFE06,
116 eFRODOKEM_1344_AES_OQS = 0xFE0C,
117
118 // https://datatracker.ietf.org/doc/draft-kwiatkowski-tls-ecdhe-mlkem/03/
122
123 // https://github.com/open-quantum-safe/oqs-provider/blob/main/ALGORITHMS.md
124 // (last update: 6th June 2025 - matching oqs commit 9447f68)
127
130
133
136
139};
@ NONE
Definition filter.h:193

◆ Handshake_Type

enum class Botan::TLS::Handshake_Type : uint8_t
strong
Enumerator
HelloRequest 
ClientHello 
ServerHello 
HelloVerifyRequest 
NewSessionTicket 
EndOfEarlyData 
EncryptedExtensions 
Certificate 
ServerKeyExchange 
CertificateRequest 
ServerHelloDone 
CertificateVerify 
ClientKeyExchange 
Finished 
CertificateUrl 
CertificateStatus 
KeyUpdate 
HandshakeCCS 
HelloRetryRequest 
MessageHash 
None 

Definition at line 74 of file tls_magic.h.

74 : uint8_t {
75 HelloRequest = 0,
76 ClientHello = 1,
77 ServerHello = 2,
79 NewSessionTicket = 4, // RFC 5077
80
81 EndOfEarlyData = 5, // RFC 8446 (TLS 1.3)
82 EncryptedExtensions = 8, // RFC 8446 (TLS 1.3)
83
84 Certificate = 11,
87 ServerHelloDone = 14,
90 Finished = 20,
91
92 CertificateUrl = 21,
94
95 KeyUpdate = 24, // RFC 8446 (TLS 1.3)
96
97 HandshakeCCS = 252, // Not a wire value
98 HelloRetryRequest = 253, // Not a wire value (HRR appears as an ordinary Server Hello)
99 MessageHash = 254, // Not a wire value (RFC 9846 4.1)
100 None = 255 // Null value
101};

◆ KDF_Algo

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

Definition at line 46 of file tls_algos.h.

◆ Kex_Algo

enum class Botan::TLS::Kex_Algo : uint8_t
strong
Enumerator
STATIC_RSA 
DH 
ECDH 
PSK 
ECDHE_PSK 
DHE_PSK 
KEM 
KEM_PSK 
HYBRID 
HYBRID_PSK 
UNDEFINED 

Definition at line 265 of file tls_algos.h.

265 : uint8_t {
267 DH,
268 ECDH,
269 PSK,
270 ECDHE_PSK,
271 DHE_PSK,
272 KEM,
273 KEM_PSK,
274 HYBRID,
276
277 // To support TLS 1.3 ciphersuites, which do not determine the kex algo
279};

◆ Nonce_Format

enum class Botan::TLS::Nonce_Format : uint8_t
strong
Enumerator
CBC_MODE 
AEAD_IMPLICIT_4 
AEAD_XOR_12 
NULL_CIPHER 

Definition at line 54 of file tls_algos.h.

◆ PSK_Key_Exchange_Mode

enum class Botan::TLS::PSK_Key_Exchange_Mode : uint8_t
strong
Enumerator
PSK_KE 
PSK_DHE_KE 

Definition at line 37 of file tls_extensions_13.h.

◆ Record_Type

enum class Botan::TLS::Record_Type : uint8_t
strong
Enumerator
Invalid 
ChangeCipherSpec 
Alert 
Handshake 
ApplicationData 
Heartbeat 

Definition at line 58 of file tls_magic.h.

58 : uint8_t {
59 Invalid = 0, // RFC 8446 (TLS 1.3)
60
62 Alert = 21,
63 Handshake = 22,
64 ApplicationData = 23,
65
66 Heartbeat = 24, // RFC 6520
67};

◆ Size_Limits

enum Botan::TLS::Size_Limits : size_t

Protocol Constants for SSL/TLS

TODO(Botan4): this should not be an enum at all

Enumerator
TLS_HEADER_SIZE 
DTLS_HEADER_SIZE 
TLS_HANDSHAKE_HEADER_LENGTH 
MAX_PLAINTEXT_SIZE 
MAX_COMPRESSED_SIZE 
MAX_CIPHERTEXT_SIZE 
MAX_AEAD_EXPANSION_SIZE_TLS13 
MAX_CIPHERTEXT_SIZE_TLS13 

Definition at line 29 of file tls_magic.h.

29 : size_t /* NOLINT(*-enum-size,*-use-enum-class) */ {
32
34
35 // The "TLSInnerPlaintext" length, i.e. the maximum amount of plaintext
36 // application data that can be transmitted in a single TLS record.
37 MAX_PLAINTEXT_SIZE = 16 * 1024,
38
41
42 // RFC 8446 5.2:
43 // This limit is derived from the maximum TLSInnerPlaintext length of 2^14
44 // octets + 1 octet for ContentType + the maximum AEAD expansion of 255
45 // octets.
48};
@ MAX_CIPHERTEXT_SIZE
Definition tls_magic.h:40
@ MAX_PLAINTEXT_SIZE
Definition tls_magic.h:37
@ MAX_CIPHERTEXT_SIZE_TLS13
Definition tls_magic.h:47
@ MAX_AEAD_EXPANSION_SIZE_TLS13
Definition tls_magic.h:46
@ TLS_HEADER_SIZE
Definition tls_magic.h:30
@ TLS_HANDSHAKE_HEADER_LENGTH
Definition tls_magic.h:33
@ MAX_COMPRESSED_SIZE
Definition tls_magic.h:39
@ DTLS_HEADER_SIZE
Definition tls_magic.h:31

◆ TLS_Flavor

enum class Botan::TLS::TLS_Flavor : bool
strong
Enumerator
TLS 
DTLS 

Definition at line 69 of file tls_magic.h.

69 : bool {
70 TLS,
71 DTLS,
72};

◆ Version_Code

enum class Botan::TLS::Version_Code : uint16_t
strong
Enumerator
TLS_V10 

TLSv1.0 (no longer supported).

TLS_V11 

TLSv1.1 (no longer supported).

TLS_V12 

TLSv1.2.

TLS_V13 

TLSv1.3.

DTLS_V10 

DTLSv1.0 (no longer supported).

DTLS_V12 

DTLSv1.2.

DTLS_V13 

DTLSv1.3 (not supported yet).

Definition at line 18 of file tls_version.h.

18 : uint16_t {
19 /// TLSv1.0 (no longer supported)
20 TLS_V10 = 0x0301,
21 /// TLSv1.1 (no longer supported)
22 TLS_V11 = 0x0302,
23 /// TLSv1.2
24 TLS_V12 = 0x0303,
25 /// TLSv1.3
26 TLS_V13 = 0x0304,
27 /// DTLSv1.0 (no longer supported)
28 DTLS_V10 = 0xFEFF,
29 /// DTLSv1.2
30 DTLS_V12 = 0xFEFD,
31 /// DTLSv1.3 (not supported yet)
32 DTLS_V13 = 0xFEFC,
33};
@ TLS_V11
TLSv1.1 (no longer supported).
Definition tls_version.h:22
@ TLS_V10
TLSv1.0 (no longer supported).
Definition tls_version.h:20
@ DTLS_V10
DTLSv1.0 (no longer supported).
Definition tls_version.h:28
@ DTLS_V13
DTLSv1.3 (not supported yet).
Definition tls_version.h:32

Function Documentation

◆ annotate_record_type()

Record Botan::TLS::annotate_record_type ( Record_Content && record)

Takes a generic record and transforms it into one of the strong typed record variants based on the contained type.

Exceptions
TLS_Exceptionif the record type is any other value.

Definition at line 20 of file tls_record_13.cpp.

20 {
21 switch(record.type) {
23 return ChangeCipherSpec_Record{std::move(record)};
25 return Alert_Record{std::move(record)};
27 return Handshake_Record{std::move(record)};
29 return ApplicationData_Record{std::move(record)};
30
32 case Record_Type::Heartbeat: // not supported
33 break;
34 }
35
36 throw TLS_Exception(Alert::UnexpectedMessage, "TLS record type had unexpected value");
37}

References Alert, ApplicationData, ChangeCipherSpec, Handshake, Heartbeat, and Invalid.

Referenced by Botan::TLS::TLS_Cipher_State::deprotect_record(), and Botan::TLS::TLS_Record_Layer::next_record().

◆ append_tls_length_value() [1/4]

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 )
inline

Definition at line 212 of file tls_reader.h.

214 {
215 append_tls_length_value(buf, std::span{vals}, tag_size);
216}
void append_tls_length_value(std::vector< uint8_t, Alloc > &buf, const T *vals, size_t vals_size, size_t tag_size)
Definition tls_reader.h:182

References append_tls_length_value().

◆ append_tls_length_value() [2/4]

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 )
inline

Helper function for encoding length-tagged vectors

Definition at line 182 of file tls_reader.h.

185 {
186 const size_t T_size = sizeof(T);
187 const size_t val_bytes = T_size * vals_size;
188
189 BOTAN_ARG_CHECK(tag_size == 1 || tag_size == 2 || tag_size == 3, "Invalid TLS tag size");
190
191 const size_t max_possible_size = (1 << (8 * tag_size)) - 1;
192
193 BOTAN_ARG_CHECK(val_bytes <= max_possible_size, "Value too large to encode");
194
195 for(size_t i = 0; i != tag_size; ++i) {
196 buf.push_back(get_byte_var(sizeof(val_bytes) - tag_size + i, val_bytes));
197 }
198
199 for(size_t i = 0; i != vals_size; ++i) {
200 for(size_t j = 0; j != T_size; ++j) {
201 buf.push_back(get_byte_var(j, vals[i]));
202 }
203 }
204}
#define BOTAN_ARG_CHECK(expr, msg)
Definition assert.h:33
constexpr uint8_t get_byte_var(size_t byte_num, T input)
Definition loadstor.h:69

References BOTAN_ARG_CHECK, and Botan::get_byte_var().

Referenced by append_tls_length_value(), append_tls_length_value(), append_tls_length_value(), Botan::TLS::Client_Key_Exchange::Client_Key_Exchange(), Botan::TLS::Client_Key_Exchange::Client_Key_Exchange(), Botan::TLS::Application_Layer_Protocol_Notification::serialize(), Botan::TLS::Certificate_12::serialize(), Botan::TLS::Certificate_13::serialize(), Botan::TLS::Certificate_Authorities::serialize(), Botan::TLS::Certificate_Request_12::serialize(), Botan::TLS::Certificate_Request_13::serialize(), Botan::TLS::Certificate_Type_Base::serialize(), Botan::TLS::Client_Hello::serialize(), Botan::TLS::Cookie::serialize(), Botan::TLS::Hello_Verify_Request::serialize(), Botan::TLS::New_Session_Ticket_12::serialize(), Botan::TLS::New_Session_Ticket_13::serialize(), Botan::TLS::PSK::serialize(), Botan::TLS::Renegotiation_Extension::serialize(), Botan::TLS::Server_Hello::serialize(), and Botan::TLS::Server_Key_Exchange::Server_Key_Exchange().

◆ append_tls_length_value() [3/4]

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

Definition at line 207 of file tls_reader.h.

207 {
208 append_tls_length_value(buf, vals.data(), vals.size(), tag_size);
209}

References append_tls_length_value().

◆ append_tls_length_value() [4/4]

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

Definition at line 219 of file tls_reader.h.

219 {
220 append_tls_length_value(buf, as_span_of_bytes(str), tag_size);
221}
std::span< const uint8_t > as_span_of_bytes(const char *s, size_t len)
Definition mem_utils.h:59

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

◆ as_tls_cipher_state()

TLS_Cipher_State * Botan::TLS::as_tls_cipher_state ( Cipher_State * cs)
inline

Definition at line 499 of file tls_cipher_state.h.

499 {
500 auto* tls_cs = dynamic_cast<TLS_Cipher_State*>(cs);
502 tls_cs == nullptr, cs == nullptr, "If the cipher state is not a TLS_Cipher_State, it must be null");
503 return tls_cs;
504}
#define BOTAN_ASSERT_IMPLICATION(expr1, expr2, msg)
Definition assert.h:108

References BOTAN_ASSERT_IMPLICATION.

Referenced by Botan::TLS::TLS_Record_Layer::next_record(), and Botan::TLS::TLS_Record_Layer::prepare_record().

◆ auth_method_from_string()

Auth_Method BOTAN_TEST_API Botan::TLS::auth_method_from_string ( std::string_view str)

Definition at line 125 of file tls_algos.cpp.

125 {
126 if(str == "RSA") {
127 return Auth_Method::RSA;
128 }
129 if(str == "ECDSA") {
130 return Auth_Method::ECDSA;
131 }
132 if(str == "IMPLICIT") {
134 }
135 if(str == "UNDEFINED") {
137 }
138
139 throw Invalid_Argument(fmt("Unknown TLS signature method '{}'", str));
140}
std::string fmt(std::string_view format, const T &... args)
Definition fmt.h:53

References ECDSA, Botan::fmt(), IMPLICIT, RSA, and UNDEFINED.

◆ auth_method_to_string()

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

Definition at line 110 of file tls_algos.cpp.

110 {
111 switch(method) {
112 case Auth_Method::RSA:
113 return "RSA";
115 return "ECDSA";
117 return "IMPLICIT";
119 return "UNDEFINED";
120 }
121
122 throw Invalid_State("auth_method_to_string unknown enum value");
123}

References ECDSA, IMPLICIT, RSA, and UNDEFINED.

Referenced by Botan::TLS::Ciphersuite::sig_algo().

◆ calculate_cookie()

std::vector< uint8_t > Botan::TLS::calculate_cookie ( std::span< const uint8_t > client_hello_bits,
std::string_view client_identity,
std::span< const uint8_t > cookie_secret )

Compute a cookie value from the ClientHello and the client's identity. Used by both the DTLS 1.2 HelloVerifyRequest and the DTLS 1.3 HelloRetryRequest cookie extension.

Note: Currently, Botan does not support proper stateless handling of HelloVerifyRequest/HelloRetryRequest messages using Cookies.

Definition at line 47 of file msg_client_hello.cpp.

49 {
50 auto hmac = MessageAuthenticationCode::create_or_throw("HMAC(SHA-256)");
51 hmac->set_key(cookie_secret);
52
53 hmac->update_be(static_cast<uint64_t>(client_hello_bits.size()));
54 hmac->update(client_hello_bits);
55 hmac->update_be(static_cast<uint64_t>(client_identity.size()));
56 hmac->update(client_identity);
57
58 return hmac->final_stdvec();
59}
static std::unique_ptr< MessageAuthenticationCode > create_or_throw(std::string_view algo_spec, std::string_view provider="")
Definition mac.cpp:142

References Botan::MessageAuthenticationCode::create_or_throw().

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

◆ certificate_type_from_string()

Certificate_Type Botan::TLS::certificate_type_from_string ( const std::string & type_str)

Definition at line 536 of file tls_algos.cpp.

536 {
537 if(type_str == "X509") {
539 } else if(type_str == "RawPublicKey") {
541 } else {
542 throw Decoding_Error("Unknown certificate type: " + type_str);
543 }
544}

References RawPublicKey, and X509.

Referenced by Botan::TLS::Text_Policy::read_cert_type_list().

◆ certificate_type_to_string()

std::string Botan::TLS::certificate_type_to_string ( Certificate_Type type)

Definition at line 525 of file tls_algos.cpp.

525 {
526 switch(type) {
528 return "X509";
530 return "RawPublicKey";
531 }
532
533 return "Unknown";
534}

References RawPublicKey, and X509.

Referenced by Botan::TLS::Certificate_Type_Base::validate_selection().

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

264 {
265 if(record_len == 0 || record_len > 0xFFFF) {
266 return 0;
267 }
268
269 const uint16_t rec16 = static_cast<uint16_t>(record_len);
270
271 /*
272 * TLS v1.0 and up require all the padding bytes be the same value
273 * and allows up to 255 bytes.
274 */
275
276 const uint16_t to_check = std::min<uint16_t>(256, static_cast<uint16_t>(record_len));
277 const uint8_t pad_byte = record[record_len - 1];
278 const uint16_t pad_bytes = 1 + pad_byte;
279
280 auto pad_invalid = CT::Mask<uint16_t>::is_lt(rec16, pad_bytes);
281
282 for(uint16_t i = rec16 - to_check; i != rec16; ++i) {
283 const uint16_t offset = rec16 - i;
284 const auto in_pad_range = CT::Mask<uint16_t>::is_lte(offset, pad_bytes);
285 const auto pad_correct = CT::Mask<uint16_t>::is_equal(record[i], pad_byte);
286 pad_invalid |= in_pad_range & ~pad_correct;
287 }
288
289 return pad_invalid.if_not_set_return(pad_bytes);
290}
static constexpr Mask< T > is_lte(T x, T y)
Definition ct_utils.h:468
static constexpr Mask< T > is_equal(T x, T y)
Definition ct_utils.h:447
static constexpr Mask< T > is_lt(T x, T y)
Definition ct_utils.h:455

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

◆ filter_signature_schemes()

std::vector< std::string > Botan::TLS::filter_signature_schemes ( const std::vector< Signature_Scheme > & schemes,
const Protocol_Version & version )

Reduce schemes to the distinct certificate key-algorithm names (e.g. "RSA", "ECDSA") that are usable under version, preserving the order in which they first appear. Schemes that are unavailable in this build, or not compatible with version, are skipped. Used to narrow certificate selection to the key types the peer's signature_algorithms permits.

Definition at line 474 of file tls_signature_scheme.cpp.

475 {
476 std::vector<std::string> key_types;
477 for(const auto& scheme : schemes) {
478 if(scheme.is_available() && scheme.is_compatible_with(version)) {
479 const auto algo_name = scheme.algorithm_name();
480 if(!value_exists(key_types, algo_name)) {
481 key_types.push_back(algo_name);
482 }
483 }
484 }
485 return key_types;
486}
bool value_exists(const std::vector< T > &vec, const V &val)
Definition stl_util.h:44

References Botan::value_exists().

Referenced by Botan::TLS::Certificate_13::Certificate_13(), and Botan::TLS::Certificate_13::Certificate_13().

◆ group_may_be_ecc()

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

Return true if group is an elliptic curve group, or an unknown group outside the FFDHE range which the application may implement as a curve via the callbacks

Definition at line 256 of file tls_algos.cpp.

256 {
257 return group.is_pure_ecc_group() || (!group.to_string().has_value() && !group.is_in_ffdhe_range());
258}
constexpr bool is_in_ffdhe_range() const
Definition tls_algos.h:185
std::optional< std::string > to_string() const
constexpr bool is_pure_ecc_group() const
Definition tls_algos.h:210

References Botan::TLS::Group_Params::is_in_ffdhe_range(), Botan::TLS::Group_Params::is_pure_ecc_group(), and Botan::TLS::Group_Params::to_string().

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

◆ group_usable_in_version()

bool Botan::TLS::group_usable_in_version ( Group_Params group,
Protocol_Version version )

The Brainpool group code points of RFC 7027 are only defined up to TLS 1.2, those of RFC 8734 and all KEM groups only for TLS 1.3.

Definition at line 233 of file tls_algos.cpp.

233 {
234 if(version.is_pre_tls_13()) {
235 return !group.is_kem() && //
236 group != Group_Params::BRAINPOOL256R1TLS13 && //
237 group != Group_Params::BRAINPOOL384R1TLS13 && //
238 group != Group_Params::BRAINPOOL512R1TLS13;
239 } else {
240 return group != Group_Params::BRAINPOOL256R1 && //
241 group != Group_Params::BRAINPOOL384R1 && //
242 group != Group_Params::BRAINPOOL512R1;
243 }
244}
constexpr bool is_kem() const
Definition tls_algos.h:242

References Botan::TLS::Group_Params::is_kem(), and Botan::TLS::Protocol_Version::is_pre_tls_13().

Referenced by Botan::TLS::Client_Key_Exchange::Client_Key_Exchange(), groups_usable_in_version(), and Botan::TLS::Key_Share::retry_offer().

◆ groups_usable_in_version()

std::vector< Group_Params > Botan::TLS::groups_usable_in_version ( std::span< const Group_Params > groups,
Protocol_Version version )

Filter groups by group_usable_in_version()

Definition at line 246 of file tls_algos.cpp.

246 {
247 std::vector<Group_Params> usable;
248 for(const auto group : groups) {
249 if(group_usable_in_version(group, version)) {
250 usable.push_back(group);
251 }
252 }
253 return usable;
254}
bool group_usable_in_version(Group_Params group, Protocol_Version version)

References group_usable_in_version().

Referenced by Botan::TLS::Client_Hello_13::Client_Hello_13(), Botan::TLS::Server_Hello_13::create(), Botan::TLS::Encrypted_Extensions::Encrypted_Extensions(), and Botan::TLS::Server_Key_Exchange::Server_Key_Exchange().

◆ handshake_type_to_string()

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

Definition at line 15 of file tls_magic.cpp.

15 {
16 switch(type) {
18 return "hello_verify_request";
19
21 return "hello_request";
22
24 return "client_hello";
25
27 return "server_hello";
28
30 return "hello_retry_request";
31
33 return "certificate";
34
36 return "certificate_url";
37
39 return "certificate_status";
40
42 return "server_key_exchange";
43
45 return "certificate_request";
46
48 return "server_hello_done";
49
51 return "certificate_verify";
52
54 return "client_key_exchange";
55
57 return "new_session_ticket";
58
60 return "change_cipher_spec";
61
63 return "message_hash";
64
66 return "finished";
67
69 return "end_of_early_data";
70
72 return "encrypted_extensions";
73
75 return "key_update";
76
78 return "invalid";
79 }
80
81 throw TLS_Exception(Alert::UnexpectedMessage,
82 "Unknown TLS handshake message type " + std::to_string(static_cast<size_t>(type)));
83}

References Certificate, CertificateRequest, CertificateStatus, CertificateUrl, CertificateVerify, ClientHello, ClientKeyExchange, EncryptedExtensions, EndOfEarlyData, Finished, HandshakeCCS, HelloRequest, HelloRetryRequest, HelloVerifyRequest, KeyUpdate, MessageHash, NewSessionTicket, None, ServerHello, ServerHelloDone, and ServerKeyExchange.

Referenced by Botan::TLS::Handshake_Transitions::confirm_transition_to(), Botan::TLS::Key_Share::Key_Share(), and Botan::TLS::Handshake_Message::type_string().

◆ kdf_algo_to_string()

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

Definition at line 20 of file tls_algos.cpp.

20 {
21 switch(algo) {
22 case KDF_Algo::SHA_1:
23 return "SHA-1";
25 return "SHA-256";
27 return "SHA-384";
28 }
29
30 throw Invalid_State("kdf_algo_to_string unknown enum value");
31}

References SHA_1, SHA_256, and SHA_384.

Referenced by Botan::TLS::Ciphersuite::prf_algo().

◆ kex_method_from_string()

Kex_Algo BOTAN_TEST_API Botan::TLS::kex_method_from_string ( std::string_view str)

Definition at line 62 of file tls_algos.cpp.

62 {
63 if(str == "RSA") {
65 }
66
67 if(str == "DH") {
68 return Kex_Algo::DH;
69 }
70
71 if(str == "ECDH") {
72 return Kex_Algo::ECDH;
73 }
74
75 if(str == "PSK") {
76 return Kex_Algo::PSK;
77 }
78
79 if(str == "ECDHE_PSK") {
81 }
82
83 if(str == "DHE_PSK") {
84 return Kex_Algo::DHE_PSK;
85 }
86
87 if(str == "KEM") {
88 return Kex_Algo::KEM;
89 }
90
91 if(str == "KEM_PSK") {
92 return Kex_Algo::KEM_PSK;
93 }
94
95 if(str == "HYBRID") {
96 return Kex_Algo::HYBRID;
97 }
98
99 if(str == "HYBRID_PSK") {
101 }
102
103 if(str == "UNDEFINED") {
104 return Kex_Algo::UNDEFINED;
105 }
106
107 throw Invalid_Argument(fmt("Unknown kex method '{}'", str));
108}

References DH, DHE_PSK, ECDH, ECDHE_PSK, Botan::fmt(), HYBRID, HYBRID_PSK, KEM, KEM_PSK, PSK, STATIC_RSA, and UNDEFINED.

◆ kex_method_to_string()

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

Definition at line 33 of file tls_algos.cpp.

33 {
34 switch(method) {
36 return "RSA";
37 case Kex_Algo::DH:
38 return "DH";
39 case Kex_Algo::ECDH:
40 return "ECDH";
41 case Kex_Algo::PSK:
42 return "PSK";
44 return "ECDHE_PSK";
46 return "DHE_PSK";
47 case Kex_Algo::KEM:
48 return "KEM";
50 return "KEM_PSK";
52 return "HYBRID";
54 return "HYBRID_PSK";
56 return "UNDEFINED";
57 }
58
59 throw Invalid_State("kex_method_to_string unknown enum value");
60}

References DH, DHE_PSK, ECDH, ECDHE_PSK, HYBRID, HYBRID_PSK, KEM, KEM_PSK, PSK, STATIC_RSA, and UNDEFINED.

Referenced by Botan::TLS::Ciphersuite::kex_algo(), Botan::TLS::Server_Key_Exchange::Server_Key_Exchange(), and 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 284 of file tls_algos.h.

284 {
285 return (m == Kex_Algo::PSK || m == Kex_Algo::ECDHE_PSK || m == Kex_Algo::DHE_PSK);
286}

References DHE_PSK, ECDHE_PSK, and PSK.

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

◆ make_certificate_status_request()

std::unique_ptr< Extension > Botan::TLS::make_certificate_status_request ( TLS_Data_Reader & reader,
uint16_t extension_size,
Handshake_Type message_type,
Connection_Side from )

Parse a "status_request" extension. In a ClientHello, a request for any status_type other than "ocsp" is not supported and is treated as an unknown extension.

Definition at line 161 of file tls_extensions_cert_status_req.cpp.

164 {
165 // Only the "ocsp" status_type is supported, a request for any other type is ignored
166 if(message_type == Handshake_Type::ClientHello && extension_size > 0 && reader.peek_byte() != 1 /* ocsp */) {
167 return std::make_unique<Unknown_Extension>(Certificate_Status_Request::static_type(), reader, extension_size);
168 }
169
170 return std::make_unique<Certificate_Status_Request>(reader, extension_size, message_type, from);
171}
uint8_t peek_byte() const
Definition tls_reader.h:83

References ClientHello, Botan::TLS::TLS_Data_Reader::peek_byte(), and Botan::TLS::Certificate_Status_Request::static_type().

◆ make_hello_random()

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

Generate a (client) hello random value.

Depending on the policy, the RNG output may be hashed and if TLS 1.2 is offered, the random value may contain a timestamp.

Definition at line 26 of file msg_client_hello.cpp.

26 {
27 auto buf = rng.random_vec<std::vector<uint8_t>>(32);
28
29 if(policy.hash_hello_random()) {
30 auto sha256 = HashFunction::create_or_throw("SHA-256");
31 sha256->update(buf);
32 sha256->final(buf);
33 }
34
35 // TLS 1.3 does not require the insertion of a timestamp in the client hello
36 // random. When offering both TLS 1.2 and 1.3 we nevertheless comply with the
37 // legacy specification.
38 if(policy.include_time_in_hello_random() && (policy.allow_tls12() || policy.allow_dtls12())) {
39 const uint32_t time32 = static_cast<uint32_t>(std::chrono::system_clock::to_time_t(cb.tls_current_timestamp()));
40
41 store_be(time32, buf.data());
42 }
43
44 return buf;
45}
static std::unique_ptr< HashFunction > create_or_throw(std::string_view algo_spec, std::string_view provider="")
Definition hash.cpp:311
void random_vec(std::span< uint8_t > v)
Definition rng.h:254
virtual std::chrono::system_clock::time_point tls_current_timestamp()
virtual bool include_time_in_hello_random() const
virtual bool allow_tls12() const
virtual bool hash_hello_random() const
virtual bool allow_dtls12() const
constexpr auto store_be(ParamTs &&... params)
Definition loadstor.h:745

References Botan::TLS::Policy::allow_dtls12(), Botan::TLS::Policy::allow_tls12(), Botan::HashFunction::create_or_throw(), Botan::TLS::Policy::hash_hello_random(), Botan::TLS::Policy::include_time_in_hello_random(), Botan::RandomNumberGenerator::random_vec(), Botan::store_be(), and Botan::TLS::Callbacks::tls_current_timestamp().

Referenced by Botan::TLS::Client_Hello_12::Client_Hello_12(), Botan::TLS::Client_Hello_12::Client_Hello_12(), Botan::TLS::Client_Hello_13::Client_Hello_13(), and make_server_hello_random().

◆ make_server_hello_random()

std::vector< uint8_t > Botan::TLS::make_server_hello_random ( RandomNumberGenerator & rng,
Protocol_Version offered_version,
Callbacks & cb,
const Policy & policy,
TLS_Flavor flavor )

Generate a server hello random value for the given protocol version.

Depending on the protocol version, the random value is generated differently. For instance, TLS 1.2 requested a timestamp in the random value. Also, when downgrading to TLS 1.2 from a peer that could also negotiate TLS 1.3, the random value must be slightly modified to signal the downgrade.

Definition at line 24 of file msg_server_hello.cpp.

28 {
29 auto random = make_hello_random(rng, cb, policy);
30
31 // RFC 8446 4.1.3
32 // TLS 1.3 has a downgrade protection mechanism embedded in the server's
33 // random value. TLS 1.3 servers which negotiate TLS 1.2 or below in
34 // response to a ClientHello MUST set the last 8 bytes of their Random
35 // value specially in their ServerHello.
36 //
37 // If negotiating TLS 1.2, TLS 1.3 servers MUST set the last 8 bytes of
38 // their Random value to the bytes: [DOWNGRADE_TLS12]
39 //
40 // DTLS 1.3 is not implemented, so a DTLS server never sets these.
41 if(flavor == TLS_Flavor::TLS && offered_version.is_pre_tls_13() && policy.allow_tls13()) {
42 constexpr size_t downgrade_signal_length = sizeof(DOWNGRADE_TLS12);
43 BOTAN_ASSERT_NOMSG(random.size() >= downgrade_signal_length);
44 const auto lastbytes = std::span{random}.last(downgrade_signal_length);
45 store_be(DOWNGRADE_TLS12, lastbytes);
46 }
47
48 return random;
49}
#define BOTAN_ASSERT_NOMSG(expr)
Definition assert.h:82
virtual bool allow_tls13() const
constexpr uint64_t DOWNGRADE_TLS12
Definition tls_magic.h:130
std::vector< uint8_t > make_hello_random(RandomNumberGenerator &rng, Callbacks &cb, const Policy &policy)

References Botan::TLS::Policy::allow_tls13(), BOTAN_ASSERT_NOMSG, DOWNGRADE_TLS12, Botan::TLS::Protocol_Version::is_pre_tls_13(), make_hello_random(), Botan::store_be(), and TLS.

Referenced by Botan::TLS::Server_Hello_12::Server_Hello_12(), Botan::TLS::Server_Hello_12::Server_Hello_12(), and Botan::TLS::Server_Hello_13::Server_Hello_13().

◆ operator!=()

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

Definition at line 75 of file tls_server_info.h.

75 {
76 return !(a == b);
77}

◆ operator<() [1/2]

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

Definition at line 79 of file tls_server_info.h.

79 {
80 if(a.hostname() != b.hostname()) {
81 return (a.hostname() < b.hostname());
82 }
83 if(a.service() != b.service()) {
84 return (a.service() < b.service());
85 }
86 if(a.port() != b.port()) {
87 return (a.port() < b.port());
88 }
89 return false; // equal
90}

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

◆ operator<() [2/2]

auto Botan::TLS::operator< ( const Session_ID & id1,
const Session_ID & id2 )
inline

Definition at line 31 of file tls_session_id.h.

31 {
32 return id1.get() < id2.get();
33}
constexpr T & get() &
Definition strong_type.h:81

References Botan::detail::Strong_Base< T >::get().

◆ operator==()

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

Definition at line 71 of file tls_server_info.h.

71 {
72 return (a.hostname() == b.hostname()) && (a.service() == b.service()) && (a.port() == b.port());
73}

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

◆ read_record()

Record_Header Botan::TLS::read_record ( TLS_Flavor flavor,
secure_vector< uint8_t > & read_buffer,
const uint8_t input[],
size_t input_len,
size_t & consumed,
secure_vector< uint8_t > & record_buf,
Connection_Sequence_Numbers * sequence_numbers,
const get_cipherstate_fn & get_cipherstate,
bool allow_epoch0_restart )

Decode a TLS record

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

Definition at line 521 of file tls_record.cpp.

529 {
530 if(flavor == TLS_Flavor::DTLS) {
531 return read_dtls_record(
532 readbuf, input, input_len, consumed, recbuf, sequence_numbers, get_cipherstate, allow_epoch0_restart);
533 } else {
534 return read_tls_record(readbuf, input, input_len, consumed, recbuf, sequence_numbers, get_cipherstate);
535 }
536}

References DTLS.

Referenced by Botan::TLS::Channel_Impl_12::from_peer().

◆ to_algorithm_identifiers()

std::vector< AlgorithmIdentifier > Botan::TLS::to_algorithm_identifiers ( const std::vector< Signature_Scheme > & schemes)

Definition at line 465 of file tls_signature_scheme.cpp.

465 {
466 std::vector<AlgorithmIdentifier> result;
467 result.reserve(schemes.size());
468 for(const auto& scheme : schemes) {
469 result.push_back(scheme.algorithm_identifier());
470 }
471 return result;
472}

Referenced by Botan::TLS::Certificate_13::Certificate_13(), and Botan::TLS::Certificate_13::Certificate_13().

◆ write_record()

void Botan::TLS::write_record ( secure_vector< uint8_t > & write_buffer,
Record_Type record_type,
Protocol_Version record_version,
uint64_t record_sequence,
const uint8_t * message,
size_t message_len,
Connection_Cipher_State & cipherstate,
RandomNumberGenerator & rng )

Create a TLS record

Parameters
write_bufferthe output record is placed here
record_typethe record layer type
record_versionthe record layer version
record_sequencethe record layer sequence number
messagethe record contents
message_lenis size of message
cipherstateis the writing cipher state
Random Number Generatorsis a random number generator

Definition at line 220 of file tls_record.cpp.

227 {
228 write_record_header(output, record_type, version, record_sequence);
229
230 AEAD_Mode& aead = cs.aead();
231 const auto aad = cs.format_ad(record_sequence, record_type, version, static_cast<uint16_t>(message_len));
232
233 const size_t ctext_size = aead.output_length(message_len);
234
235 const size_t rec_size = ctext_size + cs.nonce_bytes_from_record();
236
237 aead.set_associated_data(aad);
238
239 const auto nonce = cs.aead_nonce(record_sequence, rng);
240
241 append_u16_len(output, rec_size);
242
243 if(cs.nonce_bytes_from_record() > 0) {
244 if(cs.nonce_format() == Nonce_Format::CBC_MODE) {
245 output += nonce.get();
246 } else {
247 output += nonce.get().subspan(cs.nonce_bytes_from_handshake(), cs.nonce_bytes_from_record());
248 }
249 }
250
251 const size_t header_size = output.size();
252 output += std::make_pair(message, message_len);
253
254 aead.start(nonce.get());
255 aead.finish(output, header_size);
256
257 BOTAN_ASSERT(output.size() < MAX_CIPHERTEXT_SIZE, "Produced ciphertext larger than protocol allows");
258}
#define BOTAN_ASSERT(expr, assertion_made)
Definition assert.h:69
void set_associated_data(std::span< const uint8_t > ad)
Definition aead.h:59
void start(std::span< const uint8_t > nonce)
Definition cipher_mode.h:98
void finish(secure_vector< uint8_t > &final_block, size_t offset=0)
virtual size_t output_length(size_t input_length) const =0

References Botan::TLS::Connection_Cipher_State::aead(), Botan::TLS::Connection_Cipher_State::aead_nonce(), BOTAN_ASSERT, CBC_MODE, Botan::Cipher_Mode::finish(), Botan::TLS::Connection_Cipher_State::format_ad(), MAX_CIPHERTEXT_SIZE, 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::Cipher_Mode::output_length(), Botan::AEAD_Mode::set_associated_data(), and Botan::Cipher_Mode::start().

◆ write_unencrypted_record()

void Botan::TLS::write_unencrypted_record ( secure_vector< uint8_t > & write_buffer,
Record_Type record_type,
Protocol_Version record_version,
uint64_t record_sequence,
const uint8_t * message,
size_t message_len )

Create an initial (unencrypted) TLS handshake record

Parameters
write_bufferthe output record is placed here
record_typethe record layer type
record_versionthe record layer version
record_sequencethe record layer sequence number
messagethe record contents
message_lenis size of message

Definition at line 206 of file tls_record.cpp.

211 {
212 if(record_type == Record_Type::ApplicationData) {
213 throw Internal_Error("Writing an unencrypted TLS application data record");
214 }
215 write_record_header(output, record_type, version, record_sequence);
216 append_u16_len(output, message_len);
217 output.insert(output.end(), message, message + message_len);
218}

References ApplicationData.

Variable Documentation

◆ DOWNGRADE_TLS11

uint64_t Botan::TLS::DOWNGRADE_TLS11 = 0x444F574E47524400
constexpr

Magic values used to signal a downgrade request to TLS 1.1.

RFC 8446 4.1.3: TLS 1.3 has a downgrade protection mechanism embedded in the server's random value. TLS 1.3 servers which negotiate TLS 1.2 or below in response to a ClientHello MUST set the last 8 bytes of their Random value specially in their ServerHello.

Definition at line 119 of file tls_magic.h.

Referenced by Botan::TLS::Server_Hello_12_Shim::random_signals_downgrade(), and Botan::TLS::Server_Hello_13::random_signals_downgrade().

◆ DOWNGRADE_TLS12

uint64_t Botan::TLS::DOWNGRADE_TLS12 = 0x444F574E47524401
constexpr

Magic values used to signal a downgrade request to TLS 1.2.

RFC 8446 4.1.3: TLS 1.3 has a downgrade protection mechanism embedded in the server's random value. TLS 1.3 servers which negotiate TLS 1.2 or below in response to a ClientHello MUST set the last 8 bytes of their Random value specially in their ServerHello.

Definition at line 130 of file tls_magic.h.

Referenced by make_server_hello_random(), Botan::TLS::Server_Hello_12_Shim::random_signals_downgrade(), and Botan::TLS::Server_Hello_13::random_signals_downgrade().

◆ HELLO_RETRY_REQUEST_MARKER

std::array<uint8_t, 32> Botan::TLS::HELLO_RETRY_REQUEST_MARKER
constexpr
Initial value:
= {
0xCF, 0x21, 0xAD, 0x74, 0xE5, 0x9A, 0x61, 0x11, 0xBE, 0x1D, 0x8C, 0x02, 0x1E, 0x65, 0xB8, 0x91,
0xC2, 0xA2, 0x11, 0x16, 0x7A, 0xBB, 0x8C, 0x5E, 0x07, 0x9E, 0x09, 0xE2, 0xC8, 0xA8, 0x33, 0x9C}

RFC 8446 4.1.3: For reasons of backward compatibility with middleboxes, the HelloRetryRequest message uses the same structure as the ServerHello, but with Random set to the special value of the SHA-256 of "HelloRetryRequest":

Definition at line 138 of file tls_magic.h.

138 {
139 0xCF, 0x21, 0xAD, 0x74, 0xE5, 0x9A, 0x61, 0x11, 0xBE, 0x1D, 0x8C, 0x02, 0x1E, 0x65, 0xB8, 0x91,
140 0xC2, 0xA2, 0x11, 0x16, 0x7A, 0xBB, 0x8C, 0x5E, 0x07, 0x9E, 0x09, 0xE2, 0xC8, 0xA8, 0x33, 0x9C};

Referenced by Botan::TLS::Hello_Retry_Request::Hello_Retry_Request(), and Botan::TLS::Server_Hello_Internal::Server_Hello_Internal().