blob: 251019fe261c7f8bccaaac0302f0dc3eb6b920f2 [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
9
Stephen Holsapple0d9815f2014-08-27 19:36:53 -070010.. py:data:: X509StoreContext
11
12 A class representing the X.509 store context.
Jonathan Balletc9e066c2011-07-17 22:56:05 +090013
Jonathan Balletc9e066c2011-07-17 22:56:05 +090014.. py:exception:: Error
15
16 Generic exception used in the :py:mod:`.crypto` module.
17
Laurens Van Houtven07051d32014-06-19 12:00:30 +020018Elliptic curves
19---------------
Jonathan Balletc9e066c2011-07-17 22:56:05 +090020
Jean-Paul Calderonec09fd582014-04-18 22:00:10 -040021.. py:function:: get_elliptic_curves
22
23 Return a set of objects representing the elliptic curves supported in the
24 OpenSSL build in use.
25
26 The curve objects have a :py:class:`unicode` ``name`` attribute by which
Jean-Paul Calderoneaaf516d2014-04-19 09:10:45 -040027 they identify themselves.
Jean-Paul Calderonec09fd582014-04-18 22:00:10 -040028
29 The curve objects are useful as values for the argument accepted by
Jean-Paul Calderone3b04e352014-04-19 09:29:10 -040030 :py:meth:`Context.set_tmp_ecdh` to specify which elliptical curve should be
31 used for ECDHE key exchange.
Jean-Paul Calderonec09fd582014-04-18 22:00:10 -040032
33
34.. py:function:: get_elliptic_curve
35
36 Return a single curve object selected by name.
37
38 See :py:func:`get_elliptic_curves` for information about curve objects.
39
40 If the named curve is not supported then :py:class:`ValueError` is raised.
41
42
Laurens Van Houtven07051d32014-06-19 12:00:30 +020043Serialization and deserialization
44---------------------------------
45
46The following serialization functions take one of these constants to
47determine the format:
48
49.. py:data:: FILETYPE_PEM
50 FILETYPE_ASN1
51
52Certificates
53~~~~~~~~~~~~
54
Jonathan Balletc9e066c2011-07-17 22:56:05 +090055.. py:function:: dump_certificate(type, cert)
56
57 Dump the certificate *cert* into a buffer string encoded with the type
58 *type*.
59
Laurens Van Houtven07051d32014-06-19 12:00:30 +020060.. py:function:: load_certificate(type, buffer)
61
62 Load a certificate (X509) from the string *buffer* encoded with the
63 type *type*.
64
65Certificate signing requests
66~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Jonathan Balletc9e066c2011-07-17 22:56:05 +090067
68.. py:function:: dump_certificate_request(type, req)
69
70 Dump the certificate request *req* into a buffer string encoded with the
71 type *type*.
72
Laurens Van Houtven07051d32014-06-19 12:00:30 +020073.. py:function:: load_certificate_request(type, buffer)
74
75 Load a certificate request (X509Req) from the string *buffer* encoded with
76 the type *type*.
77
78Private keys
79~~~~~~~~~~~~
Jonathan Balletc9e066c2011-07-17 22:56:05 +090080
81.. py:function:: dump_privatekey(type, pkey[, cipher, passphrase])
82
83 Dump the private key *pkey* into a buffer string encoded with the type
84 *type*, optionally (if *type* is :py:const:`FILETYPE_PEM`) encrypting it
85 using *cipher* and *passphrase*.
86
87 *passphrase* must be either a string or a callback for providing the
88 pass phrase.
89
Jonathan Balletc9e066c2011-07-17 22:56:05 +090090.. py:function:: load_privatekey(type, buffer[, passphrase])
91
92 Load a private key (PKey) from the string *buffer* encoded with the type
93 *type* (must be one of :py:const:`FILETYPE_PEM` and
94 :py:const:`FILETYPE_ASN1`).
95
96 *passphrase* must be either a string or a callback for providing the pass
97 phrase.
98
Laurens Van Houtven07051d32014-06-19 12:00:30 +020099Certificate revocation lists
100~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900101
102.. py:function:: load_crl(type, buffer)
103
104 Load Certificate Revocation List (CRL) data from a string *buffer*.
105 *buffer* encoded with the type *type*. The type *type* must either
106 :py:const:`FILETYPE_PEM` or :py:const:`FILETYPE_ASN1`).
107
108
109.. py:function:: load_pkcs7_data(type, buffer)
110
Laurens Van Houtven0f820872015-04-20 11:25:57 -0700111 Load pkcs7 data from the string *buffer* encoded with the type
112 *type*. The type *type* must either :py:const:`FILETYPE_PEM` or
113 :py:const:`FILETYPE_ASN1`).
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900114
115
116.. py:function:: load_pkcs12(buffer[, passphrase])
117
118 Load pkcs12 data from the string *buffer*. If the pkcs12 structure is
119 encrypted, a *passphrase* must be included. The MAC is always
120 checked and thus required.
121
122 See also the man page for the C function :py:func:`PKCS12_parse`.
123
Laurens Van Houtven287abd12015-04-20 12:17:35 -0700124
125.. _crl:
126
127
128.. autoclass:: CRL
129 :members:
130 :special-members:
131 :exclude-members: __weakref__
132
133
134.. _revoked:
135
136
137.. autoclass:: Revoked
138 :members:
139
140
Laurens Van Houtven07051d32014-06-19 12:00:30 +0200141Signing and verifying signatures
142--------------------------------
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900143
144.. py:function:: sign(key, data, digest)
145
146 Sign a data string using the given key and message digest.
147
148 *key* is a :py:class:`PKey` instance. *data* is a ``str`` instance.
149 *digest* is a ``str`` naming a supported message digest type, for example
150 :py:const:`sha1`.
151
152 .. versionadded:: 0.11
153
154
155.. py:function:: verify(certificate, signature, data, digest)
156
157 Verify the signature for a data string.
158
159 *certificate* is a :py:class:`X509` instance corresponding to the private
160 key which generated the signature. *signature* is a *str* instance giving
161 the signature itself. *data* is a *str* instance giving the data to which
162 the signature applies. *digest* is a *str* instance naming the message
163 digest type of the signature, for example :py:const:`sha1`.
164
165 .. versionadded:: 0.11
166
167
168.. _openssl-x509:
169
170X509 objects
171------------
172
Laurens Van Houtvenc3baa7b2014-06-18 22:06:56 +0200173.. autoclass:: X509
174 :members:
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900175
176.. _openssl-x509name:
177
178X509Name objects
179----------------
180
Laurens Van Houtven196195b2014-06-17 17:06:34 +0200181.. autoclass:: X509Name
182 :members:
183 :special-members:
184 :exclude-members: __repr__, __getattr__, __weakref__
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900185
186.. _openssl-x509req:
187
188X509Req objects
189---------------
190
Laurens Van Houtven3e83d242014-06-18 14:29:47 +0200191.. autoclass:: X509Req
192 :members:
193 :special-members:
194 :exclude-members: __weakref__
Jean-Paul Calderone26e07d62014-03-02 08:08:23 -0500195
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900196.. _openssl-x509store:
197
198X509Store objects
199-----------------
200
Laurens Van Houtven8aeafdd2014-06-17 15:33:42 +0200201.. autoclass:: X509Store
202 :members:
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900203
Stephen Holsapple95a46652015-02-09 19:34:25 -0800204X509StoreContextError objects
205-----------------------------
206
207The X509StoreContextError is an exception raised from
208`X509StoreContext.verify_certificate` in circumstances where a certificate
209cannot be verified in a provided context.
210
Jean-Paul Calderone876b2ac2015-03-15 16:17:19 -0400211The certificate for which the verification error was detected is given by the
212``certificate`` attribute of the exception instance as a :class:`X509`
213instance.
214
Laurens Van Houtven9313a4e2015-04-20 11:27:28 -0700215Details about the verification error are given in the exception's
216``args`` attribute.
Stephen Holsapple95a46652015-02-09 19:34:25 -0800217
Stephen Holsapple08ffaa62015-01-30 17:18:40 -0800218X509StoreContext objects
219------------------------
220
221The X509StoreContext object is used for verifying a certificate against a set
222of trusted certificates.
223
224
225.. py:method:: X509StoreContext.verify_certificate()
226
227 Verify a certificate in the context of this initialized `X509StoreContext`.
228 On error, raises `X509StoreContextError`, otherwise does nothing.
229
230 .. versionadded:: 0.15
231
232
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900233.. _openssl-pkey:
234
235PKey objects
236------------
237
Laurens Van Houtven6e7dd432014-06-17 16:10:57 +0200238.. autoclass:: PKey
239 :members:
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900240
241.. _openssl-pkcs7:
242
Laurens Van Houtven9d4c0742015-04-20 11:58:39 -0700243.. py:data:: TYPE_RSA
244 TYPE_DSA
245
246 Key type constants.
247
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900248PKCS7 objects
249-------------
250
251PKCS7 objects have the following methods:
252
Jonathan Ballet6381da32011-07-20 16:43:38 +0900253.. py:method:: PKCS7.type_is_signed()
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900254
255 FIXME
256
Jonathan Ballet6381da32011-07-20 16:43:38 +0900257.. py:method:: PKCS7.type_is_enveloped()
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900258
259 FIXME
260
Jonathan Ballet6381da32011-07-20 16:43:38 +0900261.. py:method:: PKCS7.type_is_signedAndEnveloped()
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900262
263 FIXME
264
Jonathan Ballet6381da32011-07-20 16:43:38 +0900265.. py:method:: PKCS7.type_is_data()
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900266
267 FIXME
268
Jonathan Ballet6381da32011-07-20 16:43:38 +0900269.. py:method:: PKCS7.get_type_name()
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900270
271 Get the type name of the PKCS7.
272
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900273.. _openssl-pkcs12:
274
275PKCS12 objects
276--------------
277
Laurens Van Houtvenbb503a32014-06-19 12:28:08 +0200278.. autoclass:: PKCS12
279 :members:
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900280
281.. _openssl-509ext:
282
283X509Extension objects
284---------------------
285
Laurens Van Houtven2650de52014-06-18 13:47:47 +0200286.. autoclass:: X509Extension
287 :members:
288 :special-members:
289 :exclude-members: __weakref__
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900290
291.. _openssl-netscape-spki:
292
293NetscapeSPKI objects
294--------------------
295
Laurens Van Houtven59152b52014-06-19 16:42:30 +0200296.. autoclass:: NetscapeSPKI
297 :members:
298 :special-members:
299 :exclude-members: __weakref__
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900300
Laurens Van Houtvenc3baa7b2014-06-18 22:06:56 +0200301Digest names
302------------
303
304Several of the functions and methods in this module take a digest
305name. These must be strings describing a digest algorithm supported by
306OpenSSL (by ``EVP_get_digestbyname``, specifically). For example,
307:py:const:`b"md5"` or :py:const:`b"sha1"`.
308
309More information and a list of these digest names can be found in the
310``EVP_DigestInit(3)`` man page of your OpenSSL installation. This page
311can be found online for the latest version of OpenSSL:
312https://www.openssl.org/docs/crypto/EVP_DigestInit.html
313
Laurens Van Houtven13d56ba2014-06-17 16:00:26 +0200314Backwards compatible type names
315-------------------------------
316
317When PyOpenSSL was originally written, the most current version of
318Python was 2.1. It made a distinction between classes and types. None
319of the versions of Python currently supported by PyOpenSSL still
320enforce that distinction: the type of an instance of an
321:py:class:`X509` object is now simply :py:class:`X509`. Originally,
322the type would have been :py:class:`X509Type`. These days,
323:py:class:`X509Type` and :py:class:`X509` are literally the same
324object. PyOpenSSL maintains these old names for backwards
325compatibility.
326
327Here's a table of these backwards-compatible names:
328
329========================= =============================
330Type name Backwards-compatible name
331========================= =============================
332:py:class:`X509` :py:class:`X509Type`
333:py:class:`X509Name` :py:class:`X509NameType`
334:py:class:`X509Req` :py:class:`X509ReqType`
335:py:class:`X509Store` :py:class:`X509StoreType`
336:py:class:`X509Extension` :py:class:`X509ExtensionType`
337:py:class:`PKey` :py:class:`PKeyType`
338:py:class:`PKCS7` :py:class:`PKCS7Type`
339:py:class:`PKCS12` :py:class:`PKCS12Type`
340:py:class:`NetscapeSPKI` :py:class:`NetscapeSPKIType`
341:py:class:`CRL` :py:class:`CRLType`
342========================= =============================
343
Laurens Van Houtven2ec1fba2015-04-20 11:48:12 -0700344Some objects, such as py:class`Revoked`, don't have ``Type``
Laurens Van Houtven13d56ba2014-06-17 16:00:26 +0200345equivalents, because they were added after the restriction had been
346lifted.