blob: 8a31da5a7706e44019a9ee17f971d398a898d5f5 [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 Houtven07051d32014-06-19 12:00:30 +0200124Signing and verifying signatures
125--------------------------------
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900126
127.. py:function:: sign(key, data, digest)
128
129 Sign a data string using the given key and message digest.
130
131 *key* is a :py:class:`PKey` instance. *data* is a ``str`` instance.
132 *digest* is a ``str`` naming a supported message digest type, for example
133 :py:const:`sha1`.
134
135 .. versionadded:: 0.11
136
137
138.. py:function:: verify(certificate, signature, data, digest)
139
140 Verify the signature for a data string.
141
142 *certificate* is a :py:class:`X509` instance corresponding to the private
143 key which generated the signature. *signature* is a *str* instance giving
144 the signature itself. *data* is a *str* instance giving the data to which
145 the signature applies. *digest* is a *str* instance naming the message
146 digest type of the signature, for example :py:const:`sha1`.
147
148 .. versionadded:: 0.11
149
150
151.. _openssl-x509:
152
153X509 objects
154------------
155
Laurens Van Houtvenc3baa7b2014-06-18 22:06:56 +0200156.. autoclass:: X509
157 :members:
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900158
159.. _openssl-x509name:
160
161X509Name objects
162----------------
163
Laurens Van Houtven196195b2014-06-17 17:06:34 +0200164.. autoclass:: X509Name
165 :members:
166 :special-members:
167 :exclude-members: __repr__, __getattr__, __weakref__
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900168
169.. _openssl-x509req:
170
171X509Req objects
172---------------
173
Laurens Van Houtven3e83d242014-06-18 14:29:47 +0200174.. autoclass:: X509Req
175 :members:
176 :special-members:
177 :exclude-members: __weakref__
Jean-Paul Calderone26e07d62014-03-02 08:08:23 -0500178
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900179.. _openssl-x509store:
180
181X509Store objects
182-----------------
183
Laurens Van Houtven8aeafdd2014-06-17 15:33:42 +0200184.. autoclass:: X509Store
185 :members:
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900186
Stephen Holsapple95a46652015-02-09 19:34:25 -0800187X509StoreContextError objects
188-----------------------------
189
190The X509StoreContextError is an exception raised from
191`X509StoreContext.verify_certificate` in circumstances where a certificate
192cannot be verified in a provided context.
193
Jean-Paul Calderone876b2ac2015-03-15 16:17:19 -0400194The certificate for which the verification error was detected is given by the
195``certificate`` attribute of the exception instance as a :class:`X509`
196instance.
197
Laurens Van Houtven9313a4e2015-04-20 11:27:28 -0700198Details about the verification error are given in the exception's
199``args`` attribute.
Stephen Holsapple95a46652015-02-09 19:34:25 -0800200
Stephen Holsapple08ffaa62015-01-30 17:18:40 -0800201X509StoreContext objects
202------------------------
203
204The X509StoreContext object is used for verifying a certificate against a set
205of trusted certificates.
206
207
208.. py:method:: X509StoreContext.verify_certificate()
209
210 Verify a certificate in the context of this initialized `X509StoreContext`.
211 On error, raises `X509StoreContextError`, otherwise does nothing.
212
213 .. versionadded:: 0.15
214
215
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900216.. _openssl-pkey:
217
218PKey objects
219------------
220
Laurens Van Houtven6e7dd432014-06-17 16:10:57 +0200221.. autoclass:: PKey
222 :members:
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900223
224.. _openssl-pkcs7:
225
Laurens Van Houtven9d4c0742015-04-20 11:58:39 -0700226.. py:data:: TYPE_RSA
227 TYPE_DSA
228
229 Key type constants.
230
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900231PKCS7 objects
232-------------
233
234PKCS7 objects have the following methods:
235
Jonathan Ballet6381da32011-07-20 16:43:38 +0900236.. py:method:: PKCS7.type_is_signed()
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900237
238 FIXME
239
Jonathan Ballet6381da32011-07-20 16:43:38 +0900240.. py:method:: PKCS7.type_is_enveloped()
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900241
242 FIXME
243
Jonathan Ballet6381da32011-07-20 16:43:38 +0900244.. py:method:: PKCS7.type_is_signedAndEnveloped()
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900245
246 FIXME
247
Jonathan Ballet6381da32011-07-20 16:43:38 +0900248.. py:method:: PKCS7.type_is_data()
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900249
250 FIXME
251
Jonathan Ballet6381da32011-07-20 16:43:38 +0900252.. py:method:: PKCS7.get_type_name()
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900253
254 Get the type name of the PKCS7.
255
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900256.. _openssl-pkcs12:
257
258PKCS12 objects
259--------------
260
Laurens Van Houtvenbb503a32014-06-19 12:28:08 +0200261.. autoclass:: PKCS12
262 :members:
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900263
264.. _openssl-509ext:
265
266X509Extension objects
267---------------------
268
Laurens Van Houtven2650de52014-06-18 13:47:47 +0200269.. autoclass:: X509Extension
270 :members:
271 :special-members:
272 :exclude-members: __weakref__
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900273
274.. _openssl-netscape-spki:
275
276NetscapeSPKI objects
277--------------------
278
Laurens Van Houtven59152b52014-06-19 16:42:30 +0200279.. autoclass:: NetscapeSPKI
280 :members:
281 :special-members:
282 :exclude-members: __weakref__
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900283
Laurens Van Houtven889b9d22015-04-20 12:18:28 -0700284.. _crl:
285
286CRL objects
287-----------
288
289.. autoclass:: CRL
290 :members:
291 :special-members:
292 :exclude-members: __weakref__
293
294.. _revoked:
295
296Revoked objects
297---------------
298
299.. autoclass:: Revoked
300 :members:
301
Laurens Van Houtvenc3baa7b2014-06-18 22:06:56 +0200302Digest names
303------------
304
305Several of the functions and methods in this module take a digest
306name. These must be strings describing a digest algorithm supported by
307OpenSSL (by ``EVP_get_digestbyname``, specifically). For example,
308:py:const:`b"md5"` or :py:const:`b"sha1"`.
309
310More information and a list of these digest names can be found in the
311``EVP_DigestInit(3)`` man page of your OpenSSL installation. This page
312can be found online for the latest version of OpenSSL:
313https://www.openssl.org/docs/crypto/EVP_DigestInit.html
314
Laurens Van Houtven13d56ba2014-06-17 16:00:26 +0200315Backwards compatible type names
316-------------------------------
317
318When PyOpenSSL was originally written, the most current version of
319Python was 2.1. It made a distinction between classes and types. None
320of the versions of Python currently supported by PyOpenSSL still
321enforce that distinction: the type of an instance of an
322:py:class:`X509` object is now simply :py:class:`X509`. Originally,
323the type would have been :py:class:`X509Type`. These days,
324:py:class:`X509Type` and :py:class:`X509` are literally the same
325object. PyOpenSSL maintains these old names for backwards
326compatibility.
327
328Here's a table of these backwards-compatible names:
329
330========================= =============================
331Type name Backwards-compatible name
332========================= =============================
333:py:class:`X509` :py:class:`X509Type`
334:py:class:`X509Name` :py:class:`X509NameType`
335:py:class:`X509Req` :py:class:`X509ReqType`
336:py:class:`X509Store` :py:class:`X509StoreType`
337:py:class:`X509Extension` :py:class:`X509ExtensionType`
338:py:class:`PKey` :py:class:`PKeyType`
339:py:class:`PKCS7` :py:class:`PKCS7Type`
340:py:class:`PKCS12` :py:class:`PKCS12Type`
341:py:class:`NetscapeSPKI` :py:class:`NetscapeSPKIType`
342:py:class:`CRL` :py:class:`CRLType`
343========================= =============================
344
Laurens Van Houtven2ec1fba2015-04-20 11:48:12 -0700345Some objects, such as py:class`Revoked`, don't have ``Type``
Laurens Van Houtven13d56ba2014-06-17 16:00:26 +0200346equivalents, because they were added after the restriction had been
347lifted.