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