Reorganize the x509 docs in prep for a tutorial

2 files changed, 1598 insertions, 0 deletions

diff --git a/docs/x509/index.rst b/docs/x509/index.rst
new file mode 100644
index 00000000..c3fa1ed2
--- /dev/null
+++ b/docs/x509/index.rst
@@ -0,0 +1,14 @@
+X.509
+=====
+
+X.509 is an ITU-T standard for a `public key infrastructure`_. X.509v3 is
+defined in :rfc:`5280` (which obsoletes :rfc:`2459` and :rfc:`3280`). X.509
+certificates are commonly used in protocols like `TLS`_.
+
+.. toctree::
+    :maxdepth: 2
+
+    reference
+
+.. _`public key infrastructure`: https://en.wikipedia.org/wiki/Public_key_infrastructure
+.. _`TLS`: https://en.wikipedia.org/wiki/Transport_Layer_Security
diff --git a/docs/x509/reference.rst b/docs/x509/reference.rst
new file mode 100644
index 00000000..36fa972a
--- /dev/null
+++ b/docs/x509/reference.rst
@@ -0,0 +1,1584 @@
+X.509 Reference
+===============
+
+.. currentmodule:: cryptography.x509
+
+.. testsetup::
+
+    pem_req_data = b"""
+    -----BEGIN CERTIFICATE REQUEST-----
+    MIIC0zCCAbsCAQAwWTELMAkGA1UEBhMCVVMxETAPBgNVBAgMCElsbGlub2lzMRAw
+    DgYDVQQHDAdDaGljYWdvMREwDwYDVQQKDAhyNTA5IExMQzESMBAGA1UEAwwJaGVs
+    bG8uY29tMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAqhZx+Mo9VRd9
+    vsnWWa6NBCws21rZ0+1B/JGgB4hDsZS7iDE4Bj5z4idheFRtl8bBbdjPknq7BfoF
+    8v15Zq/Zv7i2xMSDL+LUrTBZezRd4bRTGqCm6YJ5EYkhqdcqeZleHCFImguHoq1J
+    Fh0+kObQrTHXw3ZP57a3o1IvyIUA3nNoCBL0QQhwBXaDXOojMKNR+bqB5ve8GS1y
+    Elr0AM/+cJsfaIahNQUgFKx3Eu3GeEOMKYOAG1lycgdQdmTUybLrT3U7vkClTseM
+    xHg1r5En7ALjONIhqRuq3rddYahrP8HXozb3zUy3cJ7P6IeaosuvNzvMXOX9P6HD
+    Ha9urDAJ1wIDAQABoDUwMwYJKoZIhvcNAQkOMSYwJDAiBgNVHREEGzAZggl3b3Js
+    ZC5jb22CDHdoYXRldmVyLmNvbTANBgkqhkiG9w0BAQUFAAOCAQEAS4Ro6h+z52SK
+    YSLCYARpnEu/rmh4jdqndt8naqcNb6uLx9mlKZ2W9on9XDjnSdQD9q+ZP5aZfESw
+    R0+rJhW9ZrNa/g1pt6M24ihclHYDAxYMWxT1z/TXXGM3TmZZ6gfYlNE1kkBuODHa
+    UYsR/1Ht1E1EsmmUimt2n+zQR2K8T9Coa+boaUW/GsTEuz1aaJAkj5ZvTDiIhRG4
+    AOCqFZOLAQmCCNgJnnspD9hDz/Ons085LF5wnYjN4/Nsk5tS6AGs3xjZ3jPoOGGn
+    82WQ9m4dBGoVDZXsobVTaN592JEYwN5iu72zRn7Einb4V4H5y3yD2dD4yWPlt4pk
+    5wFkeYsZEA==
+    -----END CERTIFICATE REQUEST-----
+    """.strip()
+
+    pem_data = b"""
+    -----BEGIN CERTIFICATE-----
+    MIIDfDCCAmSgAwIBAgIBAjANBgkqhkiG9w0BAQsFADBFMQswCQYDVQQGEwJVUzEf
+    MB0GA1UEChMWVGVzdCBDZXJ0aWZpY2F0ZXMgMjAxMTEVMBMGA1UEAxMMVHJ1c3Qg
+    QW5jaG9yMB4XDTEwMDEwMTA4MzAwMFoXDTMwMTIzMTA4MzAwMFowQDELMAkGA1UE
+    BhMCVVMxHzAdBgNVBAoTFlRlc3QgQ2VydGlmaWNhdGVzIDIwMTExEDAOBgNVBAMT
+    B0dvb2QgQ0EwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCQWJpHYo37
+    Xfb7oJSPe+WvfTlzIG21WQ7MyMbGtK/m8mejCzR6c+f/pJhEH/OcDSMsXq8h5kXa
+    BGqWK+vSwD/Pzp5OYGptXmGPcthDtAwlrafkGOS4GqIJ8+k9XGKs+vQUXJKsOk47
+    RuzD6PZupq4s16xaLVqYbUC26UcY08GpnoLNHJZS/EmXw1ZZ3d4YZjNlpIpWFNHn
+    UGmdiGKXUPX/9H0fVjIAaQwjnGAbpgyCumWgzIwPpX+ElFOUr3z7BoVnFKhIXze+
+    VmQGSWxZxvWDUN90Ul0tLEpLgk3OVxUB4VUGuf15OJOpgo1xibINPmWt14Vda2N9
+    yrNKloJGZNqLAgMBAAGjfDB6MB8GA1UdIwQYMBaAFOR9X9FclYYILAWuvnW2ZafZ
+    XahmMB0GA1UdDgQWBBRYAYQkG7wrUpRKPaUQchRR9a86yTAOBgNVHQ8BAf8EBAMC
+    AQYwFwYDVR0gBBAwDjAMBgpghkgBZQMCATABMA8GA1UdEwEB/wQFMAMBAf8wDQYJ
+    KoZIhvcNAQELBQADggEBADWHlxbmdTXNwBL/llwhQqwnazK7CC2WsXBBqgNPWj7m
+    tvQ+aLG8/50Qc2Sun7o2VnwF9D18UUe8Gj3uPUYH+oSI1vDdyKcjmMbKRU4rk0eo
+    3UHNDXwqIVc9CQS9smyV+x1HCwL4TTrq+LXLKx/qVij0Yqk+UJfAtrg2jnYKXsCu
+    FMBQQnWCGrwa1g1TphRp/RmYHnMynYFmZrXtzFz+U9XEA7C+gPq4kqDI/iVfIT1s
+    6lBtdB50lrDVwl2oYfAvW/6sC2se2QleZidUmrziVNP4oEeXINokU6T6p//HM1FG
+    QYw2jOvpKcKtWCSAnegEbgsGYzATKjmPJPJ0npHFqzM=
+    -----END CERTIFICATE-----
+    """.strip()
+
+    cryptography_cert_pem = b"""
+    -----BEGIN CERTIFICATE-----
+    MIIFvTCCBKWgAwIBAgICPyAwDQYJKoZIhvcNAQELBQAwRzELMAkGA1UEBhMCVVMx
+    FjAUBgNVBAoTDUdlb1RydXN0IEluYy4xIDAeBgNVBAMTF1JhcGlkU1NMIFNIQTI1
+    NiBDQSAtIEczMB4XDTE0MTAxNTEyMDkzMloXDTE4MTExNjAxMTUwM1owgZcxEzAR
+    BgNVBAsTCkdUNDg3NDI5NjUxMTAvBgNVBAsTKFNlZSB3d3cucmFwaWRzc2wuY29t
+    L3Jlc291cmNlcy9jcHMgKGMpMTQxLzAtBgNVBAsTJkRvbWFpbiBDb250cm9sIFZh
+    bGlkYXRlZCAtIFJhcGlkU1NMKFIpMRwwGgYDVQQDExN3d3cuY3J5cHRvZ3JhcGh5
+    LmlvMIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEAom/FebKJIot7Sp3s
+    itG1sicpe3thCssjI+g1JDAS7I3GLVNmbms1DOdIIqwf01gZkzzXBN2+9sOnyRaR
+    PPfCe1jTr3dk2y6rPE559vPa1nZQkhlzlhMhlPyjaT+S7g4Tio4qV2sCBZU01DZJ
+    CaksfohN+5BNVWoJzTbOcrHOEJ+M8B484KlBCiSxqf9cyNQKru4W3bHaCVNVJ8eu
+    6i6KyhzLa0L7yK3LXwwXVs583C0/vwFhccGWsFODqD/9xHUzsBIshE8HKjdjDi7Y
+    3BFQzVUQFjBB50NSZfAA/jcdt1blxJouc7z9T8Oklh+V5DDBowgAsrT4b6Z2Fq6/
+    r7D1GqivLK/ypUQmxq2WXWAUBb/Q6xHgxASxI4Br+CByIUQJsm8L2jzc7k+mF4hW
+    ltAIUkbo8fGiVnat0505YJgxWEDKOLc4Gda6d/7GVd5AvKrz242bUqeaWo6e4MTx
+    diku2Ma3rhdcr044Qvfh9hGyjqNjvhWY/I+VRWgihU7JrYvgwFdJqsQ5eiKT4OHi
+    gsejvWwkZzDtiQ+aQTrzM1FsY2swJBJsLSX4ofohlVRlIJCn/ME+XErj553431Lu
+    YQ5SzMd3nXzN78Vj6qzTfMUUY72UoT1/AcFiUMobgIqrrmwuNxfrkbVE2b6Bga74
+    FsJX63prvrJ41kuHK/16RQBM7fcCAwEAAaOCAWAwggFcMB8GA1UdIwQYMBaAFMOc
+    8/zTRgg0u85Gf6B8W/PiCMtZMFcGCCsGAQUFBwEBBEswSTAfBggrBgEFBQcwAYYT
+    aHR0cDovL2d2LnN5bWNkLmNvbTAmBggrBgEFBQcwAoYaaHR0cDovL2d2LnN5bWNi
+    LmNvbS9ndi5jcnQwDgYDVR0PAQH/BAQDAgWgMB0GA1UdJQQWMBQGCCsGAQUFBwMB
+    BggrBgEFBQcDAjAvBgNVHREEKDAmghN3d3cuY3J5cHRvZ3JhcGh5Lmlvgg9jcnlw
+    dG9ncmFwaHkuaW8wKwYDVR0fBCQwIjAgoB6gHIYaaHR0cDovL2d2LnN5bWNiLmNv
+    bS9ndi5jcmwwDAYDVR0TAQH/BAIwADBFBgNVHSAEPjA8MDoGCmCGSAGG+EUBBzYw
+    LDAqBggrBgEFBQcCARYeaHR0cHM6Ly93d3cucmFwaWRzc2wuY29tL2xlZ2FsMA0G
+    CSqGSIb3DQEBCwUAA4IBAQAzIYO2jx7h17FBT74tJ2zbV9OKqGb7QF8y3wUtP4xc
+    dH80vprI/Cfji8s86kr77aAvAqjDjaVjHn7UzebhSUivvRPmfzRgyWBacomnXTSt
+    Xlt2dp2nDQuwGyK2vB7dMfKnQAkxwq1sYUXznB8i0IhhCAoXp01QGPKq51YoIlnF
+    7DRMk6iEaL1SJbkIrLsCQyZFDf0xtfW9DqXugMMLoxeCsBhZJQzNyS2ryirrv9LH
+    aK3+6IZjrcyy9bkpz/gzJucyhU+75c4My/mnRCrtItRbCQuiI5pd5poDowm+HH9i
+    GVI9+0lAFwxOUnOnwsoI40iOoxjLMGB+CgFLKCGUcWxP
+    -----END CERTIFICATE-----
+    """.strip()
+
+Loading Certificates
+~~~~~~~~~~~~~~~~~~~~
+
+.. function:: load_pem_x509_certificate(data, backend)
+
+    .. versionadded:: 0.7
+
+    Deserialize a certificate from PEM encoded data. PEM certificates are
+    base64 decoded and have delimiters that look like
+    ``-----BEGIN CERTIFICATE-----``.
+
+    :param bytes data: The PEM encoded certificate data.
+
+    :param backend: A backend supporting the
+        :class:`~cryptography.hazmat.backends.interfaces.X509Backend`
+        interface.
+
+    :returns: An instance of :class:`~cryptography.x509.Certificate`.
+
+.. function:: load_der_x509_certificate(data, backend)
+
+    .. versionadded:: 0.7
+
+    Deserialize a certificate from DER encoded data. DER is a binary format
+    and is commonly found in files with the ``.cer`` extension (although file
+    extensions are not a guarantee of encoding type).
+
+    :param bytes data: The DER encoded certificate data.
+
+    :param backend: A backend supporting the
+        :class:`~cryptography.hazmat.backends.interfaces.X509Backend`
+        interface.
+
+    :returns: An instance of :class:`~cryptography.x509.Certificate`.
+
+.. doctest::
+
+    >>> from cryptography import x509
+    >>> from cryptography.hazmat.backends import default_backend
+    >>> cert = x509.load_pem_x509_certificate(pem_data, default_backend())
+    >>> cert.serial
+    2
+
+Loading Certificate Signing Requests
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. function:: load_pem_x509_csr(data, backend)
+
+    .. versionadded:: 0.9
+
+    Deserialize a certificate signing request (CSR) from PEM encoded data. PEM
+    requests are base64 decoded and have delimiters that look like
+    ``-----BEGIN CERTIFICATE REQUEST-----``. This format is also known as
+    PKCS#10.
+
+    :param bytes data: The PEM encoded request data.
+
+    :param backend: A backend supporting the
+        :class:`~cryptography.hazmat.backends.interfaces.X509Backend`
+        interface.
+
+    :returns: An instance of
+        :class:`~cryptography.x509.CertificateSigningRequest`.
+
+.. function:: load_der_x509_csr(data, backend)
+
+    .. versionadded:: 0.9
+
+    Deserialize a certificate signing request (CSR) from DER encoded data. DER
+    is a binary format and is not commonly used with CSRs.
+
+    :param bytes data: The DER encoded request data.
+
+    :param backend: A backend supporting the
+        :class:`~cryptography.hazmat.backends.interfaces.X509Backend`
+        interface.
+
+    :returns: An instance of
+        :class:`~cryptography.x509.CertificateSigningRequest`.
+
+.. doctest::
+
+    >>> from cryptography import x509
+    >>> from cryptography.hazmat.backends import default_backend
+    >>> from cryptography.hazmat.primitives import hashes
+    >>> csr = x509.load_pem_x509_csr(pem_req_data, default_backend())
+    >>> isinstance(csr.signature_hash_algorithm, hashes.SHA1)
+    True
+
+X.509 Certificate Object
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. class:: Certificate
+
+    .. versionadded:: 0.7
+
+    .. attribute:: version
+
+        :type: :class:`~cryptography.x509.Version`
+
+        The certificate version as an enumeration. Version 3 certificates are
+        the latest version and also the only type you should see in practice.
+
+        :raises cryptography.x509.InvalidVersion: If the version in the
+            certificate is not a known
+            :class:`X.509 version <cryptography.x509.Version>`.
+
+        .. doctest::
+
+            >>> cert.version
+            <Version.v3: 2>
+
+    .. method:: fingerprint(algorithm)
+
+        :param algorithm: The
+            :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm`
+            that will be used to generate the fingerprint.
+
+        :return bytes: The fingerprint using the supplied hash algorithm, as
+            bytes.
+
+        .. doctest::
+
+            >>> from cryptography.hazmat.primitives import hashes
+            >>> cert.fingerprint(hashes.SHA256())
+            '\x86\xd2\x187Gc\xfc\xe7}[+E9\x8d\xb4\x8f\x10\xe5S\xda\x18u\xbe}a\x03\x08[\xac\xa04?'
+
+    .. attribute:: serial
+
+        :type: int
+
+        The serial as a Python integer.
+
+        .. doctest::
+
+            >>> cert.serial
+            2
+
+    .. method:: public_key()
+
+        :type:
+            :class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPublicKey` or
+            :class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPublicKey` or
+            :class:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePublicKey`
+
+        The public key associated with the certificate.
+
+        .. doctest::
+
+            >>> from cryptography.hazmat.primitives.asymmetric import rsa
+            >>> public_key = cert.public_key()
+            >>> isinstance(public_key, rsa.RSAPublicKey)
+            True
+
+    .. attribute:: not_valid_before
+
+        :type: :class:`datetime.datetime`
+
+        A naïve datetime representing the beginning of the validity period for
+        the certificate in UTC. This value is inclusive.
+
+        .. doctest::
+
+            >>> cert.not_valid_before
+            datetime.datetime(2010, 1, 1, 8, 30)
+
+    .. attribute:: not_valid_after
+
+        :type: :class:`datetime.datetime`
+
+        A naïve datetime representing the end of the validity period for the
+        certificate in UTC. This value is inclusive.
+
+        .. doctest::
+
+            >>> cert.not_valid_after
+            datetime.datetime(2030, 12, 31, 8, 30)
+
+    .. attribute:: issuer
+
+        .. versionadded:: 0.8
+
+        :type: :class:`Name`
+
+        The :class:`Name` of the issuer.
+
+    .. attribute:: subject
+
+        .. versionadded:: 0.8
+
+        :type: :class:`Name`
+
+        The :class:`Name` of the subject.
+
+    .. attribute:: signature_hash_algorithm
+
+        :type: :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm`
+
+        Returns the
+        :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm` which
+        was used in signing this certificate.
+
+        .. doctest::
+
+            >>> from cryptography.hazmat.primitives import hashes
+            >>> isinstance(cert.signature_hash_algorithm, hashes.SHA256)
+            True
+
+    .. attribute:: extensions
+
+        :type: :class:`Extensions`
+
+        The extensions encoded in the certificate.
+
+        :raises cryptography.x509.DuplicateExtension: If more than one
+            extension of the same type is found within the certificate.
+
+        :raises cryptography.x509.UnsupportedExtension: If the certificate
+            contains an extension that is not supported.
+
+        :raises cryptography.x509.UnsupportedGeneralNameType: If an extension
+            contains a general name that is not supported.
+
+        :raises UnicodeError: If an extension contains IDNA encoding that is
+            invalid or not compliant with IDNA 2008.
+
+        .. doctest::
+
+            >>> for ext in cert.extensions:
+            ...     print(ext)
+            <Extension(oid=<ObjectIdentifier(oid=2.5.29.35, name=authorityKeyIdentifier)>, critical=False, value=<AuthorityKeyIdentifier(key_identifier='\xe4}_\xd1\\\x95\x86\x08,\x05\xae\xbeu\xb6e\xa7\xd9]\xa8f', authority_cert_issuer=None, authority_cert_serial_number=None)>)>
+            <Extension(oid=<ObjectIdentifier(oid=2.5.29.14, name=subjectKeyIdentifier)>, critical=False, value=<SubjectKeyIdentifier(digest='X\x01\x84$\x1b\xbc+R\x94J=\xa5\x10r\x14Q\xf5\xaf:\xc9')>)>
+            <Extension(oid=<ObjectIdentifier(oid=2.5.29.15, name=keyUsage)>, critical=True, value=<KeyUsage(digital_signature=False, content_commitment=False, key_encipherment=False, data_encipherment=False, key_agreement=False, key_cert_sign=True, crl_sign=True, encipher_only=None, decipher_only=None)>)>
+            <Extension(oid=<ObjectIdentifier(oid=2.5.29.32, name=certificatePolicies)>, critical=False, value=<CertificatePolicies([<PolicyInformation(policy_identifier=<ObjectIdentifier(oid=2.16.840.1.101.3.2.1.48.1, name=Unknown OID)>, policy_qualifiers=None)>])>)>
+            <Extension(oid=<ObjectIdentifier(oid=2.5.29.19, name=basicConstraints)>, critical=True, value=<BasicConstraints(ca=True, path_length=None)>)>
+
+    .. method:: public_bytes(encoding)
+
+        .. versionadded:: 1.0
+
+        :param encoding: The
+            :class:`~cryptography.hazmat.primitives.serialization.Encoding`
+            that will be used to serialize the certificate.
+
+        :return bytes: The data that can be written to a file or sent
+            over the network to be verified by clients.
+
+X.509 CRL (Certificate Revocation List) Object
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. class:: CertificateRevocationList
+
+    .. versionadded:: 1.0
+
+    .. method:: fingerprint(algorithm)
+
+        :param algorithm: The
+            :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm`
+            that will be used to generate the fingerprint.
+
+        :return bytes: The fingerprint using the supplied hash algorithm, as
+            bytes.
+
+    .. attribute:: signature_hash_algorithm
+
+        :type: :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm`
+
+        Returns the
+        :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm` which
+        was used in signing this CRL.
+
+    .. attribute:: issuer
+
+        :type: :class:`Name`
+
+        The :class:`Name` of the issuer.
+
+    .. attribute:: next_update
+
+        :type: :class:`datetime.datetime`
+
+        A naïve datetime representing when the next update to this CRL is
+        expected.
+
+    .. attribute:: last_update
+
+        :type: :class:`datetime.datetime`
+
+        A naïve datetime representing when the this CRL was last updated.
+
+    .. attribute:: revoked_certificates
+
+        :type: list of :class:`RevokedCertificate`
+
+        The revoked certificates listed in this CRL.
+
+    .. attribute:: extensions
+
+        :type: :class:`Extensions`
+
+        The extensions encoded in the CRL.
+
+X.509 CSR (Certificate Signing Request) Object
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. class:: CertificateSigningRequest
+
+    .. versionadded:: 0.9
+
+    .. method:: public_key()
+
+        :type:
+            :class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPublicKey` or
+            :class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPublicKey` or
+            :class:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePublicKey`
+
+        The public key associated with the request.
+
+        .. doctest::
+
+            >>> from cryptography.hazmat.primitives.asymmetric import rsa
+            >>> public_key = csr.public_key()
+            >>> isinstance(public_key, rsa.RSAPublicKey)
+            True
+
+    .. attribute:: subject
+
+        :type: :class:`Name`
+
+        The :class:`Name` of the subject.
+
+    .. attribute:: signature_hash_algorithm
+
+        :type: :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm`
+
+        Returns the
+        :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm` which
+        was used in signing this request.
+
+        .. doctest::
+
+            >>> from cryptography.hazmat.primitives import hashes
+            >>> isinstance(csr.signature_hash_algorithm, hashes.SHA1)
+            True
+
+    .. method:: public_bytes(encoding)
+
+        .. versionadded:: 1.0
+
+        :param encoding: The
+            :class:`~cryptography.hazmat.primitives.serialization.Encoding`
+            that will be used to serialize the certificate request.
+
+        :return bytes: The data that can be written to a file or sent
+            over the network to be signed by the certificate
+            authority.
+
+X.509 Revoked Certificate Object
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. class:: RevokedCertificate
+
+    .. versionadded:: 1.0
+
+    .. attribute:: serial_number
+
+        :type: :class:`int`
+
+        An integer representing the serial number of the revoked certificate.
+
+    .. attribute:: revocation_date
+
+        :type: :class:`datetime.datetime`
+
+        A naïve datetime representing the date this certificates was revoked.
+
+    .. attribute:: extensions
+
+        :type: :class:`Extensions`
+
+        The extensions encoded in the revoked certificate.
+
+X.509 CSR (Certificate Signing Request) Builder Object
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. class:: CertificateSigningRequestBuilder
+
+    .. versionadded:: 1.0
+
+    .. doctest::
+
+        >>> from cryptography import x509
+        >>> from cryptography.hazmat.backends import default_backend
+        >>> from cryptography.hazmat.primitives import hashes
+        >>> from cryptography.hazmat.primitives.asymmetric import rsa
+        >>> private_key = rsa.generate_private_key(
+        ...     public_exponent=65537,
+        ...     key_size=2048,
+        ...     backend=default_backend()
+        ... )
+        >>> builder = x509.CertificateSigningRequestBuilder()
+        >>> builder = builder.subject_name(x509.Name([
+        ...     x509.NameAttribute(x509.OID_COMMON_NAME, u'cryptography.io'),
+        ... ]))
+        >>> builder = builder.add_extension(
+        ...     x509.BasicConstraints(ca=False, path_length=None), critical=True,
+        ... )
+        >>> request = builder.sign(
+        ...     private_key, hashes.SHA256(), default_backend()
+        ... )
+        >>> isinstance(request, x509.CertificateSigningRequest)
+        True
+
+    .. method:: subject_name(name)
+
+        :param name: The :class:`~cryptography.x509.Name` of the certificate
+            subject.
+        :returns: A new
+            :class:`~cryptography.x509.CertificateSigningRequestBuilder`.
+
+    .. method:: add_extension(extension, critical)
+
+        :param extension: The :class:`~cryptography.x509.Extension` to add to
+            the request.
+        :param critical: Set to `True` if the extension must be understood and
+             handled by whoever reads the certificate.
+        :returns: A new
+            :class:`~cryptography.x509.CertificateSigningRequestBuilder`.
+
+    .. method:: sign(private_key, algorithm, backend)
+
+        :param backend: Backend that will be used to sign the request.
+            Must support the
+            :class:`~cryptography.hazmat.backends.interfaces.X509Backend`
+            interface.
+
+        :param private_key: The
+            :class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPrivateKey`,
+            :class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPrivateKey` or
+            :class:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePrivateKey`
+            that will be used to sign the request.  When the request is
+            signed by a certificate authority, the private key's associated
+            public key will be stored in the resulting certificate.
+
+        :param algorithm: The
+            :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm`
+            that will be used to generate the request signature.
+
+        :returns: A new
+            :class:`~cryptography.x509.CertificateSigningRequest`.
+
+
+.. class:: Name
+
+    .. versionadded:: 0.8
+
+    An X509 Name is an ordered list of attributes. The object is iterable to
+    get every attribute or you can use :meth:`Name.get_attributes_for_oid` to
+    obtain the specific type you want. Names are sometimes represented as a
+    slash or comma delimited string (e.g. ``/CN=mydomain.com/O=My Org/C=US`` or
+    ``CN=mydomain.com, O=My Org, C=US``).
+
+    .. doctest::
+
+        >>> len(cert.subject)
+        3
+        >>> for attribute in cert.subject:
+        ...     print(attribute)
+        <NameAttribute(oid=<ObjectIdentifier(oid=2.5.4.6, name=countryName)>, value=u'US')>
+        <NameAttribute(oid=<ObjectIdentifier(oid=2.5.4.10, name=organizationName)>, value=u'Test Certificates 2011')>
+        <NameAttribute(oid=<ObjectIdentifier(oid=2.5.4.3, name=commonName)>, value=u'Good CA')>
+
+    .. method:: get_attributes_for_oid(oid)
+
+        :param oid: An :class:`ObjectIdentifier` instance.
+
+        :returns: A list of :class:`NameAttribute` instances that match the
+            OID provided. If nothing matches an empty list will be returned.
+
+        .. doctest::
+
+            >>> cert.subject.get_attributes_for_oid(x509.OID_COMMON_NAME)
+            [<NameAttribute(oid=<ObjectIdentifier(oid=2.5.4.3, name=commonName)>, value=u'Good CA')>]
+
+.. class:: Version
+
+    .. versionadded:: 0.7
+
+    An enumeration for X.509 versions.
+
+    .. attribute:: v1
+
+        For version 1 X.509 certificates.
+
+    .. attribute:: v3
+
+        For version 3 X.509 certificates.
+
+.. class:: NameAttribute
+
+    .. versionadded:: 0.8
+
+    An X.509 name consists of a list of NameAttribute instances.
+
+    .. attribute:: oid
+
+        :type: :class:`ObjectIdentifier`
+
+        The attribute OID.
+
+    .. attribute:: value
+
+        :type: :term:`text`
+
+        The value of the attribute.
+
+.. class:: ObjectIdentifier
+
+    .. versionadded:: 0.8
+
+    Object identifiers (frequently seen abbreviated as OID) identify the type
+    of a value (see: :class:`NameAttribute`).
+
+    .. attribute:: dotted_string
+
+        :type: :class:`str`
+
+        The dotted string value of the OID (e.g. ``"2.5.4.3"``)
+
+.. _general_name_classes:
+
+General Name Classes
+~~~~~~~~~~~~~~~~~~~~
+
+.. class:: GeneralName
+
+    .. versionadded:: 0.9
+
+    This is the generic interface that all the following classes are registered
+    against.
+
+.. class:: RFC822Name
+
+    .. versionadded:: 0.9
+
+    This corresponds to an email address. For example, ``user@example.com``.
+
+    .. attribute:: value
+
+        :type: :term:`text`
+
+.. class:: DNSName
+
+    .. versionadded:: 0.9
+
+    This corresponds to a domain name. For example, ``cryptography.io``.
+
+    .. attribute:: value
+
+        :type: :term:`text`
+
+.. class:: DirectoryName
+
+    .. versionadded:: 0.9
+
+    This corresponds to a directory name.
+
+    .. attribute:: value
+
+        :type: :class:`Name`
+
+.. class:: UniformResourceIdentifier
+
+    .. versionadded:: 0.9
+
+    This corresponds to a uniform resource identifier.  For example,
+    ``https://cryptography.io``. The URI is parsed and IDNA decoded (see
+    :rfc:`5895`).
+
+    .. note::
+
+        URIs that do not contain ``://`` in them will not be decoded.
+
+    .. attribute:: value
+
+        :type: :term:`text`
+
+.. class:: IPAddress
+
+    .. versionadded:: 0.9
+
+    This corresponds to an IP address.
+
+    .. attribute:: value
+
+        :type: :class:`~ipaddress.IPv4Address`,
+            :class:`~ipaddress.IPv6Address`,  :class:`~ipaddress.IPv4Network`,
+            or :class:`~ipaddress.IPv6Network`.
+
+.. class:: RegisteredID
+
+    .. versionadded:: 0.9
+
+    This corresponds to a registered ID.
+
+    .. attribute:: value
+
+        :type: :class:`ObjectIdentifier`
+
+.. class:: OtherName
+
+    .. versionadded:: 1.0
+
+    This corresponds to an ``otherName.``  An ``otherName`` has a type identifier and a value represented in binary DER format.
+
+    .. attribute:: type_id
+
+        :type: :class:`ObjectIdentifier`
+
+    .. attribute:: value
+
+        :type: `bytes`
+
+X.509 Extensions
+~~~~~~~~~~~~~~~~
+
+.. class:: Extensions
+
+    .. versionadded:: 0.9
+
+    An X.509 Extensions instance is an ordered list of extensions.  The object
+    is iterable to get every extension.
+
+    .. method:: get_extension_for_oid(oid)
+
+        :param oid: An :class:`ObjectIdentifier` instance.
+
+        :returns: An instance of the extension class.
+
+        :raises cryptography.x509.ExtensionNotFound: If the certificate does
+            not have the extension requested.
+
+        .. doctest::
+
+            >>> cert.extensions.get_extension_for_oid(x509.OID_BASIC_CONSTRAINTS)
+            <Extension(oid=<ObjectIdentifier(oid=2.5.29.19, name=basicConstraints)>, critical=True, value=<BasicConstraints(ca=True, path_length=None)>)>
+
+.. class:: Extension
+
+    .. versionadded:: 0.9
+
+    .. attribute:: oid
+
+        :type: :class:`ObjectIdentifier`
+
+        The :ref:`extension OID <extension_oids>`.
+
+    .. attribute:: critical
+
+        :type: bool
+
+        Determines whether a given extension is critical or not. :rfc:`5280`
+        requires that "A certificate-using system MUST reject the certificate
+        if it encounters a critical extension it does not recognize or a
+        critical extension that contains information that it cannot process".
+
+    .. attribute:: value
+
+        Returns an instance of the extension type corresponding to the OID.
+
+.. class:: KeyUsage
+
+    .. versionadded:: 0.9
+
+    The key usage extension defines the purpose of the key contained in the
+    certificate.  The usage restriction might be employed when a key that could
+    be used for more than one operation is to be restricted. It corresponds to
+    :data:`OID_KEY_USAGE`.
+
+    .. attribute:: digital_signature
+
+        :type: bool
+
+        This purpose is set to true when the subject public key is used for verifying
+        digital signatures, other than signatures on certificates
+        (``key_cert_sign``) and CRLs (``crl_sign``).
+
+    .. attribute:: content_commitment
+
+        :type: bool
+
+        This purpose is set to true when the subject public key is used for verifying
+        digital signatures, other than signatures on certificates
+        (``key_cert_sign``) and CRLs (``crl_sign``). It is used to provide a
+        non-repudiation service that protects against the signing entity
+        falsely denying some action. In the case of later conflict, a
+        reliable third party may determine the authenticity of the signed
+        data. This was called ``non_repudiation`` in older revisions of the
+        X.509 specification.
+
+    .. attribute:: key_encipherment
+
+        :type: bool
+
+        This purpose is set to true when the subject public key is used for
+        enciphering private or secret keys.
+
+    .. attribute:: data_encipherment
+
+        :type: bool
+
+        This purpose is set to true when the subject public key is used for
+        directly enciphering raw user data without the use of an intermediate
+        symmetric cipher.
+
+    .. attribute:: key_agreement
+
+        :type: bool
+
+        This purpose is set to true when the subject public key is used for key
+        agreement.  For example, when a Diffie-Hellman key is to be used for
+        key management, then this purpose is set to true.
+
+    .. attribute:: key_cert_sign
+
+        :type: bool
+
+        This purpose is set to true when the subject public key is used for
+        verifying signatures on public key certificates. If this purpose is set
+        to true then ``ca`` must be true in the :class:`BasicConstraints`
+        extension.
+
+    .. attribute:: crl_sign
+
+        :type: bool
+
+        This purpose is set to true when the subject public key is used for
+        verifying signatures on certificate revocation lists.
+
+    .. attribute:: encipher_only
+
+        :type: bool
+
+        When this purposes is set to true and the ``key_agreement`` purpose is
+        also set, the subject public key may be used only for enciphering data
+        while performing key agreement.
+
+        :raises ValueError: This is raised if accessed when ``key_agreement``
+            is false.
+
+    .. attribute:: decipher_only
+
+        :type: bool
+
+        When this purposes is set to true and the ``key_agreement`` purpose is
+        also set, the subject public key may be used only for deciphering data
+        while performing key agreement.
+
+        :raises ValueError: This is raised if accessed when ``key_agreement``
+            is false.
+
+
+.. class:: BasicConstraints
+
+    .. versionadded:: 0.9
+
+    Basic constraints is an X.509 extension type that defines whether a given
+    certificate is allowed to sign additional certificates and what path
+    length restrictions may exist. It corresponds to
+    :data:`OID_BASIC_CONSTRAINTS`.
+
+    .. attribute:: ca
+
+        :type: bool
+
+        Whether the certificate can sign certificates.
+
+    .. attribute:: path_length
+
+        :type: int or None
+
+        The maximum path length for certificates subordinate to this
+        certificate. This attribute only has meaning if ``ca`` is true.
+        If ``ca`` is true then a path length of None means there's no
+        restriction on the number of subordinate CAs in the certificate chain.
+        If it is zero or greater then it defines the maximum length for a
+        subordinate CA's certificate chain. For example, a ``path_length`` of 1
+        means the certificate can sign a subordinate CA, but the subordinate CA
+        is not allowed to create subordinates with ``ca`` set to true.
+
+.. class:: ExtendedKeyUsage
+
+    .. versionadded:: 0.9
+
+    This extension indicates one or more purposes for which the certified
+    public key may be used, in addition to or in place of the basic
+    purposes indicated in the key usage extension. The object is
+    iterable to obtain the list of :ref:`extended key usage OIDs <eku_oids>`.
+
+.. class:: OCSPNoCheck
+
+    .. versionadded:: 1.0
+
+    This presence of this extension indicates that an OCSP client can trust a
+    responder for the lifetime of the responder's certificate. CAs issuing
+    such a certificate should realize that a compromise of the responder's key
+    is as serious as the compromise of a CA key used to sign CRLs, at least for
+    the validity period of this certificate. CA's may choose to issue this type
+    of certificate with a very short lifetime and renew it frequently. This
+    extension is only relevant when the certificate is an authorized OCSP
+    responder.
+
+.. class:: NameConstraints
+
+    .. versionadded:: 1.0
+
+    The name constraints extension, which only has meaning in a CA certificate,
+    defines a name space within which all subject names in certificates issued
+    beneath the CA certificate must (or must not) be in. For specific details
+    on the way this extension should be processed see :rfc:`5280`.
+
+    .. attribute:: permitted_subtrees
+
+        :type: list of :class:`GeneralName` objects or None
+
+        The set of permitted name patterns. If a name matches this and an
+        element in ``excluded_subtrees`` it is invalid. At least one of
+        ``permitted_subtrees`` and ``excluded_subtrees`` will be non-None.
+
+    .. attribute:: excluded_subtrees
+
+        :type: list of :class:`GeneralName` objects or None
+
+        Any name matching a restriction in the ``excluded_subtrees`` field is
+        invalid regardless of information appearing in the
+        ``permitted_subtrees``. At least one of ``permitted_subtrees`` and
+        ``excluded_subtrees`` will be non-None.
+
+.. class:: AuthorityKeyIdentifier
+
+    .. versionadded:: 0.9
+
+    The authority key identifier extension provides a means of identifying the
+    public key corresponding to the private key used to sign a certificate.
+    This extension is typically used to assist in determining the appropriate
+    certificate chain. For more information about generation and use of this
+    extension see `RFC 5280 section 4.2.1.1`_.
+
+    .. attribute:: key_identifier
+
+        :type: bytes
+
+        A value derived from the public key used to verify the certificate's
+        signature.
+
+    .. attribute:: authority_cert_issuer
+
+        :type: :class:`Name` or None
+
+        The :class:`Name` of the issuer's issuer.
+
+    .. attribute:: authority_cert_serial_number
+
+        :type: int or None
+
+        The serial number of the issuer's issuer.
+
+.. class:: SubjectKeyIdentifier
+
+    .. versionadded:: 0.9
+
+    The subject key identifier extension provides a means of identifying
+    certificates that contain a particular public key.
+
+    .. attribute:: digest
+
+        :type: bytes
+
+        The binary value of the identifier.
+
+.. class:: SubjectAlternativeName
+
+    .. versionadded:: 0.9
+
+    Subject alternative name is an X.509 extension that provides a list of
+    :ref:`general name <general_name_classes>` instances that provide a set
+    of identities for which the certificate is valid. The object is iterable to
+    get every element.
+
+    .. method:: get_values_for_type(type)
+
+        :param type: A :class:`GeneralName` provider. This is one of the
+            :ref:`general name classes <general_name_classes>`.
+
+        :returns: A list of values extracted from the matched general names.
+            The type of the returned values depends on the :class:`GeneralName`.
+
+        .. doctest::
+
+            >>> from cryptography import x509
+            >>> from cryptography.hazmat.backends import default_backend
+            >>> from cryptography.hazmat.primitives import hashes
+            >>> cert = x509.load_pem_x509_certificate(cryptography_cert_pem, default_backend())
+            >>> # Get the subjectAltName extension from the certificate
+            >>> ext = cert.extensions.get_extension_for_oid(x509.OID_SUBJECT_ALTERNATIVE_NAME)
+            >>> # Get the dNSName entries from the SAN extension
+            >>> ext.value.get_values_for_type(x509.DNSName)
+            [u'www.cryptography.io', u'cryptography.io']
+
+
+.. class:: IssuerAlternativeName
+
+    .. versionadded:: 1.0
+
+    Issuer alternative name is an X.509 extension that provides a list of
+    :ref:`general name <general_name_classes>` instances that provide a set
+    of identities for the certificate issuer. The object is iterable to
+    get every element.
+
+    .. method:: get_values_for_type(type)
+
+        :param type: A :class:`GeneralName` provider. This is one of the
+            :ref:`general name classes <general_name_classes>`.
+
+        :returns: A list of values extracted from the matched general names.
+
+
+.. class:: AuthorityInformationAccess
+
+    .. versionadded:: 0.9
+
+    The authority information access extension indicates how to access
+    information and services for the issuer of the certificate in which
+    the extension appears. Information and services may include online
+    validation services (such as OCSP) and issuer data. It is an iterable,
+    containing one or more :class:`AccessDescription` instances.
+
+
+.. class:: AccessDescription
+
+    .. versionadded:: 0.9
+
+    .. attribute:: access_method
+
+        :type: :class:`ObjectIdentifier`
+
+        The access method defines what the ``access_location`` means. It must
+        be either :data:`OID_OCSP` or :data:`OID_CA_ISSUERS`. If it is
+        :data:`OID_OCSP` the access location will be where to obtain OCSP
+        information for the certificate. If it is :data:`OID_CA_ISSUERS` the
+        access location will provide additional information about the issuing
+        certificate.
+
+    .. attribute:: access_location
+
+        :type: :class:`GeneralName`
+
+        Where to access the information defined by the access method.
+
+.. class:: CRLDistributionPoints
+
+    .. versionadded:: 0.9
+
+    The CRL distribution points extension identifies how CRL information is
+    obtained. It is an iterable, containing one or more
+    :class:`DistributionPoint` instances.
+
+.. class:: DistributionPoint
+
+    .. versionadded:: 0.9
+
+    .. attribute:: full_name
+
+        :type: list of :class:`GeneralName` instances or None
+
+        This field describes methods to retrieve the CRL. At most one of
+        ``full_name`` or ``relative_name`` will be non-None.
+
+    .. attribute:: relative_name
+
+        :type: :class:`Name` or None
+
+        This field describes methods to retrieve the CRL relative to the CRL
+        issuer. At most one of ``full_name`` or ``relative_name`` will be
+        non-None.
+
+    .. attribute:: crl_issuer
+
+        :type: list of :class:`GeneralName` instances or None
+
+        Information about the issuer of the CRL.
+
+    .. attribute:: reasons
+
+        :type: frozenset of :class:`ReasonFlags` or None
+
+        The reasons a given distribution point may be used for when performing
+        revocation checks.
+
+.. class:: ReasonFlags
+
+    .. versionadded:: 0.9
+
+    An enumeration for CRL reasons.
+
+    .. attribute:: unspecified
+
+        It is unspecified why the certificate was revoked. This reason cannot
+        be used as a reason flag in a :class:`DistributionPoint`.
+
+    .. attribute:: key_compromise
+
+        This reason indicates that the private key was compromised.
+
+    .. attribute:: ca_compromise
+
+        This reason indicates that the CA issuing the certificate was
+        compromised.
+
+    .. attribute:: affiliation_changed
+
+        This reason indicates that the subject's name or other information has
+        changed.
+
+    .. attribute:: superseded
+
+        This reason indicates that a certificate has been superseded.
+
+    .. attribute:: cessation_of_operation
+
+        This reason indicates that the certificate is no longer required.
+
+    .. attribute:: certificate_hold
+
+        This reason indicates that the certificate is on hold.
+
+    .. attribute:: privilege_withdrawn
+
+        This reason indicates that the privilege granted by this certificate
+        have been withdrawn.
+
+    .. attribute:: aa_compromise
+
+        When an attribute authority has been compromised.
+
+    .. attribute:: remove_from_crl
+
+        This reason indicates that the certificate was on hold and should be
+        removed from the CRL. This reason cannot be used as a reason flag
+        in a :class:`DistributionPoint`.
+
+.. class:: InhibitAnyPolicy
+
+    .. versionadded:: 1.0
+
+    The inhibit ``anyPolicy`` extension indicates that the special OID
+    :data:`OID_ANY_POLICY`, is not considered an explicit match for other
+    :class:`CertificatePolicies` except when it appears in an intermediate
+    self-issued CA certificate.  The value indicates the number of additional
+    non-self-issued certificates that may appear in the path before
+    :data:`OID_ANY_POLICY` is no longer permitted.  For example, a value
+    of one indicates that :data:`OID_ANY_POLICY` may be processed in
+    certificates issued by the subject of this certificate, but not in
+    additional certificates in the path.
+
+    .. attribute:: skip_certs
+
+        :type: int
+
+.. class:: CertificatePolicies
+
+    .. versionadded:: 0.9
+
+    The certificate policies extension is an iterable, containing one or more
+    :class:`PolicyInformation` instances.
+
+Certificate Policies Classes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+These classes may be present within a :class:`CertificatePolicies` instance.
+
+.. class:: PolicyInformation
+
+    .. versionadded:: 0.9
+
+    Contains a policy identifier and an optional list of qualifiers.
+
+    .. attribute:: policy_identifier
+
+        :type: :class:`ObjectIdentifier`
+
+    .. attribute:: policy_qualifiers
+
+        :type: list
+
+        A list consisting of :term:`text` and/or :class:`UserNotice` objects.
+        If the value is text it is a pointer to the practice statement
+        published by the certificate authority. If it is a user notice it is
+        meant for display to the relying party when the certificate is
+        used.
+
+.. class:: UserNotice
+
+    .. versionadded:: 0.9
+
+    User notices are intended for display to a relying party when a certificate
+    is used. In practice, few if any UIs expose this data and it is a rarely
+    encoded component.
+
+    .. attribute:: notice_reference
+
+        :type: :class:`NoticeReference` or None
+
+        The notice reference field names an organization and identifies,
+        by number, a particular statement prepared by that organization.
+
+    .. attribute:: explicit_text
+
+        This field includes an arbitrary textual statement directly in the
+        certificate.
+
+        :type: :term:`text`
+
+.. class:: NoticeReference
+
+    Notice reference can name an organization and provide information about
+    notices related to the certificate. For example, it might identify the
+    organization name and notice number 1. Application software could
+    have a notice file containing the current set of notices for the named
+    organization; the application would then extract the notice text from the
+    file and display it. In practice this is rarely seen.
+
+    .. versionadded:: 0.9
+
+    .. attribute:: organization
+
+        :type: :term:`text`
+
+    .. attribute:: notice_numbers
+
+        :type: list
+
+        A list of integers.
+
+Object Identifiers
+~~~~~~~~~~~~~~~~~~
+
+X.509 elements are frequently identified by :class:`ObjectIdentifier`
+instances. The following common OIDs are available as constants.
+
+Name OIDs
+~~~~~~~~~
+
+.. data:: OID_COMMON_NAME
+
+    Corresponds to the dotted string ``"2.5.4.3"``. Historically the domain
+    name would be encoded here for server certificates. :rfc:`2818` deprecates
+    this practice and names of that type should now be located in a
+    SubjectAlternativeName extension. This OID is typically seen in X.509 names.
+
+.. data:: OID_COUNTRY_NAME
+
+    Corresponds to the dotted string ``"2.5.4.6"``. This OID is typically seen
+    in X.509 names.
+
+.. data:: OID_LOCALITY_NAME
+
+    Corresponds to the dotted string ``"2.5.4.7"``. This OID is typically seen
+    in X.509 names.
+
+.. data:: OID_STATE_OR_PROVINCE_NAME
+
+    Corresponds to the dotted string ``"2.5.4.8"``. This OID is typically seen
+    in X.509 names.
+
+.. data:: OID_ORGANIZATION_NAME
+
+    Corresponds to the dotted string ``"2.5.4.10"``. This OID is typically seen
+    in X.509 names.
+
+.. data:: OID_ORGANIZATIONAL_UNIT_NAME
+
+    Corresponds to the dotted string ``"2.5.4.11"``. This OID is typically seen
+    in X.509 names.
+
+.. data:: OID_SERIAL_NUMBER
+
+    Corresponds to the dotted string ``"2.5.4.5"``. This is distinct from the
+    serial number of the certificate itself (which can be obtained with
+    :func:`Certificate.serial`). This OID is typically seen in X.509 names.
+
+.. data:: OID_SURNAME
+
+    Corresponds to the dotted string ``"2.5.4.4"``. This OID is typically seen
+    in X.509 names.
+
+.. data:: OID_GIVEN_NAME
+
+    Corresponds to the dotted string ``"2.5.4.42"``. This OID is typically seen
+    in X.509 names.
+
+.. data:: OID_TITLE
+
+    Corresponds to the dotted string ``"2.5.4.12"``. This OID is typically seen
+    in X.509 names.
+
+.. data:: OID_GENERATION_QUALIFIER
+
+    Corresponds to the dotted string ``"2.5.4.44"``. This OID is typically seen
+    in X.509 names.
+
+.. data:: OID_DN_QUALIFIER
+
+    Corresponds to the dotted string ``"2.5.4.46"``. This specifies
+    disambiguating information to add to the relative distinguished name of an
+    entry. See :rfc:`2256`. This OID is typically seen in X.509 names.
+
+.. data:: OID_PSEUDONYM
+
+    Corresponds to the dotted string ``"2.5.4.65"``. This OID is typically seen
+    in X.509 names.
+
+.. data:: OID_DOMAIN_COMPONENT
+
+    Corresponds to the dotted string ``"0.9.2342.19200300.100.1.25"``. A string
+    holding one component of a domain name. See :rfc:`4519`. This OID is
+    typically seen in X.509 names.
+
+.. data:: OID_EMAIL_ADDRESS
+
+    Corresponds to the dotted string ``"1.2.840.113549.1.9.1"``. This OID is
+    typically seen in X.509 names.
+
+Signature Algorithm OIDs
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. data:: OID_RSA_WITH_MD5
+
+    Corresponds to the dotted string ``"1.2.840.113549.1.1.4"``. This is
+    an MD5 digest signed by an RSA key.
+
+.. data:: OID_RSA_WITH_SHA1
+
+    Corresponds to the dotted string ``"1.2.840.113549.1.1.5"``. This is
+    a SHA1 digest signed by an RSA key.
+
+.. data:: OID_RSA_WITH_SHA224
+
+    Corresponds to the dotted string ``"1.2.840.113549.1.1.14"``. This is
+    a SHA224 digest signed by an RSA key.
+
+.. data:: OID_RSA_WITH_SHA256
+
+    Corresponds to the dotted string ``"1.2.840.113549.1.1.11"``. This is
+    a SHA256 digest signed by an RSA key.
+
+.. data:: OID_RSA_WITH_SHA384
+
+    Corresponds to the dotted string ``"1.2.840.113549.1.1.12"``. This is
+    a SHA384 digest signed by an RSA key.
+
+.. data:: OID_RSA_WITH_SHA512
+
+    Corresponds to the dotted string ``"1.2.840.113549.1.1.13"``. This is
+    a SHA512 digest signed by an RSA key.
+
+.. data:: OID_ECDSA_WITH_SHA1
+
+    Corresponds to the dotted string ``"1.2.840.10045.4.1"``. This is a SHA1
+    digest signed by an ECDSA key.
+
+.. data:: OID_ECDSA_WITH_SHA224
+
+    Corresponds to the dotted string ``"1.2.840.10045.4.3.1"``. This is
+    a SHA224 digest signed by an ECDSA key.
+
+.. data:: OID_ECDSA_WITH_SHA256
+
+    Corresponds to the dotted string ``"1.2.840.10045.4.3.2"``. This is
+    a SHA256 digest signed by an ECDSA key.
+
+.. data:: OID_ECDSA_WITH_SHA384
+
+    Corresponds to the dotted string ``"1.2.840.10045.4.3.3"``. This is
+    a SHA384 digest signed by an ECDSA key.
+
+.. data:: OID_ECDSA_WITH_SHA512
+
+    Corresponds to the dotted string ``"1.2.840.10045.4.3.4"``. This is
+    a SHA512 digest signed by an ECDSA key.
+
+.. data:: OID_DSA_WITH_SHA1
+
+    Corresponds to the dotted string ``"1.2.840.10040.4.3"``. This is
+    a SHA1 digest signed by a DSA key.
+
+.. data:: OID_DSA_WITH_SHA224
+
+    Corresponds to the dotted string ``"2.16.840.1.101.3.4.3.1"``. This is
+    a SHA224 digest signed by a DSA key.
+
+.. data:: OID_DSA_WITH_SHA256
+
+    Corresponds to the dotted string ``"2.16.840.1.101.3.4.3.2"``. This is
+    a SHA256 digest signed by a DSA key.
+
+.. _eku_oids:
+
+Extended Key Usage OIDs
+~~~~~~~~~~~~~~~~~~~~~~~
+
+.. data:: OID_SERVER_AUTH
+
+    Corresponds to the dotted string ``"1.3.6.1.5.5.7.3.1"``. This is used to
+    denote that a certificate may be used for TLS web server authentication.
+
+.. data:: OID_CLIENT_AUTH
+
+    Corresponds to the dotted string ``"1.3.6.1.5.5.7.3.2"``. This is used to
+    denote that a certificate may be used for TLS web client authentication.
+
+.. data:: OID_CODE_SIGNING
+
+    Corresponds to the dotted string ``"1.3.6.1.5.5.7.3.3"``. This is used to
+    denote that a certificate may be used for code signing.
+
+.. data:: OID_EMAIL_PROTECTION
+
+    Corresponds to the dotted string ``"1.3.6.1.5.5.7.3.4"``. This is used to
+    denote that a certificate may be used for email protection.
+
+.. data:: OID_TIME_STAMPING
+
+    Corresponds to the dotted string ``"1.3.6.1.5.5.7.3.8"``. This is used to
+    denote that a certificate may be used for time stamping.
+
+.. data:: OID_OCSP_SIGNING
+
+    Corresponds to the dotted string ``"1.3.6.1.5.5.7.3.9"``. This is used to
+    denote that a certificate may be used for signing OCSP responses.
+
+Authority Information Access OIDs
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. data:: OID_OCSP
+
+    Corresponds to the dotted string ``"1.3.6.1.5.5.7.48.1"``. Used as the
+    identifier for OCSP data in :class:`AccessDescription` objects.
+
+.. data:: OID_CA_ISSUERS
+
+    Corresponds to the dotted string ``"1.3.6.1.5.5.7.48.2"``. Used as the
+    identifier for CA issuer data in :class:`AccessDescription` objects.
+
+Policy Qualifier OIDs
+~~~~~~~~~~~~~~~~~~~~~
+
+.. data:: OID_CPS_QUALIFIER
+
+    Corresponds to the dotted string ``"1.3.6.1.5.5.7.2.1"``.
+
+.. data:: OID_CPS_USER_NOTICE
+
+    Corresponds to the dotted string ``"1.3.6.1.5.5.7.2.2"``.
+
+.. data:: OID_ANY_POLICY
+
+    Corresponds to the dotted string ``"2.5.29.32.0"``.
+
+.. _extension_oids:
+
+Extension OIDs
+~~~~~~~~~~~~~~
+
+.. data:: OID_BASIC_CONSTRAINTS
+
+    Corresponds to the dotted string ``"2.5.29.19"``. The identifier for the
+    :class:`BasicConstraints` extension type.
+
+.. data:: OID_KEY_USAGE
+
+    Corresponds to the dotted string ``"2.5.29.15"``. The identifier for the
+    :class:`KeyUsage` extension type.
+
+.. data:: OID_SUBJECT_ALTERNATIVE_NAME
+
+    Corresponds to the dotted string ``"2.5.29.17"``. The identifier for the
+    :class:`SubjectAlternativeName` extension type.
+
+.. data:: OID_ISSUER_ALTERNATIVE_NAME
+
+    Corresponds to the dotted string ``"2.5.29.18"``. The identifier for the
+    :class:`IssuerAlternativeName` extension type.
+
+.. data:: OID_SUBJECT_KEY_IDENTIFIER
+
+    Corresponds to the dotted string ``"2.5.29.14"``. The identifier for the
+    :class:`SubjectKeyIdentifier` extension type.
+
+.. data:: OID_NAME_CONSTRAINTS
+
+    Corresponds to the dotted string ``"2.5.29.30"``. The identifier for the
+    :class:`NameConstraints` extension type.
+
+.. data:: OID_CRL_DISTRIBUTION_POINTS
+
+    Corresponds to the dotted string ``"2.5.29.31"``. The identifier for the
+    :class:`CRLDistributionPoints` extension type.
+
+.. data:: OID_CERTIFICATE_POLICIES
+
+    Corresponds to the dotted string ``"2.5.29.32"``. The identifier for the
+    :class:`CertificatePolicies` extension type.
+
+.. data:: OID_AUTHORITY_KEY_IDENTIFIER
+
+    Corresponds to the dotted string ``"2.5.29.35"``. The identifier for the
+    :class:`AuthorityKeyIdentifier` extension type.
+
+.. data:: OID_EXTENDED_KEY_USAGE
+
+    Corresponds to the dotted string ``"2.5.29.37"``. The identifier for the
+    :class:`ExtendedKeyUsage` extension type.
+
+.. data:: OID_AUTHORITY_INFORMATION_ACCESS
+
+    Corresponds to the dotted string ``"1.3.6.1.5.5.7.1.1"``. The identifier
+    for the :class:`AuthorityInformationAccess` extension type.
+
+.. data:: OID_OCSP_NO_CHECK
+
+    Corresponds to the dotted string ``"1.3.6.1.5.5.7.48.1.5"``. The identifier
+    for the :class:`OCSPNoCheck` extension type.
+
+Exceptions
+~~~~~~~~~~
+
+.. class:: InvalidVersion
+
+    This is raised when an X.509 certificate has an invalid version number.
+
+    .. attribute:: parsed_version
+
+        :type: int
+
+        Returns the raw version that was parsed from the certificate.
+
+.. class:: DuplicateExtension
+
+    This is raised when more than one X.509 extension of the same type is
+    found within a certificate.
+
+    .. attribute:: oid
+
+        :type: :class:`ObjectIdentifier`
+
+        Returns the OID.
+
+.. class:: UnsupportedExtension
+
+    This is raised when a certificate contains an unsupported extension type.
+
+    .. attribute:: oid
+
+        :type: :class:`ObjectIdentifier`
+
+        Returns the OID.
+
+.. class:: ExtensionNotFound
+
+    This is raised when calling :meth:`Extensions.get_extension_for_oid` with
+    an extension OID that is not present in the certificate.
+
+    .. attribute:: oid
+
+        :type: :class:`ObjectIdentifier`
+
+        Returns the OID.
+
+.. class:: UnsupportedGeneralNameType
+
+    This is raised when a certificate contains an unsupported general name
+    type in an extension.
+
+    .. attribute:: type
+
+        :type: int
+
+        The integer value of the unsupported type. The complete list of
+        types can be found in `RFC 5280 section 4.2.1.6`_.
+
+
+.. _`public key infrastructure`: https://en.wikipedia.org/wiki/Public_key_infrastructure
+.. _`TLS`: https://en.wikipedia.org/wiki/Transport_Layer_Security
+.. _`RFC 5280 section 4.2.1.1`: https://tools.ietf.org/html/rfc5280#section-4.2.1.1
+.. _`RFC 5280 section 4.2.1.6`: https://tools.ietf.org/html/rfc5280#section-4.2.1.6