path: root/doc/x509.rst

.. _x509_certificates:

X.509 Certificates and CRLs
=================================

A certificate is a binding between some identifying information
(called a *subject*) and a public key. This binding is asserted by a
signature on the certificate, which is placed there by some authority
(the *issuer*) that at least claims that it knows the subject named in
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, designed by ISO
and further hacked on by dozens (hundreds?) of other organizations.

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
certificate. So for the most part, you only have to worry about
reading them in, verifying the signatures, and getting the bits of
data in them (most commonly the public key, and the information about
the user of that key). An X.509v3 certificate can contain a literally
infinite number of items related to all kinds of things. Botan doesn't
support a lot of them, because nobody uses them and they're an
impossible mess to work with. This section only documents the most
commonly used ones of the ones that are supported; for the rest, read
``x509cert.h`` and ``asn1_obj.h`` (which has the definitions of
various common ASN.1 constructs used in X.509).

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.

Botan doesn't currently support any of the Unicode variants used in
ASN.1 (UTF-8, UCS-2, and UCS-4), any of which could be used for the
fields in the DN. This could be problematic, particularly in Asia and
other areas where non-ASCII characters are needed for most names. The
UTF-8 and UCS-2 string types *are* accepted (in fact, UTF-8 is used
when encoding much of the time), but if any of the characters included
in the string are not in ISO 8859-1 (ie 0 ... 255), an exception will
get thrown. Currently the ``ASN1_String`` type holds its data as ISO
8859-1 internally (regardless of local character set); this would have
to be changed to hold UCS-2 or UCS-4 in order to support Unicode
(also, many interfaces in the X.509 code would have to accept or
return a ``std::wstring`` instead of a ``std::string``).

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 (mailbox@example.com), 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.509v3 Extensions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

X.509v3 specifies a large number of possible extensions. Botan
supports some, but by no means all of them. This section lists which
ones are supported, and notes areas where there may be problems with
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.

 - Subject Alternative Names: Only the "rfc822Name", "dNSName", and
   "uniformResourceIdentifier" fields will be stored; all others are
   ignored.

 - Issuer Alternative Names: Same restrictions as the Subject
   Alternative Names extension. New certificates generated by Botan
   never include the issuer alternative name.

 - Authority Key Identifier: Only the version using KeyIdentifier is
   supported. If the GeneralNames version is used and the extension is
   critical, an exception is thrown. If both the KeyIdentifier and GeneralNames
   versions are present, then the KeyIdentifier will be used, and the
   GeneralNames ignored.

 - Subject Key Identifier: No problems known.

Revocation Lists
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

It will occasionally happen that a certificate must be revoked before
its expiration date. Examples of this happening include the private
key being compromised, or the user to which it has been assigned
leaving an organization. Certificate revocation lists are an answer to
this problem (though online certificate validation techniques are
starting to become somewhat more popular). Every once in a while the
CA will release a new CRL, listing all certificates that have been
revoked. Also included is various pieces of information like what time
a particular certificate was revoked, and for what reason. In most
systems, it is wise to support some form of certificate revocation,
and CRLs handle this easily.

For most users, processing a CRL is quite easy. All you have to do is
call the constructor, which will take a filename (or a
``DataSource&``). The CRLs can either be in raw BER/DER, or in PEM
format; the constructor will figure out which format without any extra
information. For example::

   X509_CRL crl1("crl1.der");

   DataSource_Stream in("crl2.pem");
   X509_CRL crl2(in);

After that, pass the ``X509_CRL`` object to a ``X509_Store`` object
with

.. cpp:function:: X509_Code X509_Store::add_crl(const X509_CRL& crl)

and all future verifications will take into account the certificates
listed, assuming ``add_crl`` returns ``VERIFIED``. If it doesn't
return ``VERIFIED``, then the return value is an error code signifying
that the CRL could not be processed due to some problem (which could
be something like the issuing certificate could not being found, an
invalid signature, or the CRL having some format problem).

Reading Certificates
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

``X509_Certificate`` has two constructors, each of which takes a source of
data; a filename to read, and a ``DataSource&``::

   X509_Certificate cert1("cert1.pem");

   /* This file contains two certificates, concatenated */
   DataSource_Stream in("certs2_and_3.pem");

   X509_Certificate cert2(in); // read the first cert
   X509_Certificate cert3(in); // read the second cert

Certificate Stores
----------------------------------------

