Improve X.509 documentation

GH #1428

1 files changed, 141 insertions, 85 deletions

diff --git a/doc/manual/x509.rst b/doc/manual/x509.rst
index f9431c362..7bbce5e2e 100644
--- a/doc/manual/x509.rst
+++ b/doc/manual/x509.rst
@@ -10,24 +10,50 @@ signature on the certificate, which is placed there by some authority
 the certificate really "owns" the private key corresponding to the
 public key in the certificate.
 
-The major certificate format in use today is X.509v3, used for instance
-in the :doc:`tls` protocol. A X.509 certificate is represented by
+The major certificate format in use today is X.509v3, used for instance in the
+:doc:`tls` protocol. A X.509 certificate is represented by the class
+``X509_Certificate``. The data of an X.509 certificate is stored as a
+``shared_ptr`` to a structure containing the decoded information. So copying
+``X509_Certificate`` objects is quite cheap.
+
 
 .. cpp:class:: X509_Certificate
 
- .. cpp:function:: X509_Certificate(const std::string& filename)
+  .. cpp:function:: X509_Certificate(const std::string& filename)
 
      Load a certificate from a file. PEM or DER is accepted.
 
- .. cpp:function:: X509_Certificate(const std::vector<uint8_t>& in)
+  .. cpp:function:: X509_Certificate(const std::vector<uint8_t>& in)
 
      Load a certificate from a byte string.
 
- .. cpp:function:: X509_Certificate(DataSource& source)
+  .. cpp:function:: X509_Certificate(DataSource& source)
 
      Load a certificate from an abstract ``DataSource``.
 
- .. cpp:function:: std::unique_ptr<Public_Key> load_subject_public_key() const
+  .. cpp:function:: X509_DN subject_dn() const
+
+     Returns the distinguished name (DN) of the certificate's subject. This is
+     the primary place where information about the subject of the certificate is
+     stored. However "modern" information that doesn't fit in the X.500
+     framework, such as DNS name, email, IP address, or XMPP address, appears
+     instead in the subject alternative name.
+
+  .. cpp:function:: X509_DN issuer_dn() const
+
+     Returns the distinguished name (DN) of the certificate's issuer, ie the CA
+     that issued this certificate.
+
+  .. cpp:function:: const AlternativeName& subject_alt_name() const
+
+      Return the subjects alternative name. This is used to store
+      values like associated URIs, DNS addresses, and email addresses.
+
+  .. cpp:function:: const AlternativeName& issuer_alt_name() const
+
+      Return alternative names for the issuer.
+
+  .. cpp:function:: std::unique_ptr<Public_Key> load_subject_public_key() const
 
      Deserialize the stored public key and return a new object. This
      might throw, if it happens that the public key object stored in
@@ -38,45 +64,72 @@ in the :doc:`tls` protocol. A X.509 certificate is represented by
      with the returned object. It may be any type of key, in principle, though
      RSA and ECDSA are most common.
 
- .. cpp:function:: std::vector<uint8_t> serial_number() const
+  .. cpp:function:: std::vector<uint8_t> subject_public_key_bits() const
+
+     Return the binary encoding of the subject public key. This value (or a hash of
+     it) is used in various protocols, eg for public key pinning.
+
+  .. cpp:function:: AlgorithmIdentifier subject_public_key_algo() const
+
+     Return an algorithm identifier that identifies the algorithm used in the
+     subject's public key.
+
+  .. cpp:function:: std::vector<uint8_t> serial_number() const
 
      Return the certificates serial number. The tuple of issuer DN and
      serial number should be unique.
 
- .. cpp:function:: X509_DN subject_dn() const
+  .. cpp:function:: std::vector<uint8> raw_subject_dn() const
 
-     Returns the distinguished name (DN) of the certificate's subject.
+     Return the binary encoding of the subject DN.
 
- .. cpp:function:: X509_DN issuer_dn() const
+  .. cpp:function:: std::vector<uint8> raw_issuer_dn() const
 
-     Returns the distinguished name (DN) of the certificate's issuer
+     Return the binary encoding of the issuer DN.
 
- .. cpp:function:: X509_Time not_before() const
+  .. cpp:function:: X509_Time not_before() const
 
      Returns the point in time the certificate becomes valid
 
- .. cpp:function:: X509_Time not_after() const
+  .. cpp:function:: X509_Time not_after() const
 
      Returns the point in time the certificate expires
 
