Some documentation updates WRT DTLS and X.509 cert path processing

2 files changed, 100 insertions, 25 deletions

diff --git a/doc/manual/tls.rst b/doc/manual/tls.rst
index 805bca823..a5627e747 100644
--- a/doc/manual/tls.rst
+++ b/doc/manual/tls.rst
@@ -8,14 +8,10 @@ Botan supports both client and server implementations of the SSL/TLS
 protocols, including SSL v3, TLS v1.0, TLS v1.1, and TLS v1.2 (the
 insecure and obsolete SSL v2 protocol is not supported, beyond
 processing SSL v2 client hellos which some clients still send for
-backwards compatability with ancient servers). There is also some
-initial support for DTLS (v1.0 and v1.2), a variant of TLS adapted for
-operation on datagram transports such as UDP and SCTP, though as of
-1.11.6 DTLS handshaking does not support timeouts or retransmissions,
-so it can only be used over reliable datagrams (such as SCTP with
-reliable transmission turned on for DTLS handshake packets). DTLS
-support should be considered as beta quality and further testing is
-invited.
+backwards compatability with ancient servers). There is also support
+for DTLS (v1.0 and v1.2), a variant of TLS adapted for operation on
+datagram transports such as UDP and SCTP. DTLS support should be
+considered as beta quality and further testing is invited.
 
 The TLS implementation does not know anything about sockets or the
 network layer. Instead, it calls a user provided callback (hereafter
@@ -124,6 +120,14 @@ available:
       Returns true if and only if either a close notification or a
       fatal alert message have been either sent or received.
 
+   .. cpp:function:: bool timeout_check()
+
+      This function does nothing unless the channel represents a DTLS
+      connection and a handshake is actively in progress. In this case
+      it will check the current timeout state and potentially initiate
+      retransmission of handshake packets. Returns true if a timeout
+      condition occurred.
+
    .. cpp:function:: void renegotiate(bool force_full_renegotiation = false)
 
       Initiates a renegotiation. The counterparty is allowed by the
@@ -742,12 +746,11 @@ The ``TLS::Protocol_Version`` class represents a specific version:
 
  .. cpp:function:: static Protocol_Version latest_tls_version()
 
-      Returns the latest version of the TLS protocol known the the library
+      Returns the latest version of the TLS protocol known to the library
       (currently TLS v1.2)
 
  .. cpp:function:: static Protocol_Version latest_dtls_version()
 
-      Returns the latest version of the DTLS protocol known the the
+      Returns the latest version of the DTLS protocol known to the
       library (currently DTLS v1.2)
 
-
diff --git a/doc/manual/x509.rst b/doc/manual/x509.rst
index 8504126a5..211ccbaf9 100644
--- a/doc/manual/x509.rst
+++ b/doc/manual/x509.rst
@@ -28,6 +28,14 @@ in the :doc:`tls` protocol. A X.509 certificate is represented by
 
      Returns the distinguished name of the issuer
 
+ .. cpp:function:: std::string start_time() const
+
+     Returns the point in time the certificate becomes valid
+
+ .. cpp:function:: std::string end_time() const
+
+     Returns the point in time the certificate expires
+
 When working with certificates, the main class to remember is
 ``X509_Certificate``. You can read an object of this type, but you
 can't create one on the fly; a CA object is necessary for making a new
@@ -109,14 +117,14 @@ the handling.
 
  - Key Usage and Extended Key Usage: No problems known.
 
- - Basic Constraints: No problems known. The default for a v1/v2 certificate is
-   assume it's a CA if and only if the option "x509/default_to_ca" is set. A v3
-   certificate is marked as a CA if (and only if) the basic constraints
-   extension is present and set for a CA cert.
+ - Basic Constraints: No problems known. A self-signed v1 certificate
+   is assumed to be a CA, while a v3 certificate is marked as a CA if
+   and only if the basic constraints extension is present and set for
+   a CA cert.
 
  - Subject Alternative Names: Only the "rfc822Name", "dNSName", and
-   "uniformResourceIdentifier" fields will be stored; all others are
-   ignored.
+   "uniformResourceIdentifier" and raw IPv4 fields will be stored; all
+   others are ignored.
 
  - Issuer Alternative Names: Same restrictions as the Subject
    Alternative Names extension. New certificates generated by Botan
@@ -231,23 +239,87 @@ Path Validation
 
 The process of validating a certfificate chain up to a trusted root is
 called `path validation`, and in botan that operation is handled by a
-set of functions in ``x509path.h`` named ``x509_path_validate``.
+set of functions in ``x509path.h`` named ``x509_path_validate``:
+
+.. cpp:function:: Path_Validation_Result \
+     x509_path_validate(const X509_Certificate& end_cert, \
+     const Path_Validation_Restrictions& restrictions, \
+     const Certificate_Store& store)
+
+The result of the validation is returned as a class:
 
 .. cpp:class:: Path_Validation_Result
 
    Specifies the result of the validation
 
-.. cpp:class:: Path_Validation_Restrictions
+  .. cpp:function:: bool successful_validation() const
 
-   Specifies restrictions on the validation operation
+     Returns true if a certificate path from *end_cert* to a trusted
+     root was found and all path validation checks passed.
 
-.. cpp:function:: Path_Validation_Result \
-     x509_path_validate(const X509_Certificate& end_cert, \
-     const Path_Validation_Restrictions& restrictions, \
-     const Certificate_Store& store)
+  .. cpp:function:: std::string result_string() const
+
+     Returns a descriptive string of the validation status (for
+     instance "Verified", "Certificate is not yet valid", or
+     "Signature error"). This is the string value of
+     the `result` function below.
+
+  .. cpp:function:: const X509_Certificate& trust_root() const
+
+     If the validation was successful, returns the certificate which
+     is acting as the trust root for *end_cert*.
+
+   .. cpp:function:: const std::vector<X509_Certificate>& cert_path() const
+
+     Returns the full certificate path starting with the end entity
+     certificate and ending in the trust root.
+
+  .. cpp:function:: Certificate_Status_Code result() const
+
+     Returns the 'worst' error that occured during validation.  For
+     instance, we do not want an expired certificate with an invalid
+     signature to be reported to the user as being simply expired (a
+     relativly innocuous and common error) when the signature isn't
+     even valid.
+
+  .. cpp:function:: const std::vector<std::set<Certificate_Status_Code>>& all_statuses() const
+
+     For each certificate in the chain, returns a set of status which
+     indicate all errors which occurred during validation. This is
+     primarily useful for diagnostic purposes.
+
+  .. cpp:function:: std::set<std::string> trusted_hashes() const
+
+     Returns the set of all cryptographic hash functions which are
+     implicitly trusted for this validation to be correct.
+
+
+A :cpp:class:`Path_Validation_Restrictions` is passed to the path
+validator and specifies restrictions and options for the validation
+step. The two constructors are:
+
+  .. cpp:function:: Path_Validation_Restrictions(bool require_rev, \
+                                                 size_t minimum_key_strength, \
+                                                 bool ocsp_all_intermediates, \
+                                                 const std::set<std::string>& trusted_hashes)
+
+    If `require_rev` is true, then any path without revocation
+    information (CRL or OCSP check) is rejected with the code
+    `NO_REVOCATION_DATA`. The `minimum_key_strength` parameter
+    specifies the minimum strength of public key signature we will
+    accept is. The set of hash names `trusted_hashes` indicates which
+    hash functions we'll accept for cryptographic signatures.  Any
+    untrusted hash will cause the error case `UNTRUSTED_HASH`.
 
-    Validates a path
+  .. cpp:function:: Path_Validation_Restrictions(bool require_rev = false, \
+                                                 size_t minimum_key_strength = 80, \
+                                                 bool ocsp_all_intermediates = false)
 
+    A variant of the above with some convenient defaults. The current
+    default `minimum_key_strength` of 80 roughly cooresponds to 1024
+    bit RSA. The set of trusted hashes is set to all SHA-2 variants,
+    and, if `minimum_key_strength` is less than or equal to 80, then
+    SHA-1 signatures will also be accepted.
 
 Certificate Authorities
 ---------------------------------