blob: 43860eae5e50da883d031542d5011b0b25b135c9 [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
Jonathan Balletc9e066c2011-07-17 22:56:05 +090010.. py:data:: X509Type
Jonathan Ballet648875f2011-07-16 14:14:58 +090011
Jonathan Balletc9e066c2011-07-17 22:56:05 +090012 See :py:class:`X509`.
Jonathan Ballet648875f2011-07-16 14:14:58 +090013
14
Jonathan Balletc9e066c2011-07-17 22:56:05 +090015.. py:class:: X509()
16
17 A class representing X.509 certificates.
18
19
20.. py:data:: X509NameType
21
22 See :py:class:`X509Name`.
23
24
25.. py:class:: X509Name(x509name)
26
27 A class representing X.509 Distinguished Names.
28
29 This constructor creates a copy of *x509name* which should be an
30 instance of :py:class:`X509Name`.
31
32
33.. py:data:: X509ReqType
34
35 See :py:class:`X509Req`.
36
37
38.. py:class:: X509Req()
39
40 A class representing X.509 certificate requests.
41
42
43.. py:data:: X509StoreType
44
Stephen Holsapple0d9815f2014-08-27 19:36:53 -070045 See :py:class:`X509Store`
46
47
Laurens Van Houtven0c26a462015-04-20 11:00:08 -070048.. py:data:: X509Store
Stephen Holsapple0d9815f2014-08-27 19:36:53 -070049
50 A class representing the X.509 store.
51
52
53.. py:data:: X509StoreContext
54
55 A class representing the X.509 store context.
Jonathan Balletc9e066c2011-07-17 22:56:05 +090056
57
58.. py:data:: PKeyType
59
60 See :py:class:`PKey`.
61
62
63.. py:class:: PKey()
64
65 A class representing DSA or RSA keys.
66
Jonathan Balletc9e066c2011-07-17 22:56:05 +090067.. py:data:: PKCS7Type
68
69 A Python type object representing the PKCS7 object type.
70
71
72.. py:data:: PKCS12Type
73
74 A Python type object representing the PKCS12 object type.
75
76
77.. py:data:: X509ExtensionType
78
79 See :py:class:`X509Extension`.
80
81
82.. py:class:: X509Extension(typename, critical, value[, subject][, issuer])
83
84 A class representing an X.509 v3 certificate extensions. See
85 http://openssl.org/docs/apps/x509v3_config.html#STANDARD_EXTENSIONS for
86 *typename* strings and their options. Optional parameters *subject* and
87 *issuer* must be X509 objects.
88
89
90.. py:data:: NetscapeSPKIType
91
92 See :py:class:`NetscapeSPKI`.
93
94
95.. py:class:: NetscapeSPKI([enc])
96
97 A class representing Netscape SPKI objects.
98
99 If the *enc* argument is present, it should be a base64-encoded string
100 representing a NetscapeSPKI object, as returned by the :py:meth:`b64_encode`
101 method.
102
103
104.. py:class:: CRL()
105
106 A class representing Certifcate Revocation List objects.
107
108
109.. py:class:: Revoked()
110
111 A class representing Revocation objects of CRL.
112
113
114.. py:data:: FILETYPE_PEM
Jonathan Ballet6381da32011-07-20 16:43:38 +0900115 FILETYPE_ASN1
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900116
117 File type constants.
118
119
120.. py:data:: TYPE_RSA
Jonathan Ballet6381da32011-07-20 16:43:38 +0900121 TYPE_DSA
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900122
123 Key type constants.
124
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900125.. py:exception:: Error
126
127 Generic exception used in the :py:mod:`.crypto` module.
128
Laurens Van Houtven07051d32014-06-19 12:00:30 +0200129Elliptic curves
130---------------
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900131
Jean-Paul Calderonec09fd582014-04-18 22:00:10 -0400132.. py:function:: get_elliptic_curves
133
134 Return a set of objects representing the elliptic curves supported in the
135 OpenSSL build in use.
136
137 The curve objects have a :py:class:`unicode` ``name`` attribute by which
Jean-Paul Calderoneaaf516d2014-04-19 09:10:45 -0400138 they identify themselves.
Jean-Paul Calderonec09fd582014-04-18 22:00:10 -0400139
140 The curve objects are useful as values for the argument accepted by
Jean-Paul Calderone3b04e352014-04-19 09:29:10 -0400141 :py:meth:`Context.set_tmp_ecdh` to specify which elliptical curve should be
142 used for ECDHE key exchange.
Jean-Paul Calderonec09fd582014-04-18 22:00:10 -0400143
144
145.. py:function:: get_elliptic_curve
146
147 Return a single curve object selected by name.
148
149 See :py:func:`get_elliptic_curves` for information about curve objects.
150
151 If the named curve is not supported then :py:class:`ValueError` is raised.
152
153
Laurens Van Houtven07051d32014-06-19 12:00:30 +0200154Serialization and deserialization
155---------------------------------
156
157The following serialization functions take one of these constants to
158determine the format:
159
160.. py:data:: FILETYPE_PEM
161 FILETYPE_ASN1
162
163Certificates
164~~~~~~~~~~~~
165
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900166.. py:function:: dump_certificate(type, cert)
167
168 Dump the certificate *cert* into a buffer string encoded with the type
169 *type*.
170
Laurens Van Houtven07051d32014-06-19 12:00:30 +0200171.. py:function:: load_certificate(type, buffer)
172
173 Load a certificate (X509) from the string *buffer* encoded with the
174 type *type*.
175
176Certificate signing requests
177~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900178
179.. py:function:: dump_certificate_request(type, req)
180
181 Dump the certificate request *req* into a buffer string encoded with the
182 type *type*.
183
Laurens Van Houtven07051d32014-06-19 12:00:30 +0200184.. py:function:: load_certificate_request(type, buffer)
185
186 Load a certificate request (X509Req) from the string *buffer* encoded with
187 the type *type*.
188
189Private keys
190~~~~~~~~~~~~
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900191
192.. py:function:: dump_privatekey(type, pkey[, cipher, passphrase])
193
194 Dump the private key *pkey* into a buffer string encoded with the type
195 *type*, optionally (if *type* is :py:const:`FILETYPE_PEM`) encrypting it
196 using *cipher* and *passphrase*.
197
198 *passphrase* must be either a string or a callback for providing the
199 pass phrase.
200
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900201.. py:function:: load_privatekey(type, buffer[, passphrase])
202
203 Load a private key (PKey) from the string *buffer* encoded with the type
204 *type* (must be one of :py:const:`FILETYPE_PEM` and
205 :py:const:`FILETYPE_ASN1`).
206
207 *passphrase* must be either a string or a callback for providing the pass
208 phrase.
209
Laurens Van Houtven07051d32014-06-19 12:00:30 +0200210Certificate revocation lists
211~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900212
213.. py:function:: load_crl(type, buffer)
214
215 Load Certificate Revocation List (CRL) data from a string *buffer*.
216 *buffer* encoded with the type *type*. The type *type* must either
217 :py:const:`FILETYPE_PEM` or :py:const:`FILETYPE_ASN1`).
218
219
220.. py:function:: load_pkcs7_data(type, buffer)
221
222 Load pkcs7 data from the string *buffer* encoded with the type *type*.
223
224
225.. py:function:: load_pkcs12(buffer[, passphrase])
226
227 Load pkcs12 data from the string *buffer*. If the pkcs12 structure is
228 encrypted, a *passphrase* must be included. The MAC is always
229 checked and thus required.
230
231 See also the man page for the C function :py:func:`PKCS12_parse`.
232
Laurens Van Houtven07051d32014-06-19 12:00:30 +0200233Signing and verifying signatures
234--------------------------------
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900235
236.. py:function:: sign(key, data, digest)
237
238 Sign a data string using the given key and message digest.
239
240 *key* is a :py:class:`PKey` instance. *data* is a ``str`` instance.
241 *digest* is a ``str`` naming a supported message digest type, for example
242 :py:const:`sha1`.
243
244 .. versionadded:: 0.11
245
246
247.. py:function:: verify(certificate, signature, data, digest)
248
249 Verify the signature for a data string.
250
251 *certificate* is a :py:class:`X509` instance corresponding to the private
252 key which generated the signature. *signature* is a *str* instance giving
253 the signature itself. *data* is a *str* instance giving the data to which
254 the signature applies. *digest* is a *str* instance naming the message
255 digest type of the signature, for example :py:const:`sha1`.
256
257 .. versionadded:: 0.11
258
259
260.. _openssl-x509:
261
262X509 objects
263------------
264
Laurens Van Houtvenc3baa7b2014-06-18 22:06:56 +0200265.. autoclass:: X509
266 :members:
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900267
268.. _openssl-x509name:
269
270X509Name objects
271----------------
272
Laurens Van Houtven196195b2014-06-17 17:06:34 +0200273.. autoclass:: X509Name
274 :members:
275 :special-members:
276 :exclude-members: __repr__, __getattr__, __weakref__
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900277
278.. _openssl-x509req:
279
280X509Req objects
281---------------
282
Laurens Van Houtven3e83d242014-06-18 14:29:47 +0200283.. autoclass:: X509Req
284 :members:
285 :special-members:
286 :exclude-members: __weakref__
Jean-Paul Calderone26e07d62014-03-02 08:08:23 -0500287
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900288.. _openssl-x509store:
289
290X509Store objects
291-----------------
292
Laurens Van Houtven8aeafdd2014-06-17 15:33:42 +0200293.. autoclass:: X509Store
294 :members:
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900295
Stephen Holsapple95a46652015-02-09 19:34:25 -0800296X509StoreContextError objects
297-----------------------------
298
299The X509StoreContextError is an exception raised from
300`X509StoreContext.verify_certificate` in circumstances where a certificate
301cannot be verified in a provided context.
302
Jean-Paul Calderone876b2ac2015-03-15 16:17:19 -0400303The certificate for which the verification error was detected is given by the
304``certificate`` attribute of the exception instance as a :class:`X509`
305instance.
306
307Details about the verification error are given in the exception's ``args`` attribute.
Stephen Holsapple95a46652015-02-09 19:34:25 -0800308
309
Stephen Holsapple08ffaa62015-01-30 17:18:40 -0800310X509StoreContext objects
311------------------------
312
313The X509StoreContext object is used for verifying a certificate against a set
314of trusted certificates.
315
316
317.. py:method:: X509StoreContext.verify_certificate()
318
319 Verify a certificate in the context of this initialized `X509StoreContext`.
320 On error, raises `X509StoreContextError`, otherwise does nothing.
321
322 .. versionadded:: 0.15
323
324
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900325.. _openssl-pkey:
326
327PKey objects
328------------
329
Laurens Van Houtven6e7dd432014-06-17 16:10:57 +0200330.. autoclass:: PKey
331 :members:
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900332
333.. _openssl-pkcs7:
334
335PKCS7 objects
336-------------
337
338PKCS7 objects have the following methods:
339
Jonathan Ballet6381da32011-07-20 16:43:38 +0900340.. py:method:: PKCS7.type_is_signed()
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900341
342 FIXME
343
Jonathan Ballet6381da32011-07-20 16:43:38 +0900344.. py:method:: PKCS7.type_is_enveloped()
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900345
346 FIXME
347
Jonathan Ballet6381da32011-07-20 16:43:38 +0900348.. py:method:: PKCS7.type_is_signedAndEnveloped()
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900349
350 FIXME
351
Jonathan Ballet6381da32011-07-20 16:43:38 +0900352.. py:method:: PKCS7.type_is_data()
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900353
354 FIXME
355
Jonathan Ballet6381da32011-07-20 16:43:38 +0900356.. py:method:: PKCS7.get_type_name()
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900357
358 Get the type name of the PKCS7.
359
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900360.. _openssl-pkcs12:
361
362PKCS12 objects
363--------------
364
Laurens Van Houtvenbb503a32014-06-19 12:28:08 +0200365.. autoclass:: PKCS12
366 :members:
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900367
368.. _openssl-509ext:
369
370X509Extension objects
371---------------------
372
Laurens Van Houtven2650de52014-06-18 13:47:47 +0200373.. autoclass:: X509Extension
374 :members:
375 :special-members:
376 :exclude-members: __weakref__
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900377
378.. _openssl-netscape-spki:
379
380NetscapeSPKI objects
381--------------------
382
Laurens Van Houtven59152b52014-06-19 16:42:30 +0200383.. autoclass:: NetscapeSPKI
384 :members:
385 :special-members:
386 :exclude-members: __weakref__
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900387
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900388.. _crl:
389
390CRL objects
391-----------
392
Laurens Van Houtvencb32e852014-06-19 17:36:28 +0200393.. autoclass:: CRL
394 :members:
395 :special-members:
396 :exclude-members: __weakref__
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900397
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900398.. _revoked:
399
400Revoked objects
401---------------
402
Laurens Van Houtvend92f55c2014-06-19 17:08:41 +0200403.. autoclass:: Revoked
404 :members:
Laurens Van Houtven13d56ba2014-06-17 16:00:26 +0200405
Laurens Van Houtvenc3baa7b2014-06-18 22:06:56 +0200406Digest names
407------------
408
409Several of the functions and methods in this module take a digest
410name. These must be strings describing a digest algorithm supported by
411OpenSSL (by ``EVP_get_digestbyname``, specifically). For example,
412:py:const:`b"md5"` or :py:const:`b"sha1"`.
413
414More information and a list of these digest names can be found in the
415``EVP_DigestInit(3)`` man page of your OpenSSL installation. This page
416can be found online for the latest version of OpenSSL:
417https://www.openssl.org/docs/crypto/EVP_DigestInit.html
418
Laurens Van Houtven13d56ba2014-06-17 16:00:26 +0200419Backwards compatible type names
420-------------------------------
421
422When PyOpenSSL was originally written, the most current version of
423Python was 2.1. It made a distinction between classes and types. None
424of the versions of Python currently supported by PyOpenSSL still
425enforce that distinction: the type of an instance of an
426:py:class:`X509` object is now simply :py:class:`X509`. Originally,
427the type would have been :py:class:`X509Type`. These days,
428:py:class:`X509Type` and :py:class:`X509` are literally the same
429object. PyOpenSSL maintains these old names for backwards
430compatibility.
431
432Here's a table of these backwards-compatible names:
433
434========================= =============================
435Type name Backwards-compatible name
436========================= =============================
437:py:class:`X509` :py:class:`X509Type`
438:py:class:`X509Name` :py:class:`X509NameType`
439:py:class:`X509Req` :py:class:`X509ReqType`
440:py:class:`X509Store` :py:class:`X509StoreType`
441:py:class:`X509Extension` :py:class:`X509ExtensionType`
442:py:class:`PKey` :py:class:`PKeyType`
443:py:class:`PKCS7` :py:class:`PKCS7Type`
444:py:class:`PKCS12` :py:class:`PKCS12Type`
445:py:class:`NetscapeSPKI` :py:class:`NetscapeSPKIType`
446:py:class:`CRL` :py:class:`CRLType`
447========================= =============================
448
449Soem objects, such as py:class`Revoked`, don't have ``Type``
450equivalents, because they were added after the restriction had been
451lifted.