Botan 3.14.1
Crypto and TLS for C&
Botan_FFI::FFI_TLS_Credentials Class Referencefinal

#include <ffi_tls_impl.h>

Inheritance diagram for Botan_FFI::FFI_TLS_Credentials:
Botan::Credentials_Manager

Public Member Functions

void add_cert_chain (std::vector< Botan::X509_Certificate > chain, std::shared_ptr< Botan::Private_Key > key)
 chain is leaf first and not empty; key belongs to the leaf
void add_crl (const Botan::X509_CRL &crl)
void add_store (std::shared_ptr< Botan::Certificate_Store > store)
void add_trusted_cert (const Botan::X509_Certificate &cert)
virtual std::vector< X509_Certificate > cert_chain (const std::vector< std::string > &cert_key_types, const std::vector< AlgorithmIdentifier > &cert_signature_schemes, const std::string &type, const std::string &context)
std::vector< X509_Certificate > cert_chain_single_type (const std::string &cert_key_type, const std::vector< AlgorithmIdentifier > &cert_signature_schemes, const std::string &type, const std::string &context)
virtual std::optional< TLS::ExternalPSK > choose_preshared_key (std::string_view host, TLS::Connection_Side whoami, const std::vector< std::string > &identities, const std::optional< std::string > &prf=std::nullopt)
virtual secure_vector< uint8_t > dtls_cookie_secret ()
std::vector< Botan::X509_Certificate > find_cert_chain (const std::vector< std::string > &cert_key_types, const std::vector< Botan::AlgorithmIdentifier > &cert_signature_schemes, const std::vector< Botan::X509_DN > &acceptable_CAs, const std::string &type, const std::string &context) override
virtual std::vector< TLS::ExternalPSK > find_preshared_keys (std::string_view host, TLS::Connection_Side whoami, const std::vector< std::string > &identities={}, const std::optional< std::string > &prf=std::nullopt)
virtual std::shared_ptr< Public_Key > find_raw_public_key (const std::vector< std::string > &key_types, const std::string &type, const std::string &context)
std::shared_ptr< Botan::Private_Key > private_key_for (const Botan::X509_Certificate &cert, const std::string &type, const std::string &context) override
virtual std::shared_ptr< Private_Key > private_key_for (const Public_Key &raw_public_key, const std::string &type, const std::string &context)
virtual SymmetricKey psk (const std::string &type, const std::string &context, const std::string &identity)
virtual std::string psk_identity (const std::string &type, const std::string &context, const std::string &identity_hint)
virtual std::string psk_identity_hint (const std::string &type, const std::string &context)
virtual secure_vector< uint8_t > session_ticket_key ()
std::vector< Botan::Certificate_Store * > trusted_certificate_authorities (const std::string &type, const std::string &context) override

Detailed Description

The Credentials_Manager behind botan_tls_credentials_t.

Trust anchors and CRLs live in an in-memory certificate store; further stores (a directory, the system store) are kept as separate objects. The certificate chains are used for server and for client authentication alike. The setters copy certificates and CRLs and share the private keys. The object is not synchronized, but otherwise it may be modified at any time and shared between channels.

Definition at line 35 of file ffi_tls_impl.h.

Member Function Documentation

◆ add_cert_chain()

void Botan_FFI::FFI_TLS_Credentials::add_cert_chain ( std::vector< Botan::X509_Certificate > chain,
std::shared_ptr< Botan::Private_Key > key )

chain is leaf first and not empty; key belongs to the leaf

Definition at line 48 of file ffi_tls.cpp.

49 {
50 BOTAN_ARG_CHECK(!chain.empty(), "Certificate chain must not be empty");
51 BOTAN_ARG_CHECK(key != nullptr, "Private key must not be null");
52 m_chains.push_back({
53 .certs = std::move(chain),
54 .key = std::move(key),
55 });
56}
#define BOTAN_ARG_CHECK(expr, msg)
Definition assert.h:33

References BOTAN_ARG_CHECK.

◆ add_crl()

void Botan_FFI::FFI_TLS_Credentials::add_crl ( const Botan::X509_CRL & crl)

Definition at line 40 of file ffi_tls.cpp.

40 {
41 m_trusted.add_crl(crl);
42}
botan_x509_crl_t crl
Definition ffi_tls.h:127

References crl.

◆ add_store()

void Botan_FFI::FFI_TLS_Credentials::add_store ( std::shared_ptr< Botan::Certificate_Store > store)

