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

1 files changed, 86 insertions, 14 deletions

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