#include <credentials_manager.h>

Public Member Functions
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 ()

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)

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)

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

virtual std::shared_ptr< Private_Key >	private_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 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_types	specifies the key types desired ("RSA", "DSA", "ECDSA", etc), or empty if there is no preference by the caller.
cert_signature_schemes	specifies the signature types desired as signatures in the certificate(s) itself, or empty for no preference by the caller.
type	specifies the type of operation occurring
context	specifies a context relative to type.

Definition at line 96 of file credentials_manager.cpp.

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

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 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_type	specifies the type of key requested ("RSA", "DSA", "ECDSA", etc)
cert_signature_schemes	specifies the signature types desired as signatures in the certificate(s) itself, or empty for no preference by the caller.
type	specifies the type of operation occurring
context	specifies a context relative to type.

Definition at line 103 of file credentials_manager.cpp.

                             {
   return find_cert_chain({cert_key_type}, cert_signature_schemes, std::vector<X509_DN>(), type, 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

host	the host name for which a PSK is requested (may be empty)
whoami	the type of the host (client or server) that is requesting
identities	an optional filter for PSK identities to be returned (an empty list means: all identities are welcome)
prf	an 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.

                                                                                                             {
   auto psks = find_preshared_keys(host, whoami, identities, prf);
   if(psks.empty()) {
      return std::nullopt;
   } else {
      return std::move(psks.front());
   }
}

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.

                                                               {
   return {};
}

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_types	specifies the key types desired ("RSA", "DSA", "ECDSA", etc), or empty if there is no preference by the caller.
cert_signature_schemes	specifies the signature types desired as signatures in the certificate(s) itself, or empty for no preference by the caller.
acceptable_CAs	the CAs the requestor will accept (possibly empty)
type	specifies the type of operation occurring
context	specifies a context relative to type.

Definition at line 81 of file credentials_manager.cpp.

                             {
   return cert_chain(key_types, cert_signature_schemes, type, 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

host	the host name for which a PSK is requested (may be empty)
whoami	the type of the host (client or server) that is requesting
identities	an optional filter for PSK identities to be returned (an empty list means: all identities are welcome)
prf	an 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.

                                                                                                        {
   return {};
}

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_types	specifies the key types desired ("RSA", "DSA", "ECDSA", etc), or empty if there is no preference by the caller.
type	specifies the type of operation occurring
context	specifies a context relative to type.

Definition at line 90 of file credentials_manager.cpp.

                                                                                         {
   return nullptr;
}

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.

                                                                                      {
   return nullptr;
}

◆ 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

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.

Definition at line 111 of file credentials_manager.cpp.

                                                                                      {
   return nullptr;
}

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

type	specifies the type of operation occurring
context	specifies a context relative to type.
identity	is 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.

                                                                 {
   auto side = [&] {
      if(type == "tls-client") {
         return TLS::Connection_Side::Client;
      } else if(type == "tls-server") {
         return TLS::Connection_Side::Server;
      } else {
         throw Internal_Error(fmt("No PSK set for type {}", type));
      }
   }();
 
   // New applications should use the appropriate credentials methods. This is a
   // retrofit of the behaviour before Botan 3.2.0 and will be removed in a
   // future major release.
   //
   // TODO: deprecate `psk("...", "session-ticket" | "dtls-cookie-secret")`
   if(side == TLS::Connection_Side::Server && context == "session-ticket") {
      if(auto key = session_ticket_key(); !key.empty()) {
         return SymmetricKey(std::move(key));
      }
   } else if(side == TLS::Connection_Side::Server && context == "dtls-cookie-secret") {
      if(auto key = dtls_cookie_secret(); !key.empty()) {
         return SymmetricKey(std::move(key));
      }
   } else /* context is a host name */ {
      // Assuming that find_preshared_keys returns _exactly_ one or no keys when
      // searching for a single specific identity.
      if(auto psks = find_preshared_keys(context, side, {identity}); psks.size() == 1) {
         return SymmetricKey(psks.front().extract_master_secret());
      }
   }
 
   throw Internal_Error(fmt("No PSK set for identity {}", identity));
}

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

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

type	specifies the type of operation occurring
context	specifies a context relative to type.
identity_hint	was 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.

                                                                  {
   return "";
}

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

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

Parameters

type	specifies the type of operation occurring
context	specifies a context relative to type.

Returns: the PSK identity hint for this type/context

Definition at line 15 of file credentials_manager.cpp.

                                                                                       {
   return "";
}

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.

                                                               {
   return {};
}

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

type	specifies the type of operation occurring
context	specifies 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.

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

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

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

src/lib/tls/credentials_manager.h
src/lib/tls/credentials_manager.cpp

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ ~Credentials_Manager()

Member Function Documentation

◆ cert_chain()

◆ cert_chain_single_type()

◆ choose_preshared_key()

◆ dtls_cookie_secret()

◆ find_cert_chain()

◆ find_preshared_keys()

◆ find_raw_public_key()

◆ private_key_for() [1/2]

◆ private_key_for() [2/2]

◆ psk()

◆ psk_identity()

◆ psk_identity_hint()

◆ session_ticket_key()

◆ trusted_certificate_authorities()