Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / python / pyopenssl / aa677147842bc766cf7aa51e62ffef39f6f7af82 / . / doc / api / crypto.rst
blob: 5cd7fd92a7b2dacb56ee662fa2f32fca6dbc391f [file] [log] [blame]
Jonathan Ballet6381da32011-07-20 16:43:38 +0900[diff] [blame]1.. _openssl-crypto:
2
3:py:mod:`crypto` --- Generic cryptographic module
4=================================================
5
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900[diff] [blame]6.. py:module:: OpenSSL.crypto
Jonathan Ballet6381da32011-07-20 16:43:38 +0900[diff] [blame]7 :synopsis: Generic cryptographic module
Jonathan Ballet648875f2011-07-16 14:14:58 +0900[diff] [blame]8
Paul Kehrerdc996b12017-07-19 21:09:04 +0200[diff] [blame]9.. note::
10
Hynek Schlawack81021282017-07-20 10:32:37 +0200[diff] [blame]11 `pyca/cryptography`_ is likely a better choice than using this module.
12 It contains a complete set of cryptographic primitives as well as a significantly better and more powerful X509 API.
13 If necessary you can convert to and from cryptography objects using the ``to_cryptography`` and ``from_cryptography`` methods on ``X509``, ``X509Req``, ``CRL``, and ``PKey``.
14
Paul Kehrerdc996b12017-07-19 21:09:04 +0200[diff] [blame]15
Laurens Van Houtven07051d32014-06-19 12:00:30 +0200[diff] [blame]16Elliptic curves
17---------------
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900[diff] [blame]18
Alex Chand072cae2018-02-15 09:57:59 +0000[diff] [blame]19.. autofunction:: get_elliptic_curves
Jean-Paul Calderonec09fd582014-04-18 22:00:10 -0400[diff] [blame]20
Alex Chand072cae2018-02-15 09:57:59 +0000[diff] [blame]21.. autofunction:: get_elliptic_curve
Jean-Paul Calderonec09fd582014-04-18 22:00:10 -0400[diff] [blame]22
Laurens Van Houtven07051d32014-06-19 12:00:30 +0200[diff] [blame]23Serialization and deserialization
24---------------------------------
25
Cory Benfield47569252016-02-07 10:28:00 +0000[diff] [blame]26The following serialization functions take one of these constants to determine the format.
Cory Benfield4d67d042016-01-22 18:42:13 +0000[diff] [blame]27
Laurens Van Houtven07051d32014-06-19 12:00:30 +0200[diff] [blame]28.. py:data:: FILETYPE_PEM
Cory Benfieldfb4d4fb2016-01-22 18:51:34 +0000[diff] [blame]29
Cory Benfield47569252016-02-07 10:28:00 +0000[diff] [blame]30:data:`FILETYPE_PEM` serializes data to a Base64-encoded encoded representation of the underlying ASN.1 data structure. This representation includes delimiters that define what data structure is contained within the Base64-encoded block: for example, for a certificate, the delimiters are ``-----BEGIN CERTIFICATE-----`` and ``-----END CERTIFICATE-----``.
Cory Benfieldfb4d4fb2016-01-22 18:51:34 +0000[diff] [blame]31
32.. py:data:: FILETYPE_ASN1
33
Cory Benfield47569252016-02-07 10:28:00 +0000[diff] [blame]34:data:`FILETYPE_ASN1` serializes data to the underlying ASN.1 data structure. The format used by :data:`FILETYPE_ASN1` is also sometimes referred to as DER.
Laurens Van Houtven07051d32014-06-19 12:00:30 +0200[diff] [blame]35
36Certificates
37~~~~~~~~~~~~
38
Alex Chand072cae2018-02-15 09:57:59 +0000[diff] [blame]39.. autofunction:: dump_certificate
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900[diff] [blame]40
Alex Chand072cae2018-02-15 09:57:59 +0000[diff] [blame]41.. autofunction:: load_certificate
Laurens Van Houtven07051d32014-06-19 12:00:30 +0200[diff] [blame]42
43Certificate signing requests
44~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900[diff] [blame]45
Alex Chand072cae2018-02-15 09:57:59 +0000[diff] [blame]46.. autofunction:: dump_certificate_request
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900[diff] [blame]47
Alex Chand072cae2018-02-15 09:57:59 +0000[diff] [blame]48.. autofunction:: load_certificate_request
Laurens Van Houtven07051d32014-06-19 12:00:30 +0200[diff] [blame]49
50Private keys
51~~~~~~~~~~~~
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900[diff] [blame]52
Hynek Schlawack11e43ad2016-07-03 14:40:20 +0200[diff] [blame]53.. autofunction:: dump_privatekey
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900[diff] [blame]54
Alex Chand072cae2018-02-15 09:57:59 +0000[diff] [blame]55.. autofunction:: load_privatekey
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900[diff] [blame]56
Cory Benfield25338c52015-10-28 22:19:18 +0900[diff] [blame]57Public keys
58~~~~~~~~~~~
59
60.. autofunction:: dump_publickey
61
62.. autofunction:: load_publickey
63
Laurens Van Houtven07051d32014-06-19 12:00:30 +0200[diff] [blame]64Certificate revocation lists
65~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900[diff] [blame]66
Dominic Chenf05b2122015-10-13 16:32:35 +0000[diff] [blame]67.. autofunction:: dump_crl
68
Alex Chand072cae2018-02-15 09:57:59 +0000[diff] [blame]69.. autofunction:: load_crl
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900[diff] [blame]70
Alex Chand072cae2018-02-15 09:57:59 +0000[diff] [blame]71.. autofunction:: load_pkcs7_data
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900[diff] [blame]72
Alex Chand072cae2018-02-15 09:57:59 +0000[diff] [blame]73.. autofunction:: load_pkcs12
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900[diff] [blame]74
Laurens Van Houtven07051d32014-06-19 12:00:30 +0200[diff] [blame]75Signing and verifying signatures
76--------------------------------
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900[diff] [blame]77
Alex Chand072cae2018-02-15 09:57:59 +0000[diff] [blame]78.. autofunction:: sign
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900[diff] [blame]79
Alex Chand072cae2018-02-15 09:57:59 +0000[diff] [blame]80.. autofunction:: verify
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900[diff] [blame]81
82
83.. _openssl-x509:
84
85X509 objects
86------------
87
Laurens Van Houtvenc3baa7b2014-06-18 22:06:56 +0200[diff] [blame]88.. autoclass:: X509
89 :members:
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900[diff] [blame]90
91.. _openssl-x509name:
92
93X509Name objects
94----------------
95
Laurens Van Houtven196195b2014-06-17 17:06:34 +0200[diff] [blame]96.. autoclass:: X509Name
97 :members:
98 :special-members:
99 :exclude-members: __repr__, __getattr__, __weakref__
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900[diff] [blame]100
101.. _openssl-x509req:
102
103X509Req objects
104---------------
105
Laurens Van Houtven3e83d242014-06-18 14:29:47 +0200[diff] [blame]106.. autoclass:: X509Req
107 :members:
108 :special-members:
109 :exclude-members: __weakref__
Jean-Paul Calderone26e07d62014-03-02 08:08:23 -0500[diff] [blame]110
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900[diff] [blame]111.. _openssl-x509store:
112
113X509Store objects
114-----------------
115
Laurens Van Houtven8aeafdd2014-06-17 15:33:42 +0200[diff] [blame]116.. autoclass:: X509Store
117 :members:
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900[diff] [blame]118
Stephen Holsapple8ad4a192015-06-09 22:51:43 -0700[diff] [blame]119.. _openssl-x509storecontexterror:
120
Stephen Holsapple95a46652015-02-09 19:34:25 -0800[diff] [blame]121X509StoreContextError objects
122-----------------------------
123
Stephen Holsapple8ad4a192015-06-09 22:51:43 -0700[diff] [blame]124.. autoclass:: X509StoreContextError
125 :members:
Stephen Holsapple95a46652015-02-09 19:34:25 -0800[diff] [blame]126
Stephen Holsapple8ad4a192015-06-09 22:51:43 -0700[diff] [blame]127.. _openssl-x509storecontext:
Stephen Holsapple95a46652015-02-09 19:34:25 -0800[diff] [blame]128
Stephen Holsapple08ffaa62015-01-30 17:18:40 -0800[diff] [blame]129X509StoreContext objects
130------------------------
131
Stephen Holsapple8ad4a192015-06-09 22:51:43 -0700[diff] [blame]132.. autoclass:: X509StoreContext
133 :members:
Stephen Holsapple08ffaa62015-01-30 17:18:40 -0800[diff] [blame]134
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900[diff] [blame]135.. _openssl-pkey:
136
Dan Sully44e767a2016-06-04 18:05:27 -0700[diff] [blame]137X509StoreFlags constants
138------------------------
139
140.. autoclass:: X509StoreFlags
141
142 .. data:: CRL_CHECK
143 .. data:: CRL_CHECK_ALL
144 .. data:: IGNORE_CRITICAL
145 .. data:: X509_STRICT
146 .. data:: ALLOW_PROXY_CERTS
147 .. data:: POLICY_CHECK
148 .. data:: EXPLICIT_POLICY
149 .. data:: INHIBIT_MAP
150 .. data:: NOTIFY_POLICY
151 .. data:: CHECK_SS_SIGNATURE
152 .. data:: CB_ISSUER_CHECK
153
154.. _openssl-x509storeflags:
155
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900[diff] [blame]156PKey objects
157------------
158
Laurens Van Houtven6e7dd432014-06-17 16:10:57 +0200[diff] [blame]159.. autoclass:: PKey
160 :members:
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900[diff] [blame]161
162.. _openssl-pkcs7:
163
Laurens Van Houtven9d4c0742015-04-20 11:58:39 -0700[diff] [blame]164.. py:data:: TYPE_RSA
165 TYPE_DSA
166
167 Key type constants.
168
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900[diff] [blame]169PKCS7 objects
170-------------
171
172PKCS7 objects have the following methods:
173
Alex Chand072cae2018-02-15 09:57:59 +0000[diff] [blame]174.. autoclass:: PKCS7
175 :members:
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900[diff] [blame]176
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900[diff] [blame]177.. _openssl-pkcs12:
178
179PKCS12 objects
180--------------
181
Laurens Van Houtvenbb503a32014-06-19 12:28:08 +0200[diff] [blame]182.. autoclass:: PKCS12
183 :members:
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900[diff] [blame]184
185.. _openssl-509ext:
186
187X509Extension objects
188---------------------
189
Laurens Van Houtven2650de52014-06-18 13:47:47 +0200[diff] [blame]190.. autoclass:: X509Extension
191 :members:
192 :special-members:
193 :exclude-members: __weakref__
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900[diff] [blame]194
195.. _openssl-netscape-spki:
196
197NetscapeSPKI objects
198--------------------
199
Laurens Van Houtven59152b52014-06-19 16:42:30 +0200[diff] [blame]200.. autoclass:: NetscapeSPKI
201 :members:
202 :special-members:
203 :exclude-members: __weakref__
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900[diff] [blame]204
Laurens Van Houtven889b9d22015-04-20 12:18:28 -0700[diff] [blame]205.. _crl:
206
207CRL objects
208-----------
209
210.. autoclass:: CRL
211 :members:
212 :special-members:
213 :exclude-members: __weakref__
214
215.. _revoked:
216
217Revoked objects
218---------------
219
220.. autoclass:: Revoked
221 :members:
222
Laurens Van Houtven3de6b2b2015-04-20 12:20:42 -0700[diff] [blame]223Exceptions
224----------
225
226.. py:exception:: Error
227
228 Generic exception used in the :py:mod:`.crypto` module.
229
Hynek Schlawack8d4f9762016-03-19 08:15:03 +0100[diff] [blame]230
Laurens Van Houtvenc3baa7b2014-06-18 22:06:56 +0200[diff] [blame]231Digest names
232------------
233
Hynek Schlawack8d4f9762016-03-19 08:15:03 +0100[diff] [blame]234Several of the functions and methods in this module take a digest name.
235These must be strings describing a digest algorithm supported by OpenSSL (by ``EVP_get_digestbyname``, specifically).
Alex Gaynor643aab82016-09-11 12:14:55 -0400[diff] [blame]236For example, :const:`b"sha256"` or :const:`b"sha384"`.
Laurens Van Houtvenc3baa7b2014-06-18 22:06:56 +0200[diff] [blame]237
Hynek Schlawack8d4f9762016-03-19 08:15:03 +0100[diff] [blame]238More information and a list of these digest names can be found in the ``EVP_DigestInit(3)`` man page of your OpenSSL installation.
239This page can be found online for the latest version of OpenSSL:
Alex Chan54005ce2017-03-21 08:08:17 +0000[diff] [blame]240https://www.openssl.org/docs/manmaster/man3/EVP_DigestInit.html
Hynek Schlawack8d4f9762016-03-19 08:15:03 +0100[diff] [blame]241
Paul Kehrerdc996b12017-07-19 21:09:04 +0200[diff] [blame]242.. _`pyca/cryptography`: https://cryptography.io