Move TLS cert verification callback from Credentials_Manager to TLS::Callbacks

It is the only function in C_M which is called on to process session-specific
(and adversarially provided) inputs, rather than passively returning some credential
which is typically not session specific.

2 files changed, 37 insertions, 27 deletions

diff --git a/doc/manual/credentials_manager.rst b/doc/manual/credentials_manager.rst
index 04e9e3f2e..006d47343 100644
--- a/doc/manual/credentials_manager.rst
+++ b/doc/manual/credentials_manager.rst
@@ -29,31 +29,6 @@ implementation.
 
       The default implementation returns an empty list.
 
-   .. cpp::function:: void verify_certificate_chain( \
-         const std::string& type, \
-         const std::string& hostname, \
-         const std::vector<X509_Certificate>& cert_chain)
-
-      Verifies the certificate chain in *cert_chain*, assuming the
-      leaf certificate is the first element.
-
-      If *hostname* is set, additionally ``verify_certificate_chain``
-      will check that the leaf certificate has a DNS entry matching
-      *hostname*.
-
-      In the default implementation the *type* argument is passed,
-      along with *hostname*, to ``trusted_certificate_authorities`` to
-      find out what root(s) should be trusted for verifying this
-      certificate.
-
-      This function indicates a validation failure by throwing an
-      exception.
-
-      This function has a default implementation that probably
-      sufficies for most uses, however can be overrided for
-      implementing extra validation routines such as public key
-      pinning.
-
    .. cpp:function:: std::vector<X509_Certificate> cert_chain( \
          const std::vector<std::string>& cert_key_types, \
          const std::string& type, \
@@ -78,6 +53,15 @@ implementation.
       the leaf cert of a chain returned previously by ``cert_chain``
       or ``cert_chain_single_type``.
 
+In versions before 1.11.34, there was an additional function on `Credentials_Manager`
+
+   .. cpp::function:: void verify_certificate_chain( \
+         const std::string& type, \
+         const std::string& hostname, \
+         const std::vector<X509_Certificate>& cert_chain)
+
+This function has been replaced by `TLS::Callbacks::tls_verify_cert_chain`.
+
 SRP Authentication
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
diff --git a/doc/manual/tls.rst b/doc/manual/tls.rst
index 8508b0a70..2c8b7cf70 100644
--- a/doc/manual/tls.rst
+++ b/doc/manual/tls.rst
@@ -66,12 +66,12 @@ information about the connection.
      For DTLS, it is possible to receive records with the `rec_no` field out of
      order, or with gaps, cooresponding to reordered or lost datagrams.
 
- .. cpp:function:: void tls_alert(Alert alert) 
+ .. cpp:function:: void tls_alert(Alert alert)
 
      Mandatory. Called when an alert is received from the peer. Note that alerts
      received before the handshake is complete are not authenticated and
      could have been inserted by a MITM attacker.
-     
+
  .. cpp:function:: bool tls_session_established(const TLS::Session& session)
 
      Mandatory. Called whenever a negotiation completes. This can happen more
@@ -85,6 +85,32 @@ information about the connection.
      exception which will send a close message to the counterparty and
      reset the connection state.
 
+ .. cpp::function:: void tls_verify_cert_chain(const std::vector<X509_Certificate>& cert_chain, \
+                   const std::vector<Certificate_Store*>& trusted_roots, \
+                   Usage_Type usage, \
+                   const std::string& hostname)
+
+     Optional - default implementation should work for many users.
+     It can be overrided for implementing extra validation routines
+     such as public key pinning.
+
+     Verifies the certificate chain in *cert_chain*, assuming the
+     leaf certificate is the first element.
+
+     If usage is `Usage_Type::TLS_SERVER_AUTH`, then *hostname* should
+     match the information in the server certificate. If usage is
+     `TLS_CLIENT_AUTH`, then *hostname* specifies the host the client
+     is authenticating against (from SNI); the callback can use this for
+     any special site specific auth logic.
+
+     The `trusted_roots` parameter was returned by a call from the
+     associated `Credentials_Manager`.
+
+ .. cpp::function:: std::chrono::milliseconds tls_verify_cert_chain_ocsp_timeout() const
+
+     Called by default `tls_verify_cert_cert` to set timeout for OCSP requests.
+     Return 0 to disable OCSP. Current default is 0.
+
  .. cpp:function:: std::string tls_server_choose_app_protocol(const std::vector<std::string>& client_protos)
 
      Optional. Called by the server when a client includes a list of protocols in the ALPN extension.