Definition at line 44 of file ffi_tls.cpp.

44 {
45 m_extra_stores.push_back(std::move(store));
46}

◆ add_trusted_cert()

void Botan_FFI::FFI_TLS_Credentials::add_trusted_cert ( const Botan::X509_Certificate & cert)

Definition at line 36 of file ffi_tls.cpp.

36 {
37 m_trusted.add_certificate(cert);
38}

◆ cert_chain()

std::vector< X509_Certificate > Botan::Credentials_Manager::cert_chain ( const std::vector< std::string > & cert_key_types,
const std::vector< AlgorithmIdentifier > & cert_signature_schemes,
const std::string & type,
const std::string & context )
virtualinherited

Return a certificate chain we can use to identify ourselves, ordered from leaf to root, or else an empty vector.

This virtual function is deprecated, and will be removed in a future release. Use (and override) find_cert_chain() instead.

It is assumed that the caller can get the private key of the leaf with private_key_for()

Parameters
cert_key_typesspecifies the key types desired ("RSA", "DSA", "ECDSA", etc), or empty if there is no preference by the caller.
cert_signature_schemesspecifies the signature types desired as signatures in the certificate(s) itself, or empty for no preference by the caller.
typespecifies the type of operation occurring
contextspecifies a context relative to type.

Definition at line 98 of file credentials_manager.cpp.

101 {
102 return std::vector<X509_Certificate>();
103}

Referenced by find_cert_chain(), and ~Credentials_Manager().

◆ cert_chain_single_type()

std::vector< X509_Certificate > Botan::Credentials_Manager::cert_chain_single_type ( const std::string & cert_key_type,
const std::vector< AlgorithmIdentifier > & cert_signature_schemes,
const std::string & type,
const std::string & context )
inherited

Return a certificate chain we can use to identify ourselves, ordered from leaf to root, or else an empty vector. Override this if we have one certificate of type cert_key_type and we would like to use a certificate in this type and context.

For servers type will be "tls-server" and the context will be the server name that the client requested via SNI (or empty, if the client did not send SNI).

Warning
To avoid cross-protocol attacks it is recommended that if a server receives an SNI request for a name it does not expect, it should close the connection with an alert. This can be done by throwing an exception from the implementation of this function.

It is assumed that the caller can get the private key of the leaf with private_key_for()

Parameters
cert_key_typespecifies the type of key requested ("RSA", "DSA", "ECDSA", etc)
cert_signature_schemesspecifies the signature types desired as signatures in the certificate(s) itself, or empty for no preference by the caller.
typespecifies the type of operation occurring
contextspecifies a context relative to type.

Definition at line 105 of file credentials_manager.cpp.

109 {
110 return find_cert_chain({cert_key_type}, cert_signature_schemes, std::vector<X509_DN>(), type, context);
111}
virtual std::vector< X509_Certificate > find_cert_chain(const std::vector< std::string > &cert_key_types, const std::vector< AlgorithmIdentifier > &cert_signature_schemes, const std::vector< X509_DN > &acceptable_CAs, const std::string &type, const std::string &context)

References find_cert_chain().

Referenced by ~Credentials_Manager().

◆ choose_preshared_key()

std::optional< TLS::ExternalPSK > Botan::Credentials_Manager::choose_preshared_key ( std::string_view host,
TLS::Connection_Side whoami,
const std::vector< std::string > & identities,
const std::optional< std::string > & prf = std::nullopt )
virtualinherited

Selects a single PSK identity from the given identities and returns its details (i.e. the secret value) for it to be used in the handshake.

The default implementation relies on the filtering capabilities provided by find_preshared_keys() and simply selects the first PSK returned. If applications need finer grained control, they should override this method.

In TLS 1.3 the identities might contain opaque session ticket data that is not necessarily a printable string, despite the utilized std::string type. Implementations must be prepared to ignore identities generated via the TLS 1.3 resumption mechanism.

Parameters
hostthe host name for which a PSK is requested (may be empty)
whoamithe type of the host (client or server) that is requesting
identitiesan optional filter for PSK identities to be returned (an empty list means: all identities are welcome)
prfan optional filter for the Pseudo Random Function the PRFs must be provisioned for
Returns
the PSK for the selected identity or std::nullopt if no PSK meets the requirements

Definition at line 71 of file credentials_manager.cpp.

