Botan 3.5.0
Crypto and TLS for C&
Botan::Credentials_Manager Class Reference

#include <credentials_manager.h>

Public Member Functions

virtual std::vector< X509_Certificatecert_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_Certificatecert_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::ExternalPSKchoose_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 ()
 
virtual std::vector< X509_Certificatefind_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)
 
virtual std::vector< TLS::ExternalPSKfind_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_Keyfind_raw_public_key (const std::vector< std::string > &key_types, const std::string &type, const std::string &context)
 
virtual std::shared_ptr< Private_Keyprivate_key_for (const Public_Key &raw_public_key, const std::string &type, const std::string &context)
 
virtual std::shared_ptr< Private_Keyprivate_key_for (const X509_Certificate &cert, 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 ()
 
virtual std::vector< Certificate_Store * > trusted_certificate_authorities (const std::string &type, const std::string &context)
 
virtual ~Credentials_Manager ()=default
 

Detailed Description

Interface for a credentials manager.

A type is a fairly static value that represents the general nature of the transaction occurring. Currently used values are "tls-client" and "tls-server". Context represents a hostname, email address, username, or other identifier.

Definition at line 34 of file credentials_manager.h.

Constructor & Destructor Documentation

◆ ~Credentials_Manager()

virtual Botan::Credentials_Manager::~Credentials_Manager ( )
virtualdefault

Member Function Documentation

◆ 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 )
virtual

Return a cert chain we can use, 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 96 of file credentials_manager.cpp.

99 {
100 return std::vector<X509_Certificate>();
101}

Referenced by find_cert_chain().

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

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

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 103 of file credentials_manager.cpp.

107 {
108 return find_cert_chain({cert_key_type}, cert_signature_schemes, std::vector<X509_DN>(), type, context);
109}
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().

◆ 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 )
virtual

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 69 of file credentials_manager.cpp.

72 {
73 auto psks = find_preshared_keys(host, whoami, identities, prf);
74 if(psks.empty()) {
75 return std::nullopt;
76 } else {
77 return std::move(psks.front());
78 }
79}
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 ( )
virtual

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 127 of file credentials_manager.cpp.

127 {
128 return {};
129}

Referenced by psk().

◆ find_cert_chain()

std::vector< X509_Certificate > Botan::Credentials_Manager::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 )
virtual

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.

Definition at line 81 of file credentials_manager.cpp.

86 {
87 return cert_chain(key_types, cert_signature_schemes, type, context);
88}
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)

References cert_chain().

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

◆ 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 )
virtual

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 62 of file credentials_manager.cpp.

65 {
66 return {};
67}

Referenced by choose_preshared_key(), and psk().

◆ 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 )
virtual

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 90 of file credentials_manager.cpp.

92 {
93 return nullptr;
94}

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

◆ private_key_for() [1/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()

Definition at line 117 of file credentials_manager.cpp.

119 {
120 return nullptr;
121}

◆ private_key_for() [2/2]

std::shared_ptr< Private_Key > Botan::Credentials_Manager::private_key_for ( const X509_Certificate & cert,
const std::string & type,
const std::string & context )
virtual
Returns
private key associated with this certificate if we should use it with this context. cert was returned by cert_chain This function should either return null or throw an exception if the key is unavailable.

Definition at line 111 of file credentials_manager.cpp.

113 {
114 return nullptr;
115}

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

◆ psk()

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

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().

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 25 of file credentials_manager.cpp.

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

◆ psk_identity()

std::string Botan::Credentials_Manager::psk_identity ( const std::string & type,
const std::string & context,
const std::string & identity_hint )
virtual
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 19 of file credentials_manager.cpp.

21 {
22 return "";
23}

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

◆ psk_identity_hint()

std::string Botan::Credentials_Manager::psk_identity_hint ( const std::string & type,
const std::string & context )
virtual
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 15 of file credentials_manager.cpp.

15 {
16 return "";
17}

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

◆ session_ticket_key()

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

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 123 of file credentials_manager.cpp.

123 {
124 return {};
125}

Referenced by psk().

◆ trusted_certificate_authorities()

std::vector< Certificate_Store * > Botan::Credentials_Manager::trusted_certificate_authorities ( const std::string & type,
const std::string & context )
virtual

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.

Definition at line 131 of file credentials_manager.cpp.

132 {
133 return std::vector<Certificate_Store*>();
134}

Referenced by Botan::TLS::Certificate_Request_13::maybe_create().


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