Reorganize the x509 docs in prep for a tutorial
diff --git a/docs/x509/reference.rst b/docs/x509/reference.rst
new file mode 100644
index 0000000..36fa972
--- /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