74 {
75 auto psks = find_preshared_keys(host, whoami, identities, prf);
76 if(psks.empty()) {
77 return std::nullopt;
78 } else {
79 return std::move(psks.front());
80 }
81}
virtual std::vector< TLS::ExternalPSK > find_preshared_keys(std::string_view host, TLS::Connection_Side whoami, const std::vector< std::string > &identities={}, const std::optional< std::string > &prf=std::nullopt)

References find_preshared_keys().

Referenced by Botan::TLS::PSK::select_offered_psk().

◆ dtls_cookie_secret()

secure_vector< uint8_t > Botan::Credentials_Manager::dtls_cookie_secret ( )
virtualinherited

Provides a secret to authenticate DTLS hello cookies. The default implementation returns an empty key that effectively disables hello cookies. Applications that wish to use DTLS are strongly advised to implement this method.

Returns
a secret value to authenticate DTLS hello cookies

Definition at line 129 of file credentials_manager.cpp.

129 {
130 return {};
131}

Referenced by psk(), and ~Credentials_Manager().

◆ find_cert_chain()

std::vector< Botan::X509_Certificate > Botan_FFI::FFI_TLS_Credentials::find_cert_chain ( const std::vector< std::string > & cert_key_types,
const std::vector< Botan::AlgorithmIdentifier > & cert_signature_schemes,
const std::vector< Botan::X509_DN > & acceptable_CAs,
const std::string & type,
const std::string & context )
overridevirtual

Return a cert chain we can use, ordered from leaf to root, or else an empty vector.

It is assumed that the caller can get the private key of the leaf with private_key_for

For a comprehensive write-up of how to select certificates for TLS CertificateVerify messages, see RFC 8446 Sections 4.4.2.2 and 4.4.2.3.

Parameters
cert_key_typesspecifies the key types desired ("RSA", "DSA", "ECDSA", etc), or empty if there is no preference by the caller.
cert_signature_schemesspecifies the signature types desired as signatures in the certificate(s) itself, or empty for no preference by the caller.
acceptable_CAsthe CAs the requestor will accept (possibly empty)
typespecifies the type of operation occurring
contextspecifies a context relative to type.

Reimplemented from Botan::Credentials_Manager.

Definition at line 68 of file ffi_tls.cpp.

73 {
74 // A chain is usable if the peer accepts the type of its key. On a server,
75 // if any chain (of whatever key type) has a leaf certificate matching the
76 // server name the client asked for, only such chains are offered; the
77 // TLS 1.2 server asks once per key type, so a chain for another name must
78 // not be offered under a different key type when a matching one exists.
79 // Among the usable chains the first one issued by a certificate authority
80 // the peer named wins, otherwise the first usable chain is used, since the
81 // peer may still accept it. The names the peer sends may be those of trust
82 // anchors as well as of subordinate CAs (RFC 8446 4.2.4); a Botan server for
83 // instance sends the subjects of its trust stores. A root's name matches the
84 // issuer of the last certificate of a chain, not the issuer of the leaf, so
85 // every certificate of the chain is checked.
86 const bool restrict_to_hostname = type == "tls-server" && !context.empty() &&
87 std::any_of(m_chains.begin(), m_chains.end(), [&](const Chain& chain) {
88 return chain.certs.front().matches_dns_name(context);
89 });
90
91 std::vector<Botan::X509_Certificate> result;
92
93 for(const auto& chain : m_chains) {
94 if(!cert_key_types.empty() && !Botan::value_exists(cert_key_types, chain.key->algo_name())) {
95 continue;
96 }
97
98 if(restrict_to_hostname && !chain.certs.front().matches_dns_name(context)) {
99 continue;
100 }
101
102 bool preferred = true;
103
104 if(!acceptable_CAs.empty()) {
105 preferred = std::any_of(chain.certs.begin(), chain.certs.end(), [&](const Botan::X509_Certificate& cert) {
106 return Botan::value_exists(acceptable_CAs, cert.issuer_dn());
107 });
108 }
109
110 if(preferred) {
111 result = chain.certs;
112 break;
113 }
114
115 if(result.empty()) {
116 result = chain.certs;
117 }
118 }
119
120 return result;
121}
bool value_exists(const std::vector< T > &vec, const V &val)
Definition stl_util.h:44

References Botan::value_exists().

◆ find_preshared_keys()

