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.interfaces.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.interfaces.DSAPublicKey` or
            :class:`~cryptography.hazmat.primitives.interfaces.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.


.. class:: Name

    .. versionadded:: 0.8

    An X509 Name is an ordered list of attributes. The entire list can be
    obtained with :attr:`attributes` or you can use the helper properties 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``).

    .. attribute:: attributes

        :type: :class:`list`

        A list of all the :class:`NameAttribute` objects.

        .. doctest::

            >>> len(cert.subject.attributes)
            3

    .. attribute:: country_name

        :type: :class:`list`

        A list of country name :class:`NameAttribute` objects.

        .. doctest::

            >>> cert.subject.country_name == [
            ...    x509.NameAttribute(
            ...        x509.OID_COUNTRY_NAME,
            ...        'US'
            ...    )
            ... ]
            True

    .. attribute:: organization_name

        :type: :class:`list`

        A list of organization name :class:`NameAttribute` objects.

    .. attribute:: organizational_unit_name

        :type: :class:`list`

        A list of organizational unit name :class:`NameAttribute` objects.

    .. attribute:: dn_qualifier

        :type: :class:`list`

        A list of DN qualifier :class:`NameAttribute` objects.

    .. attribute:: state_or_province_name

        :type: :class:`list`

        A list of state or province name :class:`NameAttribute` objects.

    .. attribute:: common_name

        :type: :class:`list`

        A list of common name :class:`NameAttribute` objects.

    .. attribute:: serial_number

        :type: :class:`list`

        A list of serial number :class:`NameAttribute` objects. This is not the
        same as the certificate's serial number.

    .. attribute:: locality_name

        :type: :class:`list`

        A list of locality name :class:`NameAttribute` objects.

    .. attribute:: title

        :type: :class:`list`

        A list of title :class:`NameAttribute` objects.

    .. attribute:: surname

        :type: :class:`list`

        A list of surname :class:`NameAttribute` objects.

    .. attribute:: given_name

        :type: :class:`list`

        A list of given name :class:`NameAttribute` objects.

    .. attribute:: pseudonym

        :type: :class:`list`

        A list of pseudonym :class:`NameAttribute` objects.

    .. attribute:: generation_qualifier

        :type: :class:`list`

        A list of generation qualifier :class:`NameAttribute` objects.

    .. attribute:: domain_component

        :type: :class:`list`

        A list of domain component :class:`NameAttribute` objects.

    .. attribute:: email_address

        :type: :class:`list`

        A list of email address :class:`NameAttribute` objects.

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

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

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