WIP

src/lib/tls/credentials_manager.cpp

@@ -62,18 +62,18 @@ SymmetricKey Credentials_Manager::psk(const std::string& type,
 
 std::vector<TLS::PresharedKey> Credentials_Manager::find_preshared_keys(
  std::string_view /* host */,
- TLS::Connection_Side /* peer_type */,
+ TLS::Connection_Side /* whoami */,
  const std::vector<TLS::PresharedKeyID>& /* identities */,
  const std::optional<std::string>& /* prf */) {
  return {};
 }
 
 std::optional<TLS::PresharedKey> Credentials_Manager::choose_preshared_key(
  std::string_view host,
- TLS::Connection_Side peer_type,
+ TLS::Connection_Side whoami,
  const std::vector<TLS::PresharedKeyID>& identities,
  const std::optional<std::string>& prf) {
- auto psks = find_preshared_keys(host, peer_type, identities, prf);
+ auto psks = find_preshared_keys(host, whoami, identities, prf);
  if(psks.empty()) {
  return std::nullopt;
  } else {

src/lib/tls/credentials_manager.h

@@ -135,7 +135,24 @@ class BOTAN_PUBLIC_API(2, 0) Credentials_Manager {
  const std::string& type,
  const std::string& context);
 
+ /**
+ * 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.
+ */
  virtual secure_vector<uint8_t> session_ticket_key();
+
+ /**
+ * 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
+ */
  virtual secure_vector<uint8_t> dtls_cookie_secret();
 
  /**
@@ -156,24 +173,75 @@ class BOTAN_PUBLIC_API(2, 0) Credentials_Manager {
  const std::string& identity_hint);
 
  /**
+ * Retrieves the PSK with the given @p identity or throws an exception.
+ * It's default implementation uses find_preshared_keys() with @p 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 @p 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().
+ *
  * @param type specifies the type of operation occurring
  * @param context specifies a context relative to type.
  * @param identity is a PSK identity previously returned by
  psk_identity for the same type and context.
  * @return the PSK used for identity, or throw an exception if no
- * key exists
+ *  key exists
  */
  virtual SymmetricKey psk(const std::string& type, const std::string& context, const std::string& identity);
 
+ /**
+ * Filters all available PSKs with the given criterions. Note that omitted
+ * criterions (like an empty @p identities list or an unspecified @p 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.
+ *
+ * @param host the host name for which a PSK is requested (may be empty)
+ * @param whoami the type of the host (client or server) that is requesting
+ * @param identities an optional filter for PSK identities to be returned
+ * (an empty list means: all identities are welcome)
+ * @param 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
+ */
  virtual std::vector<TLS::PresharedKey> find_preshared_keys(
  std::string_view host,
- TLS::Connection_Side peer_type,
+ TLS::Connection_Side whoami,
  const std::vector<TLS::PresharedKeyID>& identities = {},
  const std::optional<std::string>& prf = std::nullopt);
 
+ /**
+ * Selects a single PSK identity from the given @p 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.
+ *
+ * @param host the host name for which a PSK is requested (may be empty)
+ * @param whoami the type of the host (client or server) that is requesting
+ * @param identities an optional filter for PSK identities to be returned
+ * (an empty list means: all identities are welcome)
+ * @param 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
+ */
  virtual std::optional<TLS::PresharedKey> choose_preshared_key(
  std::string_view host,
- TLS::Connection_Side peer_type,
+ TLS::Connection_Side whoami,
  const std::vector<TLS::PresharedKeyID>& identities,
  const std::optional<std::string>& prf = std::nullopt);
 };