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