From 4af5b37dfe3208706445fb1880f705236625a2f5 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Sun, 12 Jul 2015 10:30:59 -0500 Subject: Reorganize the x509 docs in prep for a tutorial --- docs/index.rst | 2 +- docs/x509.rst | 1588 ----------------------------------------------- docs/x509/index.rst | 14 + docs/x509/reference.rst | 1584 ++++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 1599 insertions(+), 1589 deletions(-) delete mode 100644 docs/x509.rst create mode 100644 docs/x509/index.rst create mode 100644 docs/x509/reference.rst diff --git a/docs/index.rst b/docs/index.rst index 35f80a2d..5c26a754 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -63,7 +63,7 @@ The recipes layer :maxdepth: 2 fernet - x509 + x509/index random-numbers exceptions faq diff --git a/docs/x509.rst b/docs/x509.rst deleted file mode 100644 index bcb6ee66..00000000 --- a/docs/x509.rst +++ /dev/null @@ -1,1588 +0,0 @@ -X.509 -===== - -.. 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() - -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`_. - -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 `. - - .. doctest:: - - >>> cert.version - - - .. 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) - , critical=False, value=)> - , critical=False, value=)> - , critical=True, value=)> - , critical=False, value=, policy_qualifiers=None)>])>)> - , critical=True, value=)> - - .. 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) - , value=u'US')> - , value=u'Test Certificates 2011')> - , 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) - [, 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) - , critical=True, value=)> - -.. class:: Extension - - .. versionadded:: 0.9 - - .. attribute:: oid - - :type: :class:`ObjectIdentifier` - - The :ref:`extension OID `. - - .. 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 `. - -.. 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 ` 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 `. - - :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 ` 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 `. - - :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 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 `. + + .. doctest:: + + >>> cert.version + + + .. 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) + , critical=False, value=)> + , critical=False, value=)> + , critical=True, value=)> + , critical=False, value=, policy_qualifiers=None)>])>)> + , critical=True, value=)> + + .. 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) + , value=u'US')> + , value=u'Test Certificates 2011')> + , 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) + [, 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) + , critical=True, value=)> + +.. class:: Extension + + .. versionadded:: 0.9 + + .. attribute:: oid + + :type: :class:`ObjectIdentifier` + + The :ref:`extension OID `. + + .. 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 `. + +.. 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 ` 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 `. + + :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 ` 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 `. + + :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 -- cgit v1.2.3 From 856b87b9c35c2a88f01fbbc7f0242a33c4f7d300 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Sun, 12 Jul 2015 10:31:41 -0500 Subject: these were moved --- docs/x509/reference.rst | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/x509/reference.rst b/docs/x509/reference.rst index 36fa972a..9179468f 100644 --- a/docs/x509/reference.rst +++ b/docs/x509/reference.rst @@ -1578,7 +1578,5 @@ Exceptions 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 -- cgit v1.2.3 From 5e0da3aad87d3c7ee617ad354973a8f9b0ed956e Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Sun, 12 Jul 2015 10:35:56 -0500 Subject: updated links in the changelog --- CHANGELOG.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.rst b/CHANGELOG.rst index 475a2a35..85f84477 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -93,7 +93,7 @@ Changelog Note that unsupported extensions with the critical flag raise :class:`~cryptography.x509.UnsupportedExtension` while unsupported extensions set to non-critical are silently ignored. Read the - :doc:`X.509 documentation` for more information. + :doc:`X.509 documentation` for more information. 0.8.2 - 2015-04-10 ~~~~~~~~~~~~~~~~~~ @@ -120,7 +120,7 @@ Changelog from :mod:`~cryptography.hazmat.primitives.interfaces` to :mod:`~cryptography.hazmat.primitives.kdf`. * Added support for parsing X.509 names. See the - :doc:`X.509 documentation` for more information. + :doc:`X.509 documentation` for more information. * Added :func:`~cryptography.hazmat.primitives.serialization.load_der_private_key` to support loading of DER encoded private keys and @@ -256,7 +256,7 @@ Changelog support the loading of OpenSSH public keys (:rfc:`4253`). Only RSA and DSA keys are currently supported. * Added initial support for X.509 certificate parsing. See the - :doc:`X.509 documentation` for more information. + :doc:`X.509 documentation` for more information. 0.6.1 - 2014-10-15 ~~~~~~~~~~~~~~~~~~ -- cgit v1.2.3 From b32b005b1fa3965ebc76131eb4c6ebd352cc6f1a Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Sun, 12 Jul 2015 10:41:46 -0500 Subject: fixed this doc too --- docs/hazmat/primitives/asymmetric/serialization.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/hazmat/primitives/asymmetric/serialization.rst b/docs/hazmat/primitives/asymmetric/serialization.rst index 7839f346..8d51f0d7 100644 --- a/docs/hazmat/primitives/asymmetric/serialization.rst +++ b/docs/hazmat/primitives/asymmetric/serialization.rst @@ -97,8 +97,8 @@ all begin with ``-----BEGIN {format}-----`` and end with ``-----END .. note:: A PEM block which starts with ``-----BEGIN CERTIFICATE-----`` is not a - public or private key, it's an :doc:`X.509 Certificate `. You can - load it using :func:`~cryptography.x509.load_pem_x509_certificate` and + public or private key, it's an :doc:`X.509 Certificate `. You + can load it using :func:`~cryptography.x509.load_pem_x509_certificate` and extract the public key with :meth:`Certificate.public_key `. -- cgit v1.2.3