Rename all text files that are actually reStructuredText to .rst

1 files changed, 0 insertions, 403 deletions

diff --git a/doc/x509.txt b/doc/x509.txt
deleted file mode 100644
index e7d5c3cdf..000000000
--- a/doc/x509.txt
+++ /dev/null
@@ -1,403 +0,0 @@
-
-.. _x509_certificates:
-
-Certificate Handling
-=================================
-
-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 ([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.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.