- .. cpp:function:: const Extensions& v3_extensions() const
+  .. cpp:function:: const Extensions& v3_extensions() const
 
      Returns all extensions of this certificate. You can use this
      to examine any extension data associated with the certificate,
      including custom extensions the library doesn't know about.
 
-  .. cpp:function:: const AlternativeName& subject_alt_name() const
+  .. cpp:function:: std::vector<uint8_t> authority_key_id() const
 
-      Return the subjects alternative name. This is used to store
-      values like associated URIs, DNS addresses, and email addresses.
+      Return the authority key id, if set. This is an arbitrary string; in the
+      issuing certificate this will be the subject key id.
 
-  .. cpp:function:: const AlternativeName& issuer_alt_name() const
+  .. cpp:function:: std::vector<uint8_t> subject_key_id() const
 
-      Return alternative names for the issuer.
+      Return the subject key id, if set.
+
+  .. cpp:function:: bool allowed_extended_usage(const OID& usage) const
+
+      Return true if and only if the usage OID appears in the extended key usage
+      extension. Also will return true if the extended key usage extension is
+      not used in the current certificate.
+
+  .. cpp:function: std::vector<OID> extended_key_usage() const
 
-  .. cpp:function:: std::string fingerprint(const std::string& hash_name = "SHA-1") const
+      Return the list of extended key usages. May be empty.
 
-      Return a fingerprint for the certificate.
+  .. cpp:function:: std::string fingerprint(const std::string& hash_fn = "SHA-1") const
+
+      Return a fingerprint for the certificate, which is basically just a hash
+      of the binary contents. Normally SHA-1 or SHA-256 is used, but any hash
+      function is allowed.
+
+  .. cpp:function:: bool matches_dns_name(const std::string& name) const
+
+     Returns true if ``name`` matches the DNS name in the certificate. This function
+     accounts for wildcard certificates.
 
   .. cpp:function:: Key_Constraints constraints() const
 
@@ -99,64 +152,51 @@ in the :doc:`tls` protocol. A X.509 certificate is represented by
 
       Returns a free-form human readable string describing the certificate.
 
