Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / python / cryptography / e76cd27c28f75f3972ddcf5e15d5e37e6da2098e / . / docs / x509.rst
blob: c682e5e88e083168ba3c3cc530ea91c9feb6f669 [file] [log] [blame]
Paul Kehrer016e08a2014-11-26 09:41:18 -1000[diff] [blame]1.. hazmat::
2
3X.509
4=====
5
Paul Kehrera9d78c12014-11-26 10:59:03 -1000[diff] [blame]6.. currentmodule:: cryptography.x509
Paul Kehrer016e08a2014-11-26 09:41:18 -1000[diff] [blame]7
8X.509 is an ITU-T standard for a `public key infrastructure`_. X.509v3 is
Paul Kehrera68fd332014-11-27 07:08:40 -1000[diff] [blame]9defined in :rfc:`5280` (which obsoletes :rfc:`2459` and :rfc:`3280`). X.509
10certificates are commonly used in protocols like `TLS`_.
Paul Kehrer016e08a2014-11-26 09:41:18 -1000[diff] [blame]11
Paul Kehrerb2de9482014-12-11 14:54:48 -0600[diff] [blame]12
13Loading Certificates
14~~~~~~~~~~~~~~~~~~~~
Paul Kehrer016e08a2014-11-26 09:41:18 -1000[diff] [blame]15
16.. function:: load_pem_x509_certificate(data, backend)
17
18 .. versionadded:: 0.7
19
Paul Kehrere76cd272014-12-14 19:00:51 -0600[diff] [blame^]20 Deserialize a certificate from PEM encoded data. PEM certificates are
21 base64 decoded and have delimiters that look like
22 ``-----BEGIN CERTIFICATE-----``.
Paul Kehrer016e08a2014-11-26 09:41:18 -1000[diff] [blame]23
24 :param bytes data: The PEM encoded certificate data.
25
26 :param backend: A backend supporting the
27 :class:`~cryptography.hazmat.backends.interfaces.X509Backend`
28 interface.
29
Paul Kehrere76cd272014-12-14 19:00:51 -0600[diff] [blame^]30 :returns: An instance of :class:`~cryptography.x509.Certificate`.
Paul Kehrer016e08a2014-11-26 09:41:18 -1000[diff] [blame]31
32.. function:: load_der_x509_certificate(data, backend)
33
34 .. versionadded:: 0.7
35
Paul Kehrere76cd272014-12-14 19:00:51 -0600[diff] [blame^]36 Deserialize a certificate from DER encoded data. DER is a binary format
37 and is commonly found in files with the ``cer`` suffix (although file
38 suffixes are not a guarantee of encoding type).
Paul Kehrer016e08a2014-11-26 09:41:18 -1000[diff] [blame]39
40 :param bytes data: The DER encoded certificate data.
41
42 :param backend: A backend supporting the
43 :class:`~cryptography.hazmat.backends.interfaces.X509Backend`
44 interface.
45
Paul Kehrere76cd272014-12-14 19:00:51 -0600[diff] [blame^]46 :returns: An instance of :class:`~cryptography.x509.Certificate`.
Paul Kehrer016e08a2014-11-26 09:41:18 -1000[diff] [blame]47
48.. testsetup::
49
50 pem_data = b"""
51 -----BEGIN CERTIFICATE-----
52 MIIDfDCCAmSgAwIBAgIBAjANBgkqhkiG9w0BAQsFADBFMQswCQYDVQQGEwJVUzEf
53 MB0GA1UEChMWVGVzdCBDZXJ0aWZpY2F0ZXMgMjAxMTEVMBMGA1UEAxMMVHJ1c3Qg
54 QW5jaG9yMB4XDTEwMDEwMTA4MzAwMFoXDTMwMTIzMTA4MzAwMFowQDELMAkGA1UE
55 BhMCVVMxHzAdBgNVBAoTFlRlc3QgQ2VydGlmaWNhdGVzIDIwMTExEDAOBgNVBAMT
56 B0dvb2QgQ0EwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCQWJpHYo37
57 Xfb7oJSPe+WvfTlzIG21WQ7MyMbGtK/m8mejCzR6c+f/pJhEH/OcDSMsXq8h5kXa
58 BGqWK+vSwD/Pzp5OYGptXmGPcthDtAwlrafkGOS4GqIJ8+k9XGKs+vQUXJKsOk47
59 RuzD6PZupq4s16xaLVqYbUC26UcY08GpnoLNHJZS/EmXw1ZZ3d4YZjNlpIpWFNHn
60 UGmdiGKXUPX/9H0fVjIAaQwjnGAbpgyCumWgzIwPpX+ElFOUr3z7BoVnFKhIXze+
61 VmQGSWxZxvWDUN90Ul0tLEpLgk3OVxUB4VUGuf15OJOpgo1xibINPmWt14Vda2N9
62 yrNKloJGZNqLAgMBAAGjfDB6MB8GA1UdIwQYMBaAFOR9X9FclYYILAWuvnW2ZafZ
63 XahmMB0GA1UdDgQWBBRYAYQkG7wrUpRKPaUQchRR9a86yTAOBgNVHQ8BAf8EBAMC
64 AQYwFwYDVR0gBBAwDjAMBgpghkgBZQMCATABMA8GA1UdEwEB/wQFMAMBAf8wDQYJ
65 KoZIhvcNAQELBQADggEBADWHlxbmdTXNwBL/llwhQqwnazK7CC2WsXBBqgNPWj7m
66 tvQ+aLG8/50Qc2Sun7o2VnwF9D18UUe8Gj3uPUYH+oSI1vDdyKcjmMbKRU4rk0eo
67 3UHNDXwqIVc9CQS9smyV+x1HCwL4TTrq+LXLKx/qVij0Yqk+UJfAtrg2jnYKXsCu
68 FMBQQnWCGrwa1g1TphRp/RmYHnMynYFmZrXtzFz+U9XEA7C+gPq4kqDI/iVfIT1s
69 6lBtdB50lrDVwl2oYfAvW/6sC2se2QleZidUmrziVNP4oEeXINokU6T6p//HM1FG
70 QYw2jOvpKcKtWCSAnegEbgsGYzATKjmPJPJ0npHFqzM=
71 -----END CERTIFICATE-----
72 """.strip()
73
74.. doctest::
75
76 >>> from cryptography.x509 import load_pem_x509_certificate
77 >>> from cryptography.hazmat.backends import default_backend
78 >>> cert = load_pem_x509_certificate(pem_data, default_backend())
79 >>> cert.serial
80 2
81
Paul Kehrere76cd272014-12-14 19:00:51 -0600[diff] [blame^]82X.509 Certificate Object
83~~~~~~~~~~~~~~~~~~~~~~~~
Paul Kehrerb2de9482014-12-11 14:54:48 -0600[diff] [blame]84
Paul Kehrere76cd272014-12-14 19:00:51 -0600[diff] [blame^]85.. class:: Certificate
Paul Kehrerb2de9482014-12-11 14:54:48 -0600[diff] [blame]86
87 .. versionadded:: 0.7
88
89 .. attribute:: version
90
Paul Kehrere76cd272014-12-14 19:00:51 -0600[diff] [blame^]91 :type: :class:`~cryptography.x509.Version`
Paul Kehrerb2de9482014-12-11 14:54:48 -0600[diff] [blame]92
Paul Kehrere76cd272014-12-14 19:00:51 -0600[diff] [blame^]93 The certificate version as an enumeration. Version 3 certificates are
94 the latest version and also the only type you should see in practice.
Paul Kehrerb2de9482014-12-11 14:54:48 -0600[diff] [blame]95
96 .. method:: fingerprint(algorithm)
97
98 :param algorithm: The
99 :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm`
100 that will be used to generate the fingerprint.
101
102 :return bytes: The fingerprint using the supplied hash algorithm as
103 bytes.
104
105 .. attribute:: serial
106
107 :type: int
108
109 The serial as a Python integer.
110
111 .. method:: public_key()
112
113 :type:
114 :class:`~cryptography.hazmat.primitives.interfaces.RSAPublicKey` or
115 :class:`~cryptography.hazmat.primitives.interfaces.DSAPublicKey` or
116 :class:`~cryptography.hazmat.primitives.interfaces.EllipticCurvePublicKey`
117
118 The public key associated with the certificate.
119
120 .. attribute:: not_valid_before
121
122 :type: :class:`datetime.datetime`
123
124 A naïve datetime representing the beginning of the validity period for the
125 certificate in UTC. This value is inclusive.
126
127 .. attribute:: not_valid_after
128
129 :type: :class:`datetime.datetime`
130
131 A naïve datetime representing the end of the validity period for the
132 certificate in UTC. This value is inclusive.
133
134
Paul Kehrere76cd272014-12-14 19:00:51 -0600[diff] [blame^]135.. class:: Version
Paul Kehrer016e08a2014-11-26 09:41:18 -1000[diff] [blame]136
137 .. versionadded:: 0.7
138
139 An enumeration for X.509 versions.
140
141 .. attribute:: v1
142
143 For version 1 X.509 certificates.
144
145 .. attribute:: v3
146
147 For version 3 X.509 certificates.
148
Paul Kehrere76cd272014-12-14 19:00:51 -0600[diff] [blame^]149.. class:: InvalidVersion
Paul Kehrera68fd332014-11-27 07:08:40 -1000[diff] [blame]150
151 This is raised when an X.509 certificate has an invalid version number.
Paul Kehrer016e08a2014-11-26 09:41:18 -1000[diff] [blame]152
153
154.. _`public key infrastructure`: https://en.wikipedia.org/wiki/Public_key_infrastructure
Paul Kehrera68fd332014-11-27 07:08:40 -1000[diff] [blame]155.. _`TLS`: https://en.wikipedia.org/wiki/Transport_Layer_Security