| 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 <cryptography.x509.Version>`. |
| |
| .. doctest:: |
| |
| >>> cert.version |
| <Version.v3: 2> |
| |
| .. method:: fingerprint(algorithm) |
| |
| :param algorithm: The |
| :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm` |
| that will be used to generate the fingerprint. |
| |
| :return bytes: The fingerprint using the supplied hash algorithm as |
| bytes. |
| |
| .. doctest:: |
| |
| >>> from cryptography.hazmat.primitives import hashes |
| >>> cert.fingerprint(hashes.SHA256()) |
| '\x86\xd2\x187Gc\xfc\xe7}[+E9\x8d\xb4\x8f\x10\xe5S\xda\x18u\xbe}a\x03\x08[\xac\xa04?' |
| |
| .. attribute:: serial |
| |
| :type: int |
| |
| The serial as a Python integer. |
| |
| .. doctest:: |
| |
| >>> cert.serial |
| 2 |
| |
| .. method:: public_key() |
| |
| :type: |
| :class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPublicKey` or |
| :class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPublicKey` or |
| :class:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePublicKey` |
| |
| The public key associated with the certificate. |
| |
| .. doctest:: |
| |
| >>> from cryptography.hazmat.primitives.asymmetric import rsa |
| >>> public_key = cert.public_key() |
| >>> isinstance(public_key, rsa.RSAPublicKey) |
| True |
| |
| .. attribute:: not_valid_before |
| |
| :type: :class:`datetime.datetime` |
| |
| A naïve datetime representing the beginning of the validity period for |
| the certificate in UTC. This value is inclusive. |
| |
| .. doctest:: |
| |
| >>> cert.not_valid_before |
| datetime.datetime(2010, 1, 1, 8, 30) |
| |
| .. attribute:: not_valid_after |
| |
| :type: :class:`datetime.datetime` |
| |
| A naïve datetime representing the end of the validity period for the |
| certificate in UTC. This value is inclusive. |
| |
| .. doctest:: |
| |
| >>> cert.not_valid_after |
| datetime.datetime(2030, 12, 31, 8, 30) |
| |
| .. attribute:: issuer |
| |
| .. versionadded:: 0.8 |
| |
| :type: :class:`Name` |
| |
| The :class:`Name` of the issuer. |
| |
| .. attribute:: subject |
| |
| .. versionadded:: 0.8 |
| |
| :type: :class:`Name` |
| |
| The :class:`Name` of the subject. |
| |
| .. attribute:: signature_hash_algorithm |
| |
| :type: :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm` |
| |
| Returns the |
| :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm` which |
| was used in signing this certificate. |
| |
| .. doctest:: |
| |
| >>> from cryptography.hazmat.primitives import hashes |
| >>> isinstance(cert.signature_hash_algorithm, hashes.SHA256) |
| True |
| |
| .. class:: Name |
| |
| .. versionadded:: 0.8 |
| |
| An X509 Name is an ordered list of attributes. The object is iterable to |
| get every attribute or you can use :meth:`Name.get_attributes_for_oid` to |
| obtain the specific type you want. Names are sometimes represented as a |
| slash or comma delimited string (e.g. ``/CN=mydomain.com/O=My Org/C=US`` or |
| ``CN=mydomain.com, O=My Org, C=US``). |
| |
| .. doctest:: |
| |
| >>> len(cert.subject) |
| 3 |
| >>> for attribute in cert.subject: |
| ... print(attribute) |
| <NameAttribute(oid=<ObjectIdentifier(oid=2.5.4.6, name=countryName)>, value=u'US')> |
| <NameAttribute(oid=<ObjectIdentifier(oid=2.5.4.10, name=organizationName)>, value=u'Test Certificates 2011')> |
| <NameAttribute(oid=<ObjectIdentifier(oid=2.5.4.3, name=commonName)>, value=u'Good CA')> |
| |
| .. method:: get_attributes_for_oid(oid) |
| |
| :param oid: An :class:`ObjectIdentifier` instance. |
| |
| :returns: A list of :class:`NameAttribute` instances that match the |
| OID provided. If nothing matches an empty list will be returned. |
| |
| .. doctest:: |
| |
| >>> cert.subject.get_attributes_for_oid(x509.OID_COMMON_NAME) |
| [<NameAttribute(oid=<ObjectIdentifier(oid=2.5.4.3, name=commonName)>, value=u'Good CA')>] |
| |
| .. class:: Version |
| |
| .. versionadded:: 0.7 |
| |
| An enumeration for X.509 versions. |
| |
| .. attribute:: v1 |
| |
| For version 1 X.509 certificates. |
| |
| .. attribute:: v3 |
| |
| For version 3 X.509 certificates. |
| |
| .. class:: NameAttribute |
| |
| .. versionadded:: 0.8 |
| |
| An X.509 name consists of a list of NameAttribute instances. |
| |
| .. attribute:: oid |
| |
| :type: :class:`ObjectIdentifier` |
| |
| The attribute OID. |
| |
| .. attribute:: value |
| |
| :type: :term:`text` |
| |
| The value of the attribute. |
| |
| .. class:: ObjectIdentifier |
| |
| .. versionadded:: 0.8 |
| |
| Object identifiers (frequently seen abbreviated as OID) identify the type |
| of a value (see: :class:`NameAttribute`). |
| |
| .. attribute:: dotted_string |
| |
| :type: :class:`str` |
| |
| The dotted string value of the OID (e.g. ``"2.5.4.3"``) |
| |
| 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 |