-The ``X509_Certificate`` class has several other functions not described here.
-See the header ``x509cert.h`` for details.
-
-The data of an X.509 certificate is stored as a ``shared_ptr`` to a structure
-containing the decoded information. So copying ``X509_Certificate`` objects is
-quite cheap.
-
-So what's in an X.509 certificate?
------------------------------------
-
-Obviously, you want to be able to get the public key. This is achieved
-by calling the member function ``subject_public_key``, which will
-return a ``Public_Key``\*. As to what to do with this, read about
-``load_key`` in :ref:`serializing_public_keys`. In the general case,
-this could be any kind of public key, though 99% of the time it will
-be an RSA key. However, Diffie-Hellman, DSA, and ECDSA keys are also
-supported, so be careful about how you treat this. It is also a wise
-idea to examine the value returned by ``constraints``, to see what
-uses the public key is approved for.
-
-The second major piece of information you'll want is the
-name/email/etc of the person to whom this certificate is
-assigned. Here is where things get a little nasty. X.509v3 has two
-(well, mostly just two...) different places where you can stick
-information about the user: the *subject* field, and in an extension
-called *subjectAlternativeName*. The *subject* field is supposed to
-only included the following information: country, organization, an
-organizational sub-unit name, and a so-called common name. The common
-name is usually the name of the person, or it could be a title
-associated with a position of some sort in the organization. It may
-also include fields for state/province and locality. What a locality
-is, nobody knows, but it's usually given as a city name.
-
-Like the distinguished names, subject alternative names can contain a lot of
-things that Botan will flat out ignore (most of which you would likely never
-want to use). However, there are three very useful pieces of information that
-this extension might hold: an email address ([email protected]), a DNS name
-(somehost.example.com), or a URI (http://www.example.com).
-
-So, how to get the information? Call ``subject_info`` with the name of
-the piece of information you want, and it will return a
-``std::string`` that is either empty (signifying that the certificate
-doesn't have this information), or has the information
-requested. There are several names for each possible item, but the
-most easily readable ones are: "Name", "Country", "Organization",
-"Organizational Unit", "Locality", "State", "RFC822", "URI", and
-"DNS". These values are returned as a ``std::string``.
-
-You can also get information about the issuer of the certificate in the same
-way, using ``issuer_info``.
+X.509 Distinguished Names
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. cpp:class:: X509_DN
+
+  .. cpp:function:: bool has_field(const std::string& attr) const
+
+      Returns true if ``get_attribute`` or ``get_first_attribute`` will return a value.
+
+  .. cpp:function:: std::vector<std::string> get_attribute(const std::string& attr) const
+
+      Return all attributes associated with a certain attribute type.
+
+  .. cpp:function:: std::string get_first_attribute(const std::string& attr) const
+
+      Like ``get_attribute`` but returns just the first attribute, or
+      empty if the DN has no attribute of the specified type.
+
+  .. cpp:function:: std::multimap<OID, std::string> get_attributes() const
+
+      Get all attributes of the DN. The OID maps to a DN component such as
+      2.5.4.10 ("Organization"), and the strings are UTF-8 encoded.
+
+  .. cpp:function:: std::multimap<std::string, std::string> contents() const
+
+      Similar to ``get_attributes``, but the OIDs are decoded to strings.
+
+  .. cpp:function:: void add_attribute(const std::string& key, const std::string& val)
+
+      Add an attribute to a DN.
+
+  .. cpp:function:: void add_attribute(const OID& oid, const std::string& val)
+
+      Add an attribute to a DN using an OID instead of string-valued attribute type.
+
+The ``X509_DN`` type also supports iostream extraction and insertion operators,
+for formatted input and output.
 
 X.509v3 Extensions
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-X.509v3 specifies a large number of possible extensions. Botan
-supports some, but by no means all of them.
-The following listing lists which X.509v3 extensions are supported
-and notes areas where there may be problems with the handling.
+X.509v3 specifies a large number of possible extensions. Botan supports some,
+but by no means all of them. The following listing lists which X.509v3
+extensions are supported and notes areas where there may be problems with the
+handling.
 
  - Key Usage and Extended Key Usage: No problems known.
 
@@ -199,10 +239,16 @@ functions are provided to search them.
 
  .. cpp:function:: void add(Certificate_Extension* extn, bool critical = false)
 
-     Adds a new extension to the list. ``critical`` specifies whether the extension
-     should be marked as critical.
+     Adds a new extension to the extensions object. If an extension of the same
+     type already exists, ``extn`` will replace it. If ``critical`` is true the
+     extension will be marked as critical in the encoding.
 
- .. cpp:function:: replace(Certificate_Extension* extn, bool critical = false)
+ .. cpp:function:: bool add_new(Certificate_Extension* extn, bool critical = false)
+
+    Like ``add`` but an existing extension will not be replaced. Returns true if the
+    extension was used, false if an extension of the same type was already in place.
+
+ .. cpp:function:: void replace(Certificate_Extension* extn, bool critical = false)
 
      Adds an extension to the list or replaces it, if the same
      extension was already added
@@ -641,6 +687,20 @@ This function acts quite similarly to
 transmit it to a CA, who signs it and returns a freshly minted X.509
 certificate.
 
+.. cpp:function:: PKCS10_Request PKCS10_Request::create(const Private_Key& key, \
+                                   const X509_DN& subject_dn, \
+                                   const Extensions& extensions, \
+                                   const std::string& hash_fn, \
+                                   RandomNumberGenerator& rng, \
+                                   const std::string& padding_scheme = "", \
+                                   const std::string& challenge = "")
+
+  This function (added in 2.5) is similar to ``create_cert_req`` but allows
+  specifying all the parameters directly. In fact ``create_cert_req`` just
+  creates the DN and extensions from the options, then uses this call to
+  actually create the ``PKCS10_Request`` object.
+
+
 Certificate Options
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -718,13 +778,9 @@ are named "PKIX.ServerAuth" (for TLS server authentication),
 times - each new OID will be added to the list to include in the
 certificate.
 
-Lastly, you can add any X.509v3 extensions in the `extensions`
-member. This is really only useful if you want to encode custom
-extensions in the certificate. Most users probably won't need this.
-Note that extensions added this way will be overwritten by an
-``X509_CA`` if also added by the ``X509_CA`` itself. This currently
-includes the Basic Constraints, Key Usage, Authority Key ID, Subject
-Key ID, Subject Alternative Name and Extended Key Usage extension.
+Lastly, you can add any X.509v3 extensions in the `extensions` member, which is
+useful if you want to encode a custom extension, or encode an extension in a way
+differently from how Botan defaults.
 
 OCSP Requests
 ----------------------------------------