X.509 ===== .. currentmodule:: cryptography.x509 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`. .. testsetup:: 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() .. 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 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 .. 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"``) 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_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. 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. .. _`public key infrastructure`: https://en.wikipedia.org/wiki/Public_key_infrastructure .. _`TLS`: https://en.wikipedia.org/wiki/Transport_Layer_Security