docs/x509.rst

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` used in
        the certificate's signature.

        .. note::
            Items signed by the parsed certificate do not have to use the same
            hash algorithm.

        .. 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_MD5_WITH_RSA

    Corresponds to the dotted string ``"1.2.840.113549.1.1.4"``. This is
    an MD5 digest signed by an RSA key.

.. data:: OID_SHA1_WITH_RSA

    Corresponds to the dotted string ``"1.2.840.113549.1.1.5"``. This is
    a SHA1 digest signed by an RSA key.

.. data:: OID_SHA224_WITH_RSA

    Corresponds to the dotted string ``"1.2.840.113549.1.1.14"``. This is
    a SHA224 digest signed by an RSA key.

.. data:: OID_SHA256_WITH_RSA

    Corresponds to the dotted string ``"1.2.840.113549.1.1.11"``. This is
    a SHA256 digest signed by an RSA key.

.. data:: OID_SHA384_WITH_RSA

    Corresponds to the dotted string ``"1.2.840.113549.1.1.12"``. This is
    a SHA384 digest signed by an RSA key.

.. data:: OID_SHA512_WITH_RSA

    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