aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorlloyd <[email protected]>2014-10-06 01:30:42 +0000
committerlloyd <[email protected]>2014-10-06 01:30:42 +0000
commit5e54dfe49ceb6ce5a9891477d190833399a0bda0 (patch)
tree425be128d0999faee0c165e597e6963828a96818
parent2d6a5e530c8db496aad61b5a9ab3107dd1ed646b (diff)
Some documentation updates WRT DTLS and X.509 cert path processing
-rw-r--r--doc/manual/tls.rst25
-rw-r--r--doc/manual/x509.rst100
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
---------------------------------