blob: 95fb4df80519533f428579b7e616d4adc9a12d5d [file] [log] [blame]
Jonathan Ballet6381da32011-07-20 16:43:38 +09001.. _openssl-crypto:
2
3:py:mod:`crypto` --- Generic cryptographic module
4=================================================
5
Jonathan Balletc9e066c2011-07-17 22:56:05 +09006.. py:module:: OpenSSL.crypto
Jonathan Ballet6381da32011-07-20 16:43:38 +09007 :synopsis: Generic cryptographic module
Jonathan Ballet648875f2011-07-16 14:14:58 +09008
Laurens Van Houtven07051d32014-06-19 12:00:30 +02009Elliptic curves
10---------------
Jonathan Balletc9e066c2011-07-17 22:56:05 +090011
Jean-Paul Calderonec09fd582014-04-18 22:00:10 -040012.. py:function:: get_elliptic_curves
13
14 Return a set of objects representing the elliptic curves supported in the
15 OpenSSL build in use.
16
17 The curve objects have a :py:class:`unicode` ``name`` attribute by which
Jean-Paul Calderoneaaf516d2014-04-19 09:10:45 -040018 they identify themselves.
Jean-Paul Calderonec09fd582014-04-18 22:00:10 -040019
20 The curve objects are useful as values for the argument accepted by
Jean-Paul Calderone3b04e352014-04-19 09:29:10 -040021 :py:meth:`Context.set_tmp_ecdh` to specify which elliptical curve should be
22 used for ECDHE key exchange.
Jean-Paul Calderonec09fd582014-04-18 22:00:10 -040023
24
Akihiro Yamazakib8450442015-09-04 16:55:04 +090025.. py:function:: get_elliptic_curve(name)
Jean-Paul Calderonec09fd582014-04-18 22:00:10 -040026
Alex Gaynorb6e92df2015-09-04 07:48:35 -040027 Return a single curve object selected by *name*.
Jean-Paul Calderonec09fd582014-04-18 22:00:10 -040028
29 See :py:func:`get_elliptic_curves` for information about curve objects.
30
31 If the named curve is not supported then :py:class:`ValueError` is raised.
32
33
Laurens Van Houtven07051d32014-06-19 12:00:30 +020034Serialization and deserialization
35---------------------------------
36
37The following serialization functions take one of these constants to
38determine the format:
39
40.. py:data:: FILETYPE_PEM
41 FILETYPE_ASN1
42
43Certificates
44~~~~~~~~~~~~
45
Jonathan Balletc9e066c2011-07-17 22:56:05 +090046.. py:function:: dump_certificate(type, cert)
47
48 Dump the certificate *cert* into a buffer string encoded with the type
49 *type*.
50
Laurens Van Houtven07051d32014-06-19 12:00:30 +020051.. py:function:: load_certificate(type, buffer)
52
53 Load a certificate (X509) from the string *buffer* encoded with the
54 type *type*.
55
56Certificate signing requests
57~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Jonathan Balletc9e066c2011-07-17 22:56:05 +090058
59.. py:function:: dump_certificate_request(type, req)
60
61 Dump the certificate request *req* into a buffer string encoded with the
62 type *type*.
63
Laurens Van Houtven07051d32014-06-19 12:00:30 +020064.. py:function:: load_certificate_request(type, buffer)
65
66 Load a certificate request (X509Req) from the string *buffer* encoded with
67 the type *type*.
68
69Private keys
70~~~~~~~~~~~~
Jonathan Balletc9e066c2011-07-17 22:56:05 +090071
72.. py:function:: dump_privatekey(type, pkey[, cipher, passphrase])
73
74 Dump the private key *pkey* into a buffer string encoded with the type
75 *type*, optionally (if *type* is :py:const:`FILETYPE_PEM`) encrypting it
76 using *cipher* and *passphrase*.
77
78 *passphrase* must be either a string or a callback for providing the
79 pass phrase.
80
Jonathan Balletc9e066c2011-07-17 22:56:05 +090081.. py:function:: load_privatekey(type, buffer[, passphrase])
82
83 Load a private key (PKey) from the string *buffer* encoded with the type
84 *type* (must be one of :py:const:`FILETYPE_PEM` and
85 :py:const:`FILETYPE_ASN1`).
86
87 *passphrase* must be either a string or a callback for providing the pass
88 phrase.
89
Laurens Van Houtven07051d32014-06-19 12:00:30 +020090Certificate revocation lists
91~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Jonathan Balletc9e066c2011-07-17 22:56:05 +090092
Dominic Chenf05b2122015-10-13 16:32:35 +000093.. autofunction:: dump_crl
94
Jonathan Balletc9e066c2011-07-17 22:56:05 +090095.. py:function:: load_crl(type, buffer)
96
97 Load Certificate Revocation List (CRL) data from a string *buffer*.
98 *buffer* encoded with the type *type*. The type *type* must either
99 :py:const:`FILETYPE_PEM` or :py:const:`FILETYPE_ASN1`).
100
101
102.. py:function:: load_pkcs7_data(type, buffer)
103
Laurens Van Houtven0f820872015-04-20 11:25:57 -0700104 Load pkcs7 data from the string *buffer* encoded with the type
105 *type*. The type *type* must either :py:const:`FILETYPE_PEM` or
106 :py:const:`FILETYPE_ASN1`).
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900107
108
109.. py:function:: load_pkcs12(buffer[, passphrase])
110
111 Load pkcs12 data from the string *buffer*. If the pkcs12 structure is
112 encrypted, a *passphrase* must be included. The MAC is always
113 checked and thus required.
114
115 See also the man page for the C function :py:func:`PKCS12_parse`.
116
Laurens Van Houtven07051d32014-06-19 12:00:30 +0200117Signing and verifying signatures
118--------------------------------
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900119
120.. py:function:: sign(key, data, digest)
121
122 Sign a data string using the given key and message digest.
123
124 *key* is a :py:class:`PKey` instance. *data* is a ``str`` instance.
125 *digest* is a ``str`` naming a supported message digest type, for example
126 :py:const:`sha1`.
127
128 .. versionadded:: 0.11
129
130
131.. py:function:: verify(certificate, signature, data, digest)
132
133 Verify the signature for a data string.
134
135 *certificate* is a :py:class:`X509` instance corresponding to the private
136 key which generated the signature. *signature* is a *str* instance giving
137 the signature itself. *data* is a *str* instance giving the data to which
138 the signature applies. *digest* is a *str* instance naming the message
139 digest type of the signature, for example :py:const:`sha1`.
140
141 .. versionadded:: 0.11
142
143
144.. _openssl-x509:
145
146X509 objects
147------------
148
Laurens Van Houtvenc3baa7b2014-06-18 22:06:56 +0200149.. autoclass:: X509
150 :members:
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900151
152.. _openssl-x509name:
153
154X509Name objects
155----------------
156
Laurens Van Houtven196195b2014-06-17 17:06:34 +0200157.. autoclass:: X509Name
158 :members:
159 :special-members:
160 :exclude-members: __repr__, __getattr__, __weakref__
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900161
162.. _openssl-x509req:
163
164X509Req objects
165---------------
166
Laurens Van Houtven3e83d242014-06-18 14:29:47 +0200167.. autoclass:: X509Req
168 :members:
169 :special-members:
170 :exclude-members: __weakref__
Jean-Paul Calderone26e07d62014-03-02 08:08:23 -0500171
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900172.. _openssl-x509store:
173
174X509Store objects
175-----------------
176
Laurens Van Houtven8aeafdd2014-06-17 15:33:42 +0200177.. autoclass:: X509Store
178 :members:
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900179
Stephen Holsapple8ad4a192015-06-09 22:51:43 -0700180.. _openssl-x509storecontexterror:
181
Stephen Holsapple95a46652015-02-09 19:34:25 -0800182X509StoreContextError objects
183-----------------------------
184
Stephen Holsapple8ad4a192015-06-09 22:51:43 -0700185.. autoclass:: X509StoreContextError
186 :members:
Stephen Holsapple95a46652015-02-09 19:34:25 -0800187
Stephen Holsapple8ad4a192015-06-09 22:51:43 -0700188.. _openssl-x509storecontext:
Stephen Holsapple95a46652015-02-09 19:34:25 -0800189
Stephen Holsapple08ffaa62015-01-30 17:18:40 -0800190X509StoreContext objects
191------------------------
192
Stephen Holsapple8ad4a192015-06-09 22:51:43 -0700193.. autoclass:: X509StoreContext
194 :members:
Stephen Holsapple08ffaa62015-01-30 17:18:40 -0800195
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900196.. _openssl-pkey:
197
198PKey objects
199------------
200
Laurens Van Houtven6e7dd432014-06-17 16:10:57 +0200201.. autoclass:: PKey
202 :members:
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900203
204.. _openssl-pkcs7:
205
Laurens Van Houtven9d4c0742015-04-20 11:58:39 -0700206.. py:data:: TYPE_RSA
207 TYPE_DSA
208
209 Key type constants.
210
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900211PKCS7 objects
212-------------
213
214PKCS7 objects have the following methods:
215
Jonathan Ballet6381da32011-07-20 16:43:38 +0900216.. py:method:: PKCS7.type_is_signed()
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900217
218 FIXME
219
Jonathan Ballet6381da32011-07-20 16:43:38 +0900220.. py:method:: PKCS7.type_is_enveloped()
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900221
222 FIXME
223
Jonathan Ballet6381da32011-07-20 16:43:38 +0900224.. py:method:: PKCS7.type_is_signedAndEnveloped()
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900225
226 FIXME
227
Jonathan Ballet6381da32011-07-20 16:43:38 +0900228.. py:method:: PKCS7.type_is_data()
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900229
230 FIXME
231
Jonathan Ballet6381da32011-07-20 16:43:38 +0900232.. py:method:: PKCS7.get_type_name()
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900233
234 Get the type name of the PKCS7.
235
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900236.. _openssl-pkcs12:
237
238PKCS12 objects
239--------------
240
Laurens Van Houtvenbb503a32014-06-19 12:28:08 +0200241.. autoclass:: PKCS12
242 :members:
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900243
244.. _openssl-509ext:
245
246X509Extension objects
247---------------------
248
Laurens Van Houtven2650de52014-06-18 13:47:47 +0200249.. autoclass:: X509Extension
250 :members:
251 :special-members:
252 :exclude-members: __weakref__
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900253
254.. _openssl-netscape-spki:
255
256NetscapeSPKI objects
257--------------------
258
Laurens Van Houtven59152b52014-06-19 16:42:30 +0200259.. autoclass:: NetscapeSPKI
260 :members:
261 :special-members:
262 :exclude-members: __weakref__
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900263
Laurens Van Houtven889b9d22015-04-20 12:18:28 -0700264.. _crl:
265
266CRL objects
267-----------
268
269.. autoclass:: CRL
270 :members:
271 :special-members:
272 :exclude-members: __weakref__
273
274.. _revoked:
275
276Revoked objects
277---------------
278
279.. autoclass:: Revoked
280 :members:
281
Laurens Van Houtven3de6b2b2015-04-20 12:20:42 -0700282Exceptions
283----------
284
285.. py:exception:: Error
286
287 Generic exception used in the :py:mod:`.crypto` module.
288
Laurens Van Houtvenc3baa7b2014-06-18 22:06:56 +0200289Digest names
290------------
291
292Several of the functions and methods in this module take a digest
293name. These must be strings describing a digest algorithm supported by
294OpenSSL (by ``EVP_get_digestbyname``, specifically). For example,
295:py:const:`b"md5"` or :py:const:`b"sha1"`.
296
297More information and a list of these digest names can be found in the
298``EVP_DigestInit(3)`` man page of your OpenSSL installation. This page
299can be found online for the latest version of OpenSSL:
300https://www.openssl.org/docs/crypto/EVP_DigestInit.html
301
Laurens Van Houtven13d56ba2014-06-17 16:00:26 +0200302Backwards compatible type names
303-------------------------------
304
305When PyOpenSSL was originally written, the most current version of
306Python was 2.1. It made a distinction between classes and types. None
307of the versions of Python currently supported by PyOpenSSL still
308enforce that distinction: the type of an instance of an
309:py:class:`X509` object is now simply :py:class:`X509`. Originally,
310the type would have been :py:class:`X509Type`. These days,
311:py:class:`X509Type` and :py:class:`X509` are literally the same
312object. PyOpenSSL maintains these old names for backwards
313compatibility.
314
315Here's a table of these backwards-compatible names:
316
317========================= =============================
318Type name Backwards-compatible name
319========================= =============================
320:py:class:`X509` :py:class:`X509Type`
321:py:class:`X509Name` :py:class:`X509NameType`
322:py:class:`X509Req` :py:class:`X509ReqType`
323:py:class:`X509Store` :py:class:`X509StoreType`
324:py:class:`X509Extension` :py:class:`X509ExtensionType`
325:py:class:`PKey` :py:class:`PKeyType`
326:py:class:`PKCS7` :py:class:`PKCS7Type`
327:py:class:`PKCS12` :py:class:`PKCS12Type`
328:py:class:`NetscapeSPKI` :py:class:`NetscapeSPKIType`
329:py:class:`CRL` :py:class:`CRLType`
330========================= =============================
331
Laurens Van Houtven5faa2812015-04-23 10:44:10 -0700332Some objects, such as :py:class`Revoked`, don't have ``Type``
Laurens Van Houtven13d56ba2014-06-17 16:00:26 +0200333equivalents, because they were added after the restriction had been
334lifted.