An object of type ``Certificate_Store`` is a generalized interface to
an external source for certificates (and CRLs). Examples of such a
store would be one that looked up the certificates in a SQL database,
or by contacting a CGI script running on a HTTP server. There are
currently three mechanisms for looking up a certificate, and one for
retrieving CRLs. By default, most of these mechanisms will return an
empty ``std::vector`` of ``X509_Certificate``. This storage mechanism
is *only* queried when doing certificate validation: it allows you to
distribute only the root key with an application, and let some online
method handle getting all the other certificates that are needed to
validate an end entity certificate. In particular, the search routines
will not attempt to access the external database.

The three certificate lookup methods are ``by_SKID`` (Subject Key
Identifier), ``by_name`` (the CommonName DN entry), and ``by_email``
(stored in either the distinguished name, or in a
subjectAlternativeName extension). The name and email versions take a
``std::string``, while the SKID version takes a
``secure_vector<byte>`` containing the subject key identifier in raw
binary. You can choose not to implement ``by_name`` or ``by_email``,
but ``by_SKID`` is mandatory to implement, and, currently, is the only
version that is used by ``X509_Store``.

Finally, there is a method for finding CRLs, called ``get_crls_for``,
that takes an ``X509_Certificate`` object, and returns a
``std::vector`` of ``X509_CRL``. While normally there will be only one
CRL, the use of the vector makes it easy to return no CRLs (eg, if the
certificate store doesn't support retrieving them), or return multiple
ones (for example, if the certificate store can't determine precisely
which key was used to sign the certificate). Implementing the function
is optional, and by default will return no CRLs. If it is available,
it will be used by ``X509_CRL``.

As for using such a store, you have to tell ``X509_Store`` about it
with

.. cpp:function:: void X509_Store::add_new_certstore(Certificate_Store* new_store)

  The store object will be owned by (and deleted by) ``X509_Store``,
  so make sure to allocate it with ``new``.

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

Certificate Authorities
---------------------------------

A CA is represented by the type ``X509_CA``, which can be found in
``x509_ca.h``. A CA always needs its own certificate, which can either
be a self-signed certificate (see below on how to create one) or one
issued by another CA (see the section on PKCS #10 requests). Creating
a CA object is done by the following constructor:

.. cpp:function:: X509_CA::X509_CA(const X509_Certificate& cert, \
   const Private_Key& key)

The private key is the private key corresponding to the public key in the
CA's certificate.

Requests for new certificates are supplied to a CA in the form on PKCS
#10 certificate requests (called a ``PKCS10_Request`` object in
Botan). These are decoded in a similar manner to
certificates/CRLs/etc. A request is vetted by humans (who somehow
verify that the name in the request corresponds to the name of the
entity who requested it), and then signed by a CA key, generating a
new certificate:

.. cpp:function:: X509_Certificate \
   X509_CA::sign_request(const PKCS10_Request& req) const

Here's an example:

.. literalinclude examples/ca.cpp

Generating CRLs
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

As mentioned previously, the ability to process CRLs is highly
important in many PKI systems. In fact, according to strict X.509
rules, you must not validate any certificate if the appropriate CRLs
are not available (though hardly any systems are that strict). In any
case, a CA should have a valid CRL available at all times.

Of course, you might be wondering what to do if no certificates have
been revoked. Never fear; empty CRLs, which revoke nothing at all, can
be issued. To generate a new, empty CRL, just call

.. cpp:function:: X509_CRL X509_CA::new_crl(u32bit seconds_to_expiration = 0)

  This function will return a new, empty CRL. The
  ``seconds_to_expiration`` parameter is the number of seconds before
  the CRL expires. If it is set to the (default) value of zero, then a
  reasonable default (currently 7 days) will be used.

On the other hand, you may have issued a CRL before. In that case, you will
want to issue a new CRL that contains all previously revoked
certificates, along with any new ones. This is done by calling

.. cpp:function:: X509_CRL X509_CA::update_crl(const X509_CRL& old_crl, \
   std::vector<CRL_Entry> new_revoked, size_t seconds_to_expiration = 0)

  Where ``X509_CRL`` is the last CRL this CA issued, and
  ``new_revoked`` is a list of any newly revoked certificates. The
  function returns a new ``X509_CRL`` to make available for
  clients.

The ``CRL_Entry`` type is a structure that contains, at a minimum, the serial
number of the revoked certificate. As serial numbers are never repeated, the
pairing of an issuer and a serial number (should) distinctly identify any
certificate. In this case, we represent the serial number as a
``secure_vector<byte>`` called ``serial``. There are two additional (optional)
values, an enumeration called ``CRL_Code`` that specifies the reason for
revocation (``reason``), and an object that represents the time that the
certificate became invalid (if this information is known).

If you wish to remove an old entry from the CRL, insert a new entry for the
same cert, with a ``reason`` code of ``DELETE_CRL_ENTRY``. For example, if a
revoked certificate has expired 'normally', there is no reason to continue to
explicitly revoke it, since clients will reject the cert as expired in any
case.

Self-Signed Certificates
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Generating a new self-signed certificate can often be useful, for
example when setting up a new root CA, or for use in specialized
protocols. The library provides a utility function for this:

.. cpp:function:: X509_Certificate create_self_signed_cert( \
   const X509_Cert_Options& opts, const Private_Key& key)

   Where *key* is the private key you wish to use (the public key,
   used in the certificate itself, is extracted from the private key),
   and *opts* is an structure that has various bits of information
   that will be used in creating the certificate (this structure, and
   its use, is discussed below).

An example:

.. literalinclude:: examples/self_sig.cpp

Creating PKCS #10 Requests
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Also in ``x509self.h``, there is a function for generating new PKCS #10
certificate requests:

.. cpp:function:: PKCS10_Request create_cert_req( \
   const X509_Cert_Options& opts, const Private_Key& key)

This function acts quite similarly to
:cpp:func:`create_self_signed_cert`, except it instead returns a PKCS
#10 certificate request. After creating it, one would typically
transmit it to a CA, who signs it and returns a freshly minted X.509
certificate.

An example:

.. literalinclude:: examples/pkcs10.cpp

Certificate Options
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

What is this ``X509_Cert_Options`` thing we've been passing around?
It's a class representing a bunch of information that will end up
being stored into the certificate. This information comes in 3 major
flavors: information about the subject (CA or end-user), the validity
period of the certificate, and restrictions on the usage of the
certificate.

First and foremost is a number of ``std::string`` members, which
contains various bits of information about the user: ``common_name``,
``serial_number``, ``country``, ``organization``, ``org_unit``,
``locality``, ``state``, ``email``, ``dns_name``, and ``uri``. As many
of these as possible should be filled it (especially an email
address), though the only required ones are ``common_name`` and
``country``.

There is another value that is only useful when creating a PKCS #10
request, which is called ``challenge``. This is a challenge password,
which you can later use to request certificate revocation (*if* the CA
supports doing revocations in this manner).

Then there is the validity period; these are set with ``not_before``
and ``not_after``. Both of these functions also take a
``std::string``, which specifies when the certificate should start
being valid, and when it should stop being valid. If you don't set the
starting validity period, it will automatically choose the current
time. If you don't set the ending time, it will choose the starting
time plus a default time period. The arguments to these functions
specify the time in the following format: "2002/11/27 1:50:14". The
time is in 24-hour format, and the date is encoded as
year/month/day. The date must be specified, but you can omit the time
or trailing parts of it, for example "2002/11/27 1:50" or
"2002/11/27".

Lastly, you can set constraints on a key. The one you're mostly likely
to want to use is to create (or request) a CA certificate, which can
be done by calling the member function ``CA_key``. This should only be
used when needed.

Other constraints can be set by calling the member functions
``add_constraints`` and ``add_ex_constraints``. The first takes a
``Key_Constraints`` value, and replaces any previously set value. If
no value is set, then the certificate key is marked as being valid for
any usage.  You can set it to any of the following (for more than one
usage, OR them together): ``DIGITAL_SIGNATURE``, ``NON_REPUDIATION``,
``KEY_ENCIPHERMENT``, ``DATA_ENCIPHERMENT``, ``KEY_AGREEMENT``,
``KEY_CERT_SIGN``, ``CRL_SIGN``, ``ENCIPHER_ONLY``,
``DECIPHER_ONLY``. Many of these have quite special semantics, so you
should either consult the appropriate standards document (such as RFC
3280), or just not call ``add_constraints``, in which case the
appropriate values will be chosen for you.

The second function, ``add_ex_constraints``, allows you to specify an
OID that has some meaning with regards to restricting the key to
particular usages. You can, if you wish, specify any OID you like, but
there is a set of standard ones that other applications will be able
to understand. These are the ones specified by the PKIX standard, and
are named "PKIX.ServerAuth" (for TLS server authentication),
"PKIX.ClientAuth" (for TLS client authentication), "PKIX.CodeSigning",
"PKIX.EmailProtection" (most likely for use with S/MIME),
"PKIX.IPsecUser", "PKIX.IPsecTunnel", "PKIX.IPsecEndSystem", and
"PKIX.TimeStamping". You can call "add_ex_constraints" any number of
times - each new OID will be added to the list to include in the
certificate.