std::vector< TLS::ExternalPSK > Botan::Credentials_Manager::find_preshared_keys ( std::string_view host,
TLS::Connection_Side whoami,
const std::vector< std::string > & identities = {},
const std::optional< std::string > & prf = std::nullopt )
virtualinherited

Filters all available PSKs with the given criterions. Note that omitted criterions (like an empty identities list or an unspecified PRF) must be interpreted as "no restriction".

Note that this is used as the underlying API for the legacy psk() method currently still used in TLS 1.2. New applications should override find_preshared_keys() and leave psk() with the default implementation.

In TLS 1.3 the identities might contain opaque session ticket data that is not necessarily a printable string, despite the utilized std::string type. Implementations must be prepared to ignore identities generated via the TLS 1.3 resumption mechanism.

Parameters
hostthe host name for which a PSK is requested (may be empty)
whoamithe type of the host (client or server) that is requesting
identitiesan optional filter for PSK identities to be returned (an empty list means: all identities are welcome)
prfan optional filter for the Pseudo Random Function the PRFs must be provisioned for
Returns
a list of PSKs that meet the defined criterions in preference order

Definition at line 64 of file credentials_manager.cpp.

67 {
68 return {};
69}

Referenced by choose_preshared_key(), psk(), and ~Credentials_Manager().

◆ find_raw_public_key()

std::shared_ptr< Public_Key > Botan::Credentials_Manager::find_raw_public_key ( const std::vector< std::string > & key_types,
const std::string & type,
const std::string & context )
virtualinherited

Return a raw public key to be used for authentication or nullptr if no public key was found.

It is assumed that the caller can get the private key of the leaf with private_key_for().

Parameters
key_typesspecifies the key types desired ("RSA", "DSA", "ECDSA", etc), or empty if there is no preference by the caller.
typespecifies the type of operation occurring
contextspecifies a context relative to type.

Definition at line 92 of file credentials_manager.cpp.

94 {
95 return nullptr;
96}

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

◆ private_key_for() [1/2]

std::shared_ptr< Botan::Private_Key > Botan_FFI::FFI_TLS_Credentials::private_key_for ( const Botan::X509_Certificate & cert,
const std::string & type,
const std::string & context )
overridevirtual

Return a shared_ptr to the private key for this certificate. The cert will be the leaf cert of a chain returned previously by find_cert_chain() or cert_chain_single_type().

This function should either return nullptr or throw an exception if the matching private key is unavailable.

Returns
private key associated with this certificate if we should use it in this context.

Reimplemented from Botan::Credentials_Manager.

Definition at line 123 of file ffi_tls.cpp.

125 {
126 for(const auto& chain : m_chains) {
127 if(chain.certs.front() == cert) {
128 return chain.key;
129 }
130 }
131 return nullptr;
132}

◆ private_key_for() [2/2]

std::shared_ptr< Private_Key > Botan::Credentials_Manager::private_key_for ( const Public_Key & raw_public_key,
const std::string & type,
const std::string & context )
virtual

This function should either return nullptr or throw an exception if the key is unavailable.

Returns
private key associated with this raw public key if we should use it with this context. raw_public_key was returned by find_raw_public_key()

Reimplemented from Botan::Credentials_Manager.

Definition at line 182 of file credentials_manager.cpp.

121 {
122 return nullptr;
123}

◆ psk()

SymmetricKey Botan::Credentials_Manager::psk ( const std::string & type,
const std::string & context,
const std::string & identity )
virtualinherited

Retrieves the PSK with the given identity or throws an exception. It's default implementation uses find_preshared_keys() with identity as the single allowed identity.

This method is called by the TLS 1.2 implementation exclusively and will eventually be deprecated in favor of find_preshared_keys(). Going forward, new applications should implement find_preshared_keys() and rely on psk()'s default implementation.

Also, the default implementation delegates context "session-ticket" and "dtls-cookie-secret" to the methods session_ticket_key() and dtls_cookie_secret() respectively. New applications should implement those methods and rely on the default implementation of psk().

TODO(Botan4) remove this interface

Parameters
typespecifies the type of operation occurring
contextspecifies a context relative to type.
identityis a PSK identity previously returned by psk_identity for the same type and context.
Returns
the PSK used for identity, or throw an exception if no key exists

Definition at line 27 of file credentials_manager.cpp.

