<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Certificate Handling — Botan</title>
<link rel="stylesheet" href="_static/agogo.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: './',
VERSION: '1.10.17',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="top" title="Botan" href="contents.html" />
<link rel="next" title="SSL and TLS" href="ssl.html" />
<link rel="prev" title="Public Key Cryptography" href="pubkey.html" />
</head>
<body role="document">
<div class="header-wrapper">
<div class="header">
<h1>Botan</h1>
</div>
</div>
<div class="content-wrapper">
<div class="content">
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="certificate-handling">
<span id="x509-certificates"></span><h1>Certificate Handling<a class="headerlink" href="#certificate-handling" title="Permalink to this headline">¶</a></h1>
<p>A certificate is a binding between some identifying information
(called a <em>subject</em>) and a public key. This binding is asserted by a
signature on the certificate, which is placed there by some authority
(the <em>issuer</em>) 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.</p>
<p>The major certificate format in use today is X.509v3, designed by ISO
and further hacked on by dozens (hundreds?) of other organizations.</p>
<p>When working with certificates, the main class to remember is
<code class="docutils literal"><span class="pre">X509_Certificate</span></code>. 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
<code class="docutils literal"><span class="pre">x509cert.h</span></code> and <code class="docutils literal"><span class="pre">asn1_obj.h</span></code> (which has the definitions of various common
ASN.1 constructs used in X.509).</p>
<div class="section" id="so-what-s-in-an-x-509-certificate">
<h2>So what’s in an X.509 certificate?<a class="headerlink" href="#so-what-s-in-an-x-509-certificate" title="Permalink to this headline">¶</a></h2>
<p>Obviously, you want to be able to get the public key. This is achieved by
calling the member function <code class="docutils literal"><span class="pre">subject_public_key</span></code>, which will return a
<code class="docutils literal"><span class="pre">Public_Key</span></code>*. As to what to do with this, read about <code class="docutils literal"><span class="pre">load_key</span></code> in
<a class="reference internal" href="pubkey.html#serializing-public-keys"><span class="std std-ref">Serializing Public Keys</span></a>. 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
<code class="docutils literal"><span class="pre">constraints</span></code>, to see what uses the public key is approved for.</p>
<p>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 <em>subject</em> field, and in an extension
called <em>subjectAlternativeName</em>. The <em>subject</em> 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.</p>
<p>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 <em>are</em> 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 <code class="docutils literal"><span class="pre">ASN1_String</span></code> 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 <code class="docutils literal"><span class="pre">std::wstring</span></code> instead of a <code class="docutils literal"><span class="pre">std::string</span></code>).</p>
<p>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 (<a class="reference external" href="mailto:mailbox%40example.com">mailbox<span>@</span>example<span>.</span>com</a>), a DNS name
(somehost.example.com), or a URI (<a class="reference external" href="http://www.example.com">http://www.example.com</a>).</p>
<p>So, how to get the information? Call <code class="docutils literal"><span class="pre">subject_info</span></code> with the name of the
piece of information you want, and it will return a <code class="docutils literal"><span class="pre">std::string</span></code> 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 <code class="docutils literal"><span class="pre">std::string</span></code>.</p>
<p>You can also get information about the issuer of the certificate in the same
way, using <code class="docutils literal"><span class="pre">issuer_info</span></code>.</p>
<div class="section" id="x-509v3-extensions">
<h3>X.509v3 Extensions<a class="headerlink" href="#x-509v3-extensions" title="Permalink to this headline">¶</a></h3>
<p>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.</p>
<blockquote>
<div><ul class="simple">
<li>Key Usage and Extended Key Usage: No problems known.</li>
<li>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.</li>
<li>Subject Alternative Names: Only the “rfc822Name”, “dNSName”, and
“uniformResourceIdentifier” fields will be stored; all others are
ignored.</li>
<li>Issuer Alternative Names: Same restrictions as the Subject
Alternative Names extension. New certificates generated by Botan
never include the issuer alternative name.</li>
<li>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.</li>
<li>Subject Key Identifier: No problems known.</li>
</ul>
</div></blockquote>
</div>
<div class="section" id="revocation-lists">
<h3>Revocation Lists<a class="headerlink" href="#revocation-lists" title="Permalink to this headline">¶</a></h3>
<p>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.</p>
<p>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 <code class="docutils literal"><span class="pre">DataSource&</span></code>). 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:</p>
<div class="highlight-cpp"><div class="highlight"><pre><span></span><span class="n">X509_CRL</span> <span class="nf">crl1</span><span class="p">(</span><span class="s">"crl1.der"</span><span class="p">);</span>
<span class="n">DataSource_Stream</span> <span class="nf">in</span><span class="p">(</span><span class="s">"crl2.pem"</span><span class="p">);</span>
<span class="n">X509_CRL</span> <span class="nf">crl2</span><span class="p">(</span><span class="n">in</span><span class="p">);</span>
</pre></div>
</div>
<p>After that, pass the <code class="docutils literal"><span class="pre">X509_CRL</span></code> object to a <code class="docutils literal"><span class="pre">X509_Store</span></code> object
with</p>
<dl class="function">
<dt id="_CPPv2N10X509_Store7add_crlERK8X509_CRL">
<span id="X509_Store::add_crl__X509_CRLCR"></span>X509_Code <code class="descclassname">X509_Store::</code><code class="descname">add_crl</code><span class="sig-paren">(</span><em class="property">const</em> X509_CRL &<em>crl</em><span class="sig-paren">)</span><a class="headerlink" href="#_CPPv2N10X509_Store7add_crlERK8X509_CRL" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p>and all future verifications will take into account the certificates
listed, assuming <code class="docutils literal"><span class="pre">add_crl</span></code> returns <code class="docutils literal"><span class="pre">VERIFIED</span></code>. If it doesn’t
return <code class="docutils literal"><span class="pre">VERIFIED</span></code>, 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). For more
about the <code class="docutils literal"><span class="pre">X509_Store</span></code> API, read <a class="reference internal" href="#x509-store"><span class="std std-ref">Storing and Using Certificates</span></a>.</p>
</div>
</div>
<div class="section" id="reading-certificates">
<h2>Reading Certificates<a class="headerlink" href="#reading-certificates" title="Permalink to this headline">¶</a></h2>
<p><code class="docutils literal"><span class="pre">X509_Certificate</span></code> has two constructors, each of which takes a source of
data; a filename to read, and a <code class="docutils literal"><span class="pre">DataSource&</span></code>:</p>
<div class="highlight-cpp"><div class="highlight"><pre><span></span><span class="n">X509_Certificate</span> <span class="nf">cert1</span><span class="p">(</span><span class="s">"cert1.pem"</span><span class="p">);</span>
<span class="cm">/* This file contains two certificates, concatenated */</span>
<span class="n">DataSource_Stream</span> <span class="nf">in</span><span class="p">(</span><span class="s">"certs2_and_3.pem"</span><span class="p">);</span>
<span class="n">X509_Certificate</span> <span class="nf">cert2</span><span class="p">(</span><span class="n">in</span><span class="p">);</span> <span class="c1">// read the first cert</span>
<span class="n">X509_Certificate</span> <span class="nf">cert3</span><span class="p">(</span><span class="n">in</span><span class="p">);</span> <span class="c1">// read the second cert</span>
</pre></div>
</div>
</div>
<div class="section" id="storing-and-using-certificates">
<span id="x509-store"></span><h2>Storing and Using Certificates<a class="headerlink" href="#storing-and-using-certificates" title="Permalink to this headline">¶</a></h2>
<p>If you read a certificate, you probably want to verify the signature on
it. However, consider that to do so, we may have to verify the signature on the
certificate that we used to verify the first certificate, and on and on until
we hit the top of the certificate tree somewhere. It would be a might huge pain
to have to handle all of that manually in every application, so there is
something that does it for you: <code class="docutils literal"><span class="pre">X509_Store</span></code>.</p>
<p>The basic operations are: put certificates and CRLs into it, search for
certificates, and attempt to verify certificates. That’s about it. In the
future, there will be support for online retrieval of certificates and CRLs (eg
with the HTTP cert-store interface currently under consideration by PKIX).</p>
<div class="section" id="adding-certificates">
<h3>Adding Certificates<a class="headerlink" href="#adding-certificates" title="Permalink to this headline">¶</a></h3>
<p>You can add new certificates to a certificate store using any of these
functions:</p>
<dl class="function">
<dt id="_CPPv2N10X509_Store8add_certERK16X509_Certificateb">
<span id="X509_Store::add_cert__X509_CertificateCR.b"></span>void <code class="descclassname">X509_Store::</code><code class="descname">add_cert</code><span class="sig-paren">(</span><em class="property">const</em> X509_Certificate &<em>cert</em>, bool <em>trusted</em> = false<span class="sig-paren">)</span><a class="headerlink" href="#_CPPv2N10X509_Store8add_certERK16X509_Certificateb" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="function">
<dt id="_CPPv2N10X509_Store8add_certER10DataSource">
<span id="X509_Store::add_cert__DataSourceR"></span>void <code class="descclassname">X509_Store::</code><code class="descname">add_cert</code><span class="sig-paren">(</span>DataSource &<em>source</em><span class="sig-paren">)</span><a class="headerlink" href="#_CPPv2N10X509_Store8add_certER10DataSource" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="function">
<dt id="_CPPv2N10X509_Store17add_trusted_certsER10DataSource">
<span id="X509_Store::add_trusted_certs__DataSourceR"></span>void <code class="descclassname">X509_Store::</code><code class="descname">add_trusted_certs</code><span class="sig-paren">(</span>DataSource &<em>source</em><span class="sig-paren">)</span><a class="headerlink" href="#_CPPv2N10X509_Store17add_trusted_certsER10DataSource" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p>The versions that take a <code class="docutils literal"><span class="pre">DataSource&</span></code> will add all the certificates
that it can find in that source.</p>
<p>All of them add the cert(s) to the store. The “trusted” certificates are the
ones that you are willing to trust for certification purposes. For example, say
your application is working with certificates that are owned by employees of
some company, and all of their certificates are signed by the company CA, whose
certificate is in turned signed by a commercial root CA. What you would then do
is include the certificate of the commercial CA with your application, and read
it in as a trusted certificate. From there, you could verify the company CA’s
certificate, and then use that to verify the end user’s certificates. Only
self-signed certificates may be considered trusted.</p>
</div>
<div class="section" id="adding-crls">
<h3>Adding CRLs<a class="headerlink" href="#adding-crls" title="Permalink to this headline">¶</a></h3>
<dl class="function">
<dt id="_CPPv2N10X509_Store7add_crlERK8X509_CRL">
X509_Code <code class="descclassname">X509_Store::</code><code class="descname">add_crl</code><span class="sig-paren">(</span><em class="property">const</em> X509_CRL &<em>crl</em><span class="sig-paren">)</span><a class="headerlink" href="#_CPPv2N10X509_Store7add_crlERK8X509_CRL" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p>This will process the CRL and mark the revoked certificates. This will
also work if a revoked certificate is added to the store sometime
after the CRL is processed. The function can return an error code
(listed later), or will return <code class="docutils literal"><span class="pre">VERIFIED</span></code> if everything completed
successfully.</p>
</div>
<div class="section" id="storing-certificates">
<h3>Storing Certificates<a class="headerlink" href="#storing-certificates" title="Permalink to this headline">¶</a></h3>
<p>You can output a set of certificates by calling <code class="docutils literal"><span class="pre">PEM_encode</span></code>, which
will return a <code class="docutils literal"><span class="pre">std::string</span></code> containing each of the certificates in
the store, PEM encoded and concatenated. This simple format can easily
be read by both Botan and other libraries/applications.</p>
</div>
<div class="section" id="certificate-stores">
<h3>Certificate Stores<a class="headerlink" href="#certificate-stores" title="Permalink to this headline">¶</a></h3>
<p>An object of type <code class="docutils literal"><span class="pre">Certificate_Store</span></code> 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 <code class="docutils literal"><span class="pre">std::vector</span></code> of
<code class="docutils literal"><span class="pre">X509_Certificate</span></code>. This storage mechanism is <em>only</em> 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.</p>
<p>The three certificate lookup methods are <code class="docutils literal"><span class="pre">by_SKID</span></code> (Subject Key Identifier),
<code class="docutils literal"><span class="pre">by_name</span></code> (the CommonName DN entry), and <code class="docutils literal"><span class="pre">by_email</span></code> (stored in either the
distinguished name, or in a subjectAlternativeName extension). The name and
email versions take a <code class="docutils literal"><span class="pre">std::string</span></code>, while the SKID version takes a
<code class="docutils literal"><span class="pre">SecureVector<byte></span></code> containing the subject key identifier in raw binary. You
can choose not to implement <code class="docutils literal"><span class="pre">by_name</span></code> or <code class="docutils literal"><span class="pre">by_email</span></code>, but <code class="docutils literal"><span class="pre">by_SKID</span></code> is
mandatory to implement, and, currently, is the only version that is used by
<code class="docutils literal"><span class="pre">X509_Store</span></code>.</p>
<p>Finally, there is a method for finding CRLs, called <code class="docutils literal"><span class="pre">get_crls_for</span></code>, that
takes an <code class="docutils literal"><span class="pre">X509_Certificate</span></code> object, and returns a <code class="docutils literal"><span class="pre">std::vector</span></code> of
<code class="docutils literal"><span class="pre">X509_CRL</span></code>. 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 <code class="docutils literal"><span class="pre">X509_CRL</span></code>.</p>
<p>As for using such a store, you have to tell <code class="docutils literal"><span class="pre">X509_Store</span></code> about it
with</p>
<dl class="function">
<dt id="_CPPv2N10X509_Store17add_new_certstoreEP17Certificate_Store">
<span id="X509_Store::add_new_certstore__Certificate_StoreP"></span>void <code class="descclassname">X509_Store::</code><code class="descname">add_new_certstore</code><span class="sig-paren">(</span>Certificate_Store *<em>new_store</em><span class="sig-paren">)</span><a class="headerlink" href="#_CPPv2N10X509_Store17add_new_certstoreEP17Certificate_Store" title="Permalink to this definition">¶</a></dt>
<dd><p>The store object will be owned by (and deleted by) <code class="docutils literal"><span class="pre">X509_Store</span></code>,
so make sure to allocate it with <code class="docutils literal"><span class="pre">new</span></code>.</p>
</dd></dl>
</div>
<div class="section" id="verifying-certificates">
<h3>Verifying Certificates<a class="headerlink" href="#verifying-certificates" title="Permalink to this headline">¶</a></h3>
<p>Verifying a certificate requires that we build up a chain of trust, starting
from the root (usually a commercial CA), down through some number of
intermediate CAs, and finally reaching the actual certificate in
question. Thus, to verify, we actually have to have all those certificates on
hand (or at the very least, know where we can get the ones we need).</p>
<p>The class which handles both storing certificates, and verifying them,
is</p>
<dl class="class">
<dt id="_CPPv210X509_Store">
<span id="X509_Store"></span><em class="property">class </em><code class="descclassname"></code><code class="descname">X509_Store</code><a class="headerlink" href="#_CPPv210X509_Store" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="type">
<dt id="_CPPv210Cert_Usage">
<span id="Cert_Usage"></span><em class="property">type </em><code class="descclassname"></code><code class="descname">Cert_Usage</code><a class="headerlink" href="#_CPPv210Cert_Usage" title="Permalink to this definition">¶</a></dt>
<dd><dl class="docutils">
<dt>Can be any of:</dt>
<dd><ul class="first last simple">
<li><code class="docutils literal"><span class="pre">ANY</span></code> (any usage is OK)</li>
<li><code class="docutils literal"><span class="pre">CRL_SIGNING</span></code></li>
<li><code class="docutils literal"><span class="pre">TLS_SERVER</span></code> (for SSL/TLS server authentication)</li>
<li><code class="docutils literal"><span class="pre">TLS_CLIENT</span></code> (for SSL/TLS client authentication)</li>
<li><code class="docutils literal"><span class="pre">CODE_SIGNING</span></code></li>
<li><code class="docutils literal"><span class="pre">EMAIL_PROTECTION</span></code> (usually this means S/MIME)</li>
<li><code class="docutils literal"><span class="pre">TIME_STAMPING</span></code> (in theory any time stamp application,
usually IETF PKIX’s Time Stamp Protocol)</li>
</ul>
</dd>
</dl>
</dd></dl>
<dl class="function">
<dt id="_CPPv213validate_certRK16X509_Certificate10Cert_Usage">
<span id="validate_cert__X509_CertificateCR.Cert_Usage"></span>X509_Code <code class="descclassname"></code><code class="descname">validate_cert</code><span class="sig-paren">(</span><em class="property">const</em> X509_Certificate &<em>cert</em>, <a class="reference internal" href="#_CPPv210Cert_Usage" title="Cert_Usage">Cert_Usage</a> <em>usage</em> = ANY<span class="sig-paren">)</span><a class="headerlink" href="#_CPPv213validate_certRK16X509_Certificate10Cert_Usage" title="Permalink to this definition">¶</a></dt>
<dd><p>Return <code class="docutils literal"><span class="pre">VERIFIED</span></code> if the certificate can safely be considered
valid for the usage(s) described by <em>usage</em>, and an error code if
it is not.</p>
</dd></dl>
<p>First, how does :cpp:class`X509_Store::validate_cert` know if a certificate is
valid? A certificate is valid if both of the following hold: a) the signature
in the certificate can be verified using the public key in the issuer’s
certificate, and b) the issuer’s certificate is a valid CA certificate. Note
that this definition is recursive. We get out of this by “bottoming out” when
we reach a certificate that we consider trusted. In general this will either be
a commercial root CA, or an organization or application specific CA.</p>
<p>There are a few other restrictions (validity periods, key usage restrictions,
etc), but the above summarizes the major points of the validation algorithm. In
theory, Botan implements the certificate path validation algorithm given in RFC
2459, but in practice it does not (yet), because we don’t support the X.509v3
policy or name constraint extensions.</p>
<p>The default <code class="docutils literal"><span class="pre">ANY</span></code> does not mean valid for any use, it means “is valid for
some usage”. This is usually what you want; requiring that a random certificate
support a particular usage will likely result in a lot of failures, unless your
application is very careful to always issue certificates with the proper
extensions, and you never use certificates generated by other apps.</p>
<p>Return values for <code class="docutils literal"><span class="pre">validate_cert</span></code> (and <code class="docutils literal"><span class="pre">add_crl</span></code>) include:</p>
<ul class="simple">
<li>VERIFIED: The certificate is valid for the specified use.</li>
<li>INVALID_USAGE: The certificate cannot be used for the specified use.</li>
<li>CANNOT_ESTABLISH_TRUST: The root certificate was not marked as trusted.</li>
<li>CERT_CHAIN_TOO_LONG: The certificate chain exceeded the length
allowed by a basicConstraints extension.</li>
<li>SIGNATURE_ERROR: An invalid signature was found</li>
<li>POLICY_ERROR: Some problem with the certificate policies was found.</li>
<li>CERT_FORMAT_ERROR: Some format problem was found in a certificate.</li>
<li>CERT_ISSUER_NOT_FOUND: The issuer of a certificate could not be found.</li>
<li>CERT_NOT_YET_VALID: The certificate is not yet valid.</li>
<li>CERT_HAS_EXPIRED: The certificate has expired.</li>
<li>CERT_IS_REVOKED: The certificate has been revoked.</li>
<li>CRL_FORMAT_ERROR: Some format problem was found in a CRL.</li>
<li>CRL_ISSUER_NOT_FOUND: The issuer of a CRL could not be found.</li>
<li>CRL_NOT_YET_VALID: The CRL is not yet valid.</li>
<li>CRL_HAS_EXPIRED: The CRL has expired.</li>
<li>CA_CERT_CANNOT_SIGN: The CA certificate found does not have an
contain a public key that allows signature verification.</li>
<li>CA_CERT_NOT_FOR_CERT_ISSUER: The CA cert found is not allowed to
issue certificates.</li>
<li>CA_CERT_NOT_FOR_CRL_ISSUER: The CA cert found is not allowed to
issue CRLs.</li>
<li>UNKNOWN_X509_ERROR: Some other error occurred.</li>
</ul>
</div>
</div>
<div class="section" id="certificate-authorities">
<h2>Certificate Authorities<a class="headerlink" href="#certificate-authorities" title="Permalink to this headline">¶</a></h2>
<p>Setting up a CA for X.509 certificates is perhaps the easiest thing to
do related to X.509. A CA is represented by the type <code class="docutils literal"><span class="pre">X509_CA</span></code>,
which can be found in <code class="docutils literal"><span class="pre">x509_ca.h</span></code>. 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:</p>
<dl class="function">
<dt id="_CPPv2N7X509_CA7X509_CAERK16X509_CertificateRK11Private_Key">
<span id="X509_CA::X509_CA__X509_CertificateCR.Private_KeyCR"></span><code class="descclassname">X509_CA::</code><code class="descname">X509_CA</code><span class="sig-paren">(</span><em class="property">const</em> X509_Certificate &<em>cert</em>, <em class="property">const</em> Private_Key &<em>key</em><span class="sig-paren">)</span><a class="headerlink" href="#_CPPv2N7X509_CA7X509_CAERK16X509_CertificateRK11Private_Key" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p>The private key is the private key corresponding to the public key in the
CA’s certificate.</p>
<p>Requests for new certificates are supplied to a CA in the form on PKCS
#10 certificate requests (called a <code class="docutils literal"><span class="pre">PKCS10_Request</span></code> 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:</p>
<dl class="function">
<dt id="_CPPv2NK7X509_CA12sign_requestERK14PKCS10_Request">
<span id="X509_CA::sign_request__PKCS10_RequestCRC"></span>X509_Certificate <code class="descclassname">X509_CA::</code><code class="descname">sign_request</code><span class="sig-paren">(</span><em class="property">const</em> PKCS10_Request &<em>req</em><span class="sig-paren">)</span> <em class="property">const</em><a class="headerlink" href="#_CPPv2NK7X509_CA12sign_requestERK14PKCS10_Request" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p>Here’s an example:</p>
<div class="section" id="generating-crls">
<h3>Generating CRLs<a class="headerlink" href="#generating-crls" title="Permalink to this headline">¶</a></h3>
<p>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.</p>
<p>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</p>
<dl class="function">
<dt id="_CPPv2N7X509_CA7new_crlE6u32bit">
<span id="X509_CA::new_crl__u32bit"></span>X509_CRL <code class="descclassname">X509_CA::</code><code class="descname">new_crl</code><span class="sig-paren">(</span>u32bit <em>seconds_to_expiration</em> = 0<span class="sig-paren">)</span><a class="headerlink" href="#_CPPv2N7X509_CA7new_crlE6u32bit" title="Permalink to this definition">¶</a></dt>
<dd><p>This function will return a new, empty CRL. The
<code class="docutils literal"><span class="pre">seconds_to_expiration</span></code> 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.</p>
</dd></dl>
<p>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</p>
<dl class="function">
<dt id="_CPPv2N7X509_CA10update_crlERK8X509_CRLNSt6vectorI9CRL_EntryEE6size_t">
<span id="X509_CA::update_crl__X509_CRLCR.std::vector:CRL_Entry:.s"></span>X509_CRL <code class="descclassname">X509_CA::</code><code class="descname">update_crl</code><span class="sig-paren">(</span><em class="property">const</em> X509_CRL &<em>old_crl</em>, std::vector<CRL_Entry> <em>new_revoked</em>, size_t <em>seconds_to_expiration</em> = 0<span class="sig-paren">)</span><a class="headerlink" href="#_CPPv2N7X509_CA10update_crlERK8X509_CRLNSt6vectorI9CRL_EntryEE6size_t" title="Permalink to this definition">¶</a></dt>
<dd><p>Where <code class="docutils literal"><span class="pre">X509_CRL</span></code> is the last CRL this CA issued, and
<code class="docutils literal"><span class="pre">new_revoked</span></code> is a list of any newly revoked certificates. The
function returns a new <code class="docutils literal"><span class="pre">X509_CRL</span></code> to make available for
clients.</p>
</dd></dl>
<p>The <code class="docutils literal"><span class="pre">CRL_Entry</span></code> 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
<code class="docutils literal"><span class="pre">SecureVector<byte></span></code> called <code class="docutils literal"><span class="pre">serial</span></code>. There are two additional (optional)
values, an enumeration called <code class="docutils literal"><span class="pre">CRL_Code</span></code> that specifies the reason for
revocation (<code class="docutils literal"><span class="pre">reason</span></code>), and an object that represents the time that the
certificate became invalid (if this information is known).</p>
<p>If you wish to remove an old entry from the CRL, insert a new entry for the
same cert, with a <code class="docutils literal"><span class="pre">reason</span></code> code of <code class="docutils literal"><span class="pre">DELETE_CRL_ENTRY</span></code>. 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.</p>
</div>
<div class="section" id="self-signed-certificates">
<h3>Self-Signed Certificates<a class="headerlink" href="#self-signed-certificates" title="Permalink to this headline">¶</a></h3>
<p>Generating a new self-signed certificate can often be useful, for example when
setting up a new root CA, or for use in email applications. The library
provides a utility function for this:</p>
<dl class="function">
<dt id="_CPPv223create_self_signed_certRK17X509_Cert_OptionsRK11Private_Key">
<span id="create_self_signed_cert__X509_Cert_OptionsCR.Private_KeyCR"></span>X509_Certificate <code class="descclassname"></code><code class="descname">create_self_signed_cert</code><span class="sig-paren">(</span><em class="property">const</em> X509_Cert_Options &<em>opts</em>, <em class="property">const</em> Private_Key &<em>key</em><span class="sig-paren">)</span><a class="headerlink" href="#_CPPv223create_self_signed_certRK17X509_Cert_OptionsRK11Private_Key" title="Permalink to this definition">¶</a></dt>
<dd><p>Where <em>key</em> is the private key you wish to use (the public key,
used in the certificate itself, is extracted from the private key),
and <em>opts</em> 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).</p>
</dd></dl>
<p>An example:</p>
<div class="highlight-cpp"><div class="highlight"><pre><span></span><span class="cp">#include</span> <span class="cpf"><botan/botan.h></span><span class="cp"></span>
<span class="cp">#include</span> <span class="cpf"><botan/x509self.h></span><span class="cp"></span>
<span class="cp">#include</span> <span class="cpf"><botan/rsa.h></span><span class="cp"></span>
<span class="cp">#include</span> <span class="cpf"><botan/dsa.h></span><span class="cp"></span>
<span class="k">using</span> <span class="k">namespace</span> <span class="n">Botan</span><span class="p">;</span>
<span class="cp">#include</span> <span class="cpf"><iostream></span><span class="cp"></span>
<span class="cp">#include</span> <span class="cpf"><fstream></span><span class="cp"></span>
<span class="cp">#include</span> <span class="cpf"><memory></span><span class="cp"></span>
<span class="kt">int</span> <span class="nf">main</span><span class="p">(</span><span class="kt">int</span> <span class="n">argc</span><span class="p">,</span> <span class="kt">char</span><span class="o">*</span> <span class="n">argv</span><span class="p">[])</span>
<span class="p">{</span>
<span class="k">if</span><span class="p">(</span><span class="n">argc</span> <span class="o">!=</span> <span class="mi">7</span><span class="p">)</span>
<span class="p">{</span>
<span class="n">std</span><span class="o">::</span><span class="n">cout</span> <span class="o"><<</span> <span class="s">"Usage: "</span> <span class="o"><<</span> <span class="n">argv</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span>
<span class="o"><<</span> <span class="s">" passphrase [CA|user] name country_code organization email"</span>
<span class="o"><<</span> <span class="n">std</span><span class="o">::</span><span class="n">endl</span><span class="p">;</span>
<span class="k">return</span> <span class="mi">1</span><span class="p">;</span>
<span class="p">}</span>
<span class="n">Botan</span><span class="o">::</span><span class="n">LibraryInitializer</span> <span class="n">init</span><span class="p">;</span>
<span class="n">std</span><span class="o">::</span><span class="n">string</span> <span class="n">CA_flag</span> <span class="o">=</span> <span class="n">argv</span><span class="p">[</span><span class="mi">2</span><span class="p">];</span>
<span class="kt">bool</span> <span class="n">do_CA</span> <span class="o">=</span> <span class="nb">false</span><span class="p">;</span>
<span class="k">if</span><span class="p">(</span><span class="n">CA_flag</span> <span class="o">==</span> <span class="s">"CA"</span><span class="p">)</span> <span class="n">do_CA</span> <span class="o">=</span> <span class="nb">true</span><span class="p">;</span>
<span class="k">else</span> <span class="k">if</span><span class="p">(</span><span class="n">CA_flag</span> <span class="o">==</span> <span class="s">"user"</span><span class="p">)</span> <span class="n">do_CA</span> <span class="o">=</span> <span class="nb">false</span><span class="p">;</span>
<span class="k">else</span>
<span class="p">{</span>
<span class="n">std</span><span class="o">::</span><span class="n">cout</span> <span class="o"><<</span> <span class="s">"Bad flag for CA/user switch: "</span> <span class="o"><<</span> <span class="n">CA_flag</span> <span class="o"><<</span> <span class="n">std</span><span class="o">::</span><span class="n">endl</span><span class="p">;</span>
<span class="k">return</span> <span class="mi">1</span><span class="p">;</span>
<span class="p">}</span>
<span class="k">try</span>
<span class="p">{</span>
<span class="n">AutoSeeded_RNG</span> <span class="n">rng</span><span class="p">;</span>
<span class="n">RSA_PrivateKey</span> <span class="n">key</span><span class="p">(</span><span class="n">rng</span><span class="p">,</span> <span class="mi">2048</span><span class="p">);</span>
<span class="n">std</span><span class="o">::</span><span class="n">ofstream</span> <span class="n">priv_key</span><span class="p">(</span><span class="s">"private.pem"</span><span class="p">);</span>
<span class="n">priv_key</span> <span class="o"><<</span> <span class="n">PKCS8</span><span class="o">::</span><span class="n">PEM_encode</span><span class="p">(</span><span class="n">key</span><span class="p">,</span> <span class="n">rng</span><span class="p">,</span> <span class="n">argv</span><span class="p">[</span><span class="mi">1</span><span class="p">]);</span>
<span class="n">X509_Cert_Options</span> <span class="n">opts</span><span class="p">;</span>
<span class="n">opts</span><span class="p">.</span><span class="n">common_name</span> <span class="o">=</span> <span class="n">argv</span><span class="p">[</span><span class="mi">3</span><span class="p">];</span>
<span class="n">opts</span><span class="p">.</span><span class="n">country</span> <span class="o">=</span> <span class="n">argv</span><span class="p">[</span><span class="mi">4</span><span class="p">];</span>
<span class="n">opts</span><span class="p">.</span><span class="n">organization</span> <span class="o">=</span> <span class="n">argv</span><span class="p">[</span><span class="mi">5</span><span class="p">];</span>
<span class="n">opts</span><span class="p">.</span><span class="n">email</span> <span class="o">=</span> <span class="n">argv</span><span class="p">[</span><span class="mi">6</span><span class="p">];</span>
<span class="cm">/* Fill in other values of opts here */</span>
<span class="c1">//opts.xmpp = "lloyd@randombit.net";</span>
<span class="k">if</span><span class="p">(</span><span class="n">do_CA</span><span class="p">)</span>
<span class="n">opts</span><span class="p">.</span><span class="n">CA_key</span><span class="p">();</span>
<span class="n">X509_Certificate</span> <span class="n">cert</span> <span class="o">=</span>
<span class="n">X509</span><span class="o">::</span><span class="n">create_self_signed_cert</span><span class="p">(</span><span class="n">opts</span><span class="p">,</span> <span class="n">key</span><span class="p">,</span> <span class="s">"SHA-256"</span><span class="p">,</span> <span class="n">rng</span><span class="p">);</span>
<span class="n">std</span><span class="o">::</span><span class="n">ofstream</span> <span class="n">cert_file</span><span class="p">(</span><span class="s">"cert.pem"</span><span class="p">);</span>
<span class="n">cert_file</span> <span class="o"><<</span> <span class="n">cert</span><span class="p">.</span><span class="n">PEM_encode</span><span class="p">();</span>
<span class="p">}</span>
<span class="k">catch</span><span class="p">(</span><span class="n">std</span><span class="o">::</span><span class="n">exception</span><span class="o">&</span> <span class="n">e</span><span class="p">)</span>
<span class="p">{</span>
<span class="n">std</span><span class="o">::</span><span class="n">cout</span> <span class="o"><<</span> <span class="s">"Exception: "</span> <span class="o"><<</span> <span class="n">e</span><span class="p">.</span><span class="n">what</span><span class="p">()</span> <span class="o"><<</span> <span class="n">std</span><span class="o">::</span><span class="n">endl</span><span class="p">;</span>
<span class="k">return</span> <span class="mi">1</span><span class="p">;</span>
<span class="p">}</span>
<span class="k">return</span> <span class="mi">0</span><span class="p">;</span>
<span class="p">}</span>
</pre></div>
</div>
</div>
<div class="section" id="creating-pkcs-10-requests">
<h3>Creating PKCS #10 Requests<a class="headerlink" href="#creating-pkcs-10-requests" title="Permalink to this headline">¶</a></h3>
<p>Also in <code class="docutils literal"><span class="pre">x509self.h</span></code>, there is a function for generating new PKCS #10
certificate requests:</p>
<dl class="function">
<dt id="_CPPv215create_cert_reqRK17X509_Cert_OptionsRK11Private_Key">
<span id="create_cert_req__X509_Cert_OptionsCR.Private_KeyCR"></span>PKCS10_Request <code class="descclassname"></code><code class="descname">create_cert_req</code><span class="sig-paren">(</span><em class="property">const</em> X509_Cert_Options &<em>opts</em>, <em class="property">const</em> Private_Key &<em>key</em><span class="sig-paren">)</span><a class="headerlink" href="#_CPPv215create_cert_reqRK17X509_Cert_OptionsRK11Private_Key" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p>This function acts quite similarly to
<a class="reference internal" href="#_CPPv223create_self_signed_certRK17X509_Cert_OptionsRK11Private_Key" title="create_self_signed_cert"><code class="xref cpp cpp-func docutils literal"><span class="pre">create_self_signed_cert</span></code></a>, 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.</p>
<p>An example:</p>
<div class="highlight-cpp"><div class="highlight"><pre><span></span><span class="cp">#include</span> <span class="cpf"><botan/init.h></span><span class="cp"></span>
<span class="cp">#include</span> <span class="cpf"><botan/auto_rng.h></span><span class="cp"></span>
<span class="cp">#include</span> <span class="cpf"><botan/x509self.h></span><span class="cp"></span>
<span class="cp">#include</span> <span class="cpf"><botan/rsa.h></span><span class="cp"></span>
<span class="cp">#include</span> <span class="cpf"><botan/dsa.h></span><span class="cp"></span>
<span class="k">using</span> <span class="k">namespace</span> <span class="n">Botan</span><span class="p">;</span>
<span class="cp">#include</span> <span class="cpf"><iostream></span><span class="cp"></span>
<span class="cp">#include</span> <span class="cpf"><fstream></span><span class="cp"></span>
<span class="cp">#include</span> <span class="cpf"><memory></span><span class="cp"></span>
<span class="kt">int</span> <span class="nf">main</span><span class="p">(</span><span class="kt">int</span> <span class="n">argc</span><span class="p">,</span> <span class="kt">char</span><span class="o">*</span> <span class="n">argv</span><span class="p">[])</span>
<span class="p">{</span>
<span class="k">if</span><span class="p">(</span><span class="n">argc</span> <span class="o">!=</span> <span class="mi">6</span><span class="p">)</span>
<span class="p">{</span>
<span class="n">std</span><span class="o">::</span><span class="n">cout</span> <span class="o"><<</span> <span class="s">"Usage: "</span> <span class="o"><<</span> <span class="n">argv</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span> <span class="o"><<</span>
<span class="s">" passphrase name country_code organization email"</span> <span class="o"><<</span> <span class="n">std</span><span class="o">::</span><span class="n">endl</span><span class="p">;</span>
<span class="k">return</span> <span class="mi">1</span><span class="p">;</span>
<span class="p">}</span>
<span class="n">Botan</span><span class="o">::</span><span class="n">LibraryInitializer</span> <span class="n">init</span><span class="p">;</span>
<span class="k">try</span>
<span class="p">{</span>
<span class="n">AutoSeeded_RNG</span> <span class="n">rng</span><span class="p">;</span>
<span class="n">RSA_PrivateKey</span> <span class="n">priv_key</span><span class="p">(</span><span class="n">rng</span><span class="p">,</span> <span class="mi">1024</span><span class="p">);</span>
<span class="n">std</span><span class="o">::</span><span class="n">ofstream</span> <span class="n">key_file</span><span class="p">(</span><span class="s">"private.pem"</span><span class="p">);</span>
<span class="n">key_file</span> <span class="o"><<</span> <span class="n">PKCS8</span><span class="o">::</span><span class="n">PEM_encode</span><span class="p">(</span><span class="n">priv_key</span><span class="p">,</span> <span class="n">rng</span><span class="p">,</span> <span class="n">argv</span><span class="p">[</span><span class="mi">1</span><span class="p">]);</span>
<span class="n">X509_Cert_Options</span> <span class="n">opts</span><span class="p">;</span>
<span class="n">opts</span><span class="p">.</span><span class="n">common_name</span> <span class="o">=</span> <span class="n">argv</span><span class="p">[</span><span class="mi">2</span><span class="p">];</span>
<span class="n">opts</span><span class="p">.</span><span class="n">country</span> <span class="o">=</span> <span class="n">argv</span><span class="p">[</span><span class="mi">3</span><span class="p">];</span>
<span class="n">opts</span><span class="p">.</span><span class="n">organization</span> <span class="o">=</span> <span class="n">argv</span><span class="p">[</span><span class="mi">4</span><span class="p">];</span>
<span class="n">opts</span><span class="p">.</span><span class="n">email</span> <span class="o">=</span> <span class="n">argv</span><span class="p">[</span><span class="mi">5</span><span class="p">];</span>
<span class="n">PKCS10_Request</span> <span class="n">req</span> <span class="o">=</span> <span class="n">X509</span><span class="o">::</span><span class="n">create_cert_req</span><span class="p">(</span><span class="n">opts</span><span class="p">,</span> <span class="n">priv_key</span><span class="p">,</span>
<span class="s">"SHA-256"</span><span class="p">,</span> <span class="n">rng</span><span class="p">);</span>
<span class="n">std</span><span class="o">::</span><span class="n">ofstream</span> <span class="n">req_file</span><span class="p">(</span><span class="s">"req.pem"</span><span class="p">);</span>
<span class="n">req_file</span> <span class="o"><<</span> <span class="n">req</span><span class="p">.</span><span class="n">PEM_encode</span><span class="p">();</span>
<span class="p">}</span>
<span class="k">catch</span><span class="p">(</span><span class="n">std</span><span class="o">::</span><span class="n">exception</span><span class="o">&</span> <span class="n">e</span><span class="p">)</span>
<span class="p">{</span>
<span class="n">std</span><span class="o">::</span><span class="n">cout</span> <span class="o"><<</span> <span class="n">e</span><span class="p">.</span><span class="n">what</span><span class="p">()</span> <span class="o"><<</span> <span class="n">std</span><span class="o">::</span><span class="n">endl</span><span class="p">;</span>
<span class="k">return</span> <span class="mi">1</span><span class="p">;</span>
<span class="p">}</span>
<span class="k">return</span> <span class="mi">0</span><span class="p">;</span>
<span class="p">}</span>
</pre></div>
</div>
</div>
<div class="section" id="certificate-options">
<h3>Certificate Options<a class="headerlink" href="#certificate-options" title="Permalink to this headline">¶</a></h3>
<p>What is this <code class="docutils literal"><span class="pre">X509_Cert_Options</span></code> 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.</p>
<p>First and foremost is a number of <code class="docutils literal"><span class="pre">std::string</span></code> members, which contains
various bits of information about the user: <code class="docutils literal"><span class="pre">common_name</span></code>, <code class="docutils literal"><span class="pre">serial_number</span></code>,
<code class="docutils literal"><span class="pre">country</span></code>, <code class="docutils literal"><span class="pre">organization</span></code>, <code class="docutils literal"><span class="pre">org_unit</span></code>, <code class="docutils literal"><span class="pre">locality</span></code>, <code class="docutils literal"><span class="pre">state</span></code>,
<code class="docutils literal"><span class="pre">email</span></code>, <code class="docutils literal"><span class="pre">dns_name</span></code>, and <code class="docutils literal"><span class="pre">uri</span></code>. As many of these as possible should be
filled it (especially an email address), though the only required ones are
<code class="docutils literal"><span class="pre">common_name</span></code> and <code class="docutils literal"><span class="pre">country</span></code>.</p>
<p>There is another value that is only useful when creating a PKCS #10 request,
which is called <code class="docutils literal"><span class="pre">challenge</span></code>. This is a challenge password, which you can
later use to request certificate revocation (<em>if</em> the CA supports doing
revocations in this manner).</p>
<p>Then there is the validity period; these are set with <code class="docutils literal"><span class="pre">not_before</span></code> and
<code class="docutils literal"><span class="pre">not_after</span></code>. Both of these functions also take a <code class="docutils literal"><span class="pre">std::string</span></code>, 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”.</p>
<p>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 <code class="docutils literal"><span class="pre">CA_key</span></code>. This should only be used when needed.</p>
<p>Other constraints can be set by calling the member functions
<code class="docutils literal"><span class="pre">add_constraints</span></code> and <code class="docutils literal"><span class="pre">add_ex_constraints</span></code>. The first takes a
<code class="docutils literal"><span class="pre">Key_Constraints</span></code> 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):
<code class="docutils literal"><span class="pre">DIGITAL_SIGNATURE</span></code>, <code class="docutils literal"><span class="pre">NON_REPUDIATION</span></code>, <code class="docutils literal"><span class="pre">KEY_ENCIPHERMENT</span></code>,
<code class="docutils literal"><span class="pre">DATA_ENCIPHERMENT</span></code>, <code class="docutils literal"><span class="pre">KEY_AGREEMENT</span></code>, <code class="docutils literal"><span class="pre">KEY_CERT_SIGN</span></code>, <code class="docutils literal"><span class="pre">CRL_SIGN</span></code>,
<code class="docutils literal"><span class="pre">ENCIPHER_ONLY</span></code>, <code class="docutils literal"><span class="pre">DECIPHER_ONLY</span></code>. Many of these have quite special
semantics, so you should either consult the appropriate standards document
(such as RFC 3280), or just not call <code class="docutils literal"><span class="pre">add_constraints</span></code>, in which case the
appropriate values will be chosen for you.</p>
<p>The second function, <code class="docutils literal"><span class="pre">add_ex_constraints</span></code>, 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.</p>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sidebar">
<h3>Table Of Contents</h3>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="index.html">Welcome</a></li>
<li class="toctree-l1"><a class="reference internal" href="reading.html">Recommended Reading</a></li>
<li class="toctree-l1"><a class="reference internal" href="building.html">Building The Library</a></li>
<li class="toctree-l1"><a class="reference internal" href="firststep.html">Getting Started</a></li>
<li class="toctree-l1"><a class="reference internal" href="filters.html">Information Flow: Pipes and Filters</a></li>
<li class="toctree-l1"><a class="reference internal" href="pubkey.html">Public Key Cryptography</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">Certificate Handling</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#so-what-s-in-an-x-509-certificate">So what’s in an X.509 certificate?</a></li>
<li class="toctree-l2"><a class="reference internal" href="#reading-certificates">Reading Certificates</a></li>
<li class="toctree-l2"><a class="reference internal" href="#storing-and-using-certificates">Storing and Using Certificates</a></li>
<li class="toctree-l2"><a class="reference internal" href="#certificate-authorities">Certificate Authorities</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="ssl.html">SSL and TLS</a></li>
<li class="toctree-l1"><a class="reference internal" href="bigint.html">BigInt</a></li>
<li class="toctree-l1"><a class="reference internal" href="lowlevel.html">The Low-Level Interface</a></li>
<li class="toctree-l1"><a class="reference internal" href="secmem.html">Secure Memory Containers</a></li>
<li class="toctree-l1"><a class="reference internal" href="kdf.html">Key Derivation Functions</a></li>
<li class="toctree-l1"><a class="reference internal" href="pbkdf.html">PBKDF Algorithms</a></li>
<li class="toctree-l1"><a class="reference internal" href="passhash.html">Password Hashing</a></li>
<li class="toctree-l1"><a class="reference internal" href="rng.html">Random Number Generators</a></li>
<li class="toctree-l1"><a class="reference internal" href="fpe.html">Format Preserving Encryption</a></li>
<li class="toctree-l1"><a class="reference internal" href="python.html">Python Binding</a></li>
</ul>
<div role="search">
<h3 style="margin-top: 1.5em;">Search</h3>
<form class="search" action="search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<div class="clearer"></div>
</div>
</div>
<div class="footer-wrapper">
<div class="footer">
<div class="left">
<div role="navigation" aria-label="related navigaton">
<a href="pubkey.html" title="Public Key Cryptography"
accesskey="P">previous</a> |
<a href="ssl.html" title="SSL and TLS"
accesskey="N">next</a> |
<a href="genindex.html" title="General Index"
accesskey="I">index</a>
</div>
<div role="note" aria-label="source link">
<br/>
<a href="_sources/x509.txt"
rel="nofollow">Show Source</a>
</div>
</div>
<div class="right">
<div class="footer" role="contentinfo">
© Copyright 2000-2011, Jack Lloyd.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.4.9.
</div>
</div>
<div class="clearer"></div>
</div>
</div>
</body>
</html>