29 {
30 const auto side = [&] {
31 if(type == "tls-client") {
33 } else if(type == "tls-server") {
35 } else {
36 throw Internal_Error(fmt("No PSK set for type {}", type));
37 }
38 }();
39
40 // New applications should use the appropriate credentials methods. This is a
41 // retrofit of the behaviour before Botan 3.2.0 and will be removed in a
42 // future major release.
43 //
44 // TODO: deprecate `psk("...", "session-ticket" | "dtls-cookie-secret")`
45 if(side == TLS::Connection_Side::Server && context == "session-ticket") {
46 if(auto key = session_ticket_key(); !key.empty()) {
47 return SymmetricKey(std::move(key));
48 }
49 } else if(side == TLS::Connection_Side::Server && context == "dtls-cookie-secret") {
50 if(auto key = dtls_cookie_secret(); !key.empty()) {
51 return SymmetricKey(std::move(key));
52 }
53 } else /* context is a host name */ {
54 // Assuming that find_preshared_keys returns _exactly_ one or no keys when
55 // searching for a single specific identity.
56 if(auto psks = find_preshared_keys(context, side, {identity}); psks.size() == 1) {
57 return SymmetricKey(psks.front().extract_master_secret());
58 }
59 }
60
61 throw Internal_Error(fmt("No PSK set for identity {}", identity));
62}
virtual secure_vector< uint8_t > dtls_cookie_secret()
virtual secure_vector< uint8_t > session_ticket_key()
OctetString SymmetricKey
Definition symkey.h:153
std::string fmt(std::string_view format, const T &... args)
Definition fmt.h:53

References Botan::TLS::Client, dtls_cookie_secret(), find_preshared_keys(), Botan::fmt(), Botan::TLS::Server, and session_ticket_key().

Referenced by Botan::TLS::Client_Key_Exchange::Client_Key_Exchange(), Botan::TLS::Client_Key_Exchange::Client_Key_Exchange(), and ~Credentials_Manager().

◆ psk_identity()

std::string Botan::Credentials_Manager::psk_identity ( const std::string & type,
const std::string & context,
const std::string & identity_hint )
virtualinherited

Returns the identity we would like to use given this type and context and the optional identity_hint. Not all servers or protocols will provide a hint.

Parameters
typespecifies the type of operation occurring
contextspecifies a context relative to type.
identity_hintwas passed by the server (but may be empty)
Returns
the PSK identity we want to use

Definition at line 21 of file credentials_manager.cpp.

23 {
24 return "";
25}

Referenced by Botan::TLS::Client_Key_Exchange::Client_Key_Exchange(), and ~Credentials_Manager().

◆ psk_identity_hint()

std::string Botan::Credentials_Manager::psk_identity_hint ( const std::string & type,
const std::string & context )
virtualinherited

Returns an identity hint which may be provided to the client. This can help a client understand what PSK to use.

Parameters
typespecifies the type of operation occurring
contextspecifies a context relative to type.
Returns
the PSK identity hint for this type/context

Definition at line 17 of file credentials_manager.cpp.

17 {
18 return "";
19}

Referenced by Botan::TLS::Server_Key_Exchange::Server_Key_Exchange(), and ~Credentials_Manager().

◆ session_ticket_key()

secure_vector< uint8_t > Botan::Credentials_Manager::session_ticket_key ( )
virtualinherited

Provides a secret value to encrypt session tickets for stateless session resumptions. The default implementation returns an empty key that effectively disables session tickets.

Returns
a secret value to be used to encrypt session tickets in subclasses of Session_Manager_Stateless.

Definition at line 125 of file credentials_manager.cpp.

125 {
126 return {};
127}

Referenced by psk(), and ~Credentials_Manager().

◆ trusted_certificate_authorities()

std::vector< Botan::Certificate_Store * > Botan_FFI::FFI_TLS_Credentials::trusted_certificate_authorities ( const std::string & type,
const std::string & context )
overridevirtual

Return a list of the certificates of CAs that we trust in this type/context.

Parameters
typespecifies the type of operation occurring
contextspecifies a context relative to type. For instance for type "tls-client", context specifies the servers name.

Reimplemented from Botan::Credentials_Manager.

Definition at line 58 of file ffi_tls.cpp.

59 {
60 std::vector<Botan::Certificate_Store*> stores;
61 stores.push_back(&m_trusted);
62 for(const auto& store : m_extra_stores) {
63 stores.push_back(store.get());
64 }
65 return stores;
66}

The documentation for this class was generated from the following files: