blob: 6dd6a436e6c0fa00f4b44db98ead68f689e8fb14 [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
Jonathan Balletc9e066c2011-07-17 22:56:05 +09009.. py:class:: NetscapeSPKI([enc])
10
11 A class representing Netscape SPKI objects.
12
13 If the *enc* argument is present, it should be a base64-encoded string
14 representing a NetscapeSPKI object, as returned by the :py:meth:`b64_encode`
15 method.
16
17
18.. py:class:: CRL()
19
20 A class representing Certifcate Revocation List objects.
21
22
23.. py:class:: Revoked()
24
25 A class representing Revocation objects of CRL.
26
Jonathan Balletc9e066c2011-07-17 22:56:05 +090027.. py:data:: TYPE_RSA
Jonathan Ballet6381da32011-07-20 16:43:38 +090028 TYPE_DSA
Jonathan Balletc9e066c2011-07-17 22:56:05 +090029
30 Key type constants.
31
Jonathan Balletc9e066c2011-07-17 22:56:05 +090032.. py:exception:: Error
33
34 Generic exception used in the :py:mod:`.crypto` module.
35
Laurens Van Houtven07051d32014-06-19 12:00:30 +020036Elliptic curves
37---------------
Jonathan Balletc9e066c2011-07-17 22:56:05 +090038
Jean-Paul Calderonec09fd582014-04-18 22:00:10 -040039.. py:function:: get_elliptic_curves
40
41 Return a set of objects representing the elliptic curves supported in the
42 OpenSSL build in use.
43
44 The curve objects have a :py:class:`unicode` ``name`` attribute by which
Jean-Paul Calderoneaaf516d2014-04-19 09:10:45 -040045 they identify themselves.
Jean-Paul Calderonec09fd582014-04-18 22:00:10 -040046
47 The curve objects are useful as values for the argument accepted by
Jean-Paul Calderone3b04e352014-04-19 09:29:10 -040048 :py:meth:`Context.set_tmp_ecdh` to specify which elliptical curve should be
49 used for ECDHE key exchange.
Jean-Paul Calderonec09fd582014-04-18 22:00:10 -040050
51
52.. py:function:: get_elliptic_curve
53
54 Return a single curve object selected by name.
55
56 See :py:func:`get_elliptic_curves` for information about curve objects.
57
58 If the named curve is not supported then :py:class:`ValueError` is raised.
59
60
Laurens Van Houtven07051d32014-06-19 12:00:30 +020061Serialization and deserialization
62---------------------------------
63
64The following serialization functions take one of these constants to
65determine the format:
66
67.. py:data:: FILETYPE_PEM
68 FILETYPE_ASN1
69
70Certificates
71~~~~~~~~~~~~
72
Jonathan Balletc9e066c2011-07-17 22:56:05 +090073.. py:function:: dump_certificate(type, cert)
74
75 Dump the certificate *cert* into a buffer string encoded with the type
76 *type*.
77
Laurens Van Houtven07051d32014-06-19 12:00:30 +020078.. py:function:: load_certificate(type, buffer)
79
80 Load a certificate (X509) from the string *buffer* encoded with the
81 type *type*.
82
83Certificate signing requests
84~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Jonathan Balletc9e066c2011-07-17 22:56:05 +090085
86.. py:function:: dump_certificate_request(type, req)
87
88 Dump the certificate request *req* into a buffer string encoded with the
89 type *type*.
90
Laurens Van Houtven07051d32014-06-19 12:00:30 +020091.. py:function:: load_certificate_request(type, buffer)
92
93 Load a certificate request (X509Req) from the string *buffer* encoded with
94 the type *type*.
95
96Private keys
97~~~~~~~~~~~~
Jonathan Balletc9e066c2011-07-17 22:56:05 +090098
99.. py:function:: dump_privatekey(type, pkey[, cipher, passphrase])
100
101 Dump the private key *pkey* into a buffer string encoded with the type
102 *type*, optionally (if *type* is :py:const:`FILETYPE_PEM`) encrypting it
103 using *cipher* and *passphrase*.
104
105 *passphrase* must be either a string or a callback for providing the
106 pass phrase.
107
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900108.. py:function:: load_privatekey(type, buffer[, passphrase])
109
110 Load a private key (PKey) from the string *buffer* encoded with the type
111 *type* (must be one of :py:const:`FILETYPE_PEM` and
112 :py:const:`FILETYPE_ASN1`).
113
114 *passphrase* must be either a string or a callback for providing the pass
115 phrase.
116
Laurens Van Houtven07051d32014-06-19 12:00:30 +0200117Certificate revocation lists
118~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900119
120.. py:function:: load_crl(type, buffer)
121
122 Load Certificate Revocation List (CRL) data from a string *buffer*.
123 *buffer* encoded with the type *type*. The type *type* must either
124 :py:const:`FILETYPE_PEM` or :py:const:`FILETYPE_ASN1`).
125
126
127.. py:function:: load_pkcs7_data(type, buffer)
128
129 Load pkcs7 data from the string *buffer* encoded with the type *type*.
130
131
132.. py:function:: load_pkcs12(buffer[, passphrase])
133
134 Load pkcs12 data from the string *buffer*. If the pkcs12 structure is
135 encrypted, a *passphrase* must be included. The MAC is always
136 checked and thus required.
137
138 See also the man page for the C function :py:func:`PKCS12_parse`.
139
Laurens Van Houtven07051d32014-06-19 12:00:30 +0200140Signing and verifying signatures
141--------------------------------
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900142
143.. py:function:: sign(key, data, digest)
144
145 Sign a data string using the given key and message digest.
146
147 *key* is a :py:class:`PKey` instance. *data* is a ``str`` instance.
148 *digest* is a ``str`` naming a supported message digest type, for example
149 :py:const:`sha1`.
150
151 .. versionadded:: 0.11
152
153
154.. py:function:: verify(certificate, signature, data, digest)
155
156 Verify the signature for a data string.
157
158 *certificate* is a :py:class:`X509` instance corresponding to the private
159 key which generated the signature. *signature* is a *str* instance giving
160 the signature itself. *data* is a *str* instance giving the data to which
161 the signature applies. *digest* is a *str* instance naming the message
162 digest type of the signature, for example :py:const:`sha1`.
163
164 .. versionadded:: 0.11
165
166
167.. _openssl-x509:
168
169X509 objects
170------------
171
Laurens Van Houtvenc3baa7b2014-06-18 22:06:56 +0200172.. autoclass:: X509
173 :members:
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900174
175.. _openssl-x509name:
176
177X509Name objects
178----------------
179
Laurens Van Houtven196195b2014-06-17 17:06:34 +0200180.. autoclass:: X509Name
181 :members:
182 :special-members:
183 :exclude-members: __repr__, __getattr__, __weakref__
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900184
185.. _openssl-x509req:
186
187X509Req objects
188---------------
189
Laurens Van Houtven3e83d242014-06-18 14:29:47 +0200190.. autoclass:: X509Req
191 :members:
192 :special-members:
193 :exclude-members: __weakref__
Jean-Paul Calderone26e07d62014-03-02 08:08:23 -0500194
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900195.. _openssl-x509store:
196
197X509Store objects
198-----------------
199
Laurens Van Houtven8aeafdd2014-06-17 15:33:42 +0200200.. autoclass:: X509Store
201 :members:
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900202
203.. _openssl-pkey:
204
205PKey objects
206------------
207
Laurens Van Houtven6e7dd432014-06-17 16:10:57 +0200208.. autoclass:: PKey
209 :members:
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900210
211.. _openssl-pkcs7:
212
213PKCS7 objects
214-------------
215
216PKCS7 objects have the following methods:
217
Jonathan Ballet6381da32011-07-20 16:43:38 +0900218.. py:method:: PKCS7.type_is_signed()
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900219
220 FIXME
221
Jonathan Ballet6381da32011-07-20 16:43:38 +0900222.. py:method:: PKCS7.type_is_enveloped()
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900223
224 FIXME
225
Jonathan Ballet6381da32011-07-20 16:43:38 +0900226.. py:method:: PKCS7.type_is_signedAndEnveloped()
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900227
228 FIXME
229
Jonathan Ballet6381da32011-07-20 16:43:38 +0900230.. py:method:: PKCS7.type_is_data()
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900231
232 FIXME
233
Jonathan Ballet6381da32011-07-20 16:43:38 +0900234.. py:method:: PKCS7.get_type_name()
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900235
236 Get the type name of the PKCS7.
237
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900238.. _openssl-pkcs12:
239
240PKCS12 objects
241--------------
242
243PKCS12 objects have the following methods:
244
Jonathan Ballet6381da32011-07-20 16:43:38 +0900245.. py:method:: PKCS12.export([passphrase=None][, iter=2048][, maciter=1])
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900246
247 Returns a PKCS12 object as a string.
248
249 The optional *passphrase* must be a string not a callback.
250
251 See also the man page for the C function :py:func:`PKCS12_create`.
252
253
254.. py:method:: PKCS12.get_ca_certificates()
255
256 Return CA certificates within the PKCS12 object as a tuple. Returns
257 :py:const:`None` if no CA certificates are present.
258
259
260.. py:method:: PKCS12.get_certificate()
261
262 Return certificate portion of the PKCS12 structure.
263
264
265.. py:method:: PKCS12.get_friendlyname()
266
267 Return friendlyName portion of the PKCS12 structure.
268
269
270.. py:method:: PKCS12.get_privatekey()
271
272 Return private key portion of the PKCS12 structure
273
274
275.. py:method:: PKCS12.set_ca_certificates(cacerts)
276
277 Replace or set the CA certificates within the PKCS12 object with the sequence *cacerts*.
278
279 Set *cacerts* to :py:const:`None` to remove all CA certificates.
280
281
282.. py:method:: PKCS12.set_certificate(cert)
283
284 Replace or set the certificate portion of the PKCS12 structure.
285
286
287.. py:method:: PKCS12.set_friendlyname(name)
288
289 Replace or set the friendlyName portion of the PKCS12 structure.
290
291
292.. py:method:: PKCS12.set_privatekey(pkey)
293
294 Replace or set private key portion of the PKCS12 structure
295
296
297.. _openssl-509ext:
298
299X509Extension objects
300---------------------
301
Laurens Van Houtven2650de52014-06-18 13:47:47 +0200302.. autoclass:: X509Extension
303 :members:
304 :special-members:
305 :exclude-members: __weakref__
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900306
307.. _openssl-netscape-spki:
308
309NetscapeSPKI objects
310--------------------
311
312NetscapeSPKI objects have the following methods:
313
314.. py:method:: NetscapeSPKI.b64_encode()
315
316 Return a base64-encoded string representation of the object.
317
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900318.. py:method:: NetscapeSPKI.get_pubkey()
319
320 Return the public key of object.
321
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900322.. py:method:: NetscapeSPKI.set_pubkey(key)
323
324 Set the public key of the object to *key*.
325
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900326.. py:method:: NetscapeSPKI.sign(key, digest_name)
327
328 Sign the NetscapeSPKI object using the given *key* and *digest_name*.
329 *digest_name* must be a string describing a digest algorithm supported by
330 OpenSSL (by EVP_get_digestbyname, specifically). For example,
331 :py:const:`"md5"` or :py:const:`"sha1"`.
332
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900333.. py:method:: NetscapeSPKI.verify(key)
334
335 Verify the NetscapeSPKI object using the given *key*.
336
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900337.. _crl:
338
339CRL objects
340-----------
341
342CRL objects have the following methods:
343
344.. py:method:: CRL.add_revoked(revoked)
345
346 Add a Revoked object to the CRL, by value not reference.
347
348
349.. py:method:: CRL.export(cert, key[, type=FILETYPE_PEM][, days=100])
350
351 Use *cert* and *key* to sign the CRL and return the CRL as a string.
352 *days* is the number of days before the next CRL is due.
353
354
355.. py:method:: CRL.get_revoked()
356
357 Return a tuple of Revoked objects, by value not reference.
358
359
360.. _revoked:
361
362Revoked objects
363---------------
364
365Revoked objects have the following methods:
366
367.. py:method:: Revoked.all_reasons()
368
369 Return a list of all supported reasons.
370
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900371.. py:method:: Revoked.get_reason()
372
373 Return the revocation reason as a str. Can be
374 None, which differs from "Unspecified".
375
376
377.. py:method:: Revoked.get_rev_date()
378
379 Return the revocation date as a str.
380 The string is formatted as an ASN1 GENERALIZEDTIME.
381
382
383.. py:method:: Revoked.get_serial()
384
385 Return a str containing a hex number of the serial of the revoked certificate.
386
387
388.. py:method:: Revoked.set_reason(reason)
389
390 Set the revocation reason. *reason* must be None or a string, but the
391 values are limited. Spaces and case are ignored. See
392 :py:meth:`all_reasons`.
393
394
395.. py:method:: Revoked.set_rev_date(date)
396
397 Set the revocation date.
398 The string is formatted as an ASN1 GENERALIZEDTIME.
399
400
401.. py:method:: Revoked.set_serial(serial)
402
403 *serial* is a string containing a hex number of the serial of the revoked certificate.
Laurens Van Houtven13d56ba2014-06-17 16:00:26 +0200404
Laurens Van Houtvenc3baa7b2014-06-18 22:06:56 +0200405Digest names
406------------
407
408Several of the functions and methods in this module take a digest
409name. These must be strings describing a digest algorithm supported by
410OpenSSL (by ``EVP_get_digestbyname``, specifically). For example,
411:py:const:`b"md5"` or :py:const:`b"sha1"`.
412
413More information and a list of these digest names can be found in the
414``EVP_DigestInit(3)`` man page of your OpenSSL installation. This page
415can be found online for the latest version of OpenSSL:
416https://www.openssl.org/docs/crypto/EVP_DigestInit.html
417
Laurens Van Houtven13d56ba2014-06-17 16:00:26 +0200418Backwards compatible type names
419-------------------------------
420
421When PyOpenSSL was originally written, the most current version of
422Python was 2.1. It made a distinction between classes and types. None
423of the versions of Python currently supported by PyOpenSSL still
424enforce that distinction: the type of an instance of an
425:py:class:`X509` object is now simply :py:class:`X509`. Originally,
426the type would have been :py:class:`X509Type`. These days,
427:py:class:`X509Type` and :py:class:`X509` are literally the same
428object. PyOpenSSL maintains these old names for backwards
429compatibility.
430
431Here's a table of these backwards-compatible names:
432
433========================= =============================
434Type name Backwards-compatible name
435========================= =============================
436:py:class:`X509` :py:class:`X509Type`
437:py:class:`X509Name` :py:class:`X509NameType`
438:py:class:`X509Req` :py:class:`X509ReqType`
439:py:class:`X509Store` :py:class:`X509StoreType`
440:py:class:`X509Extension` :py:class:`X509ExtensionType`
441:py:class:`PKey` :py:class:`PKeyType`
442:py:class:`PKCS7` :py:class:`PKCS7Type`
443:py:class:`PKCS12` :py:class:`PKCS12Type`
444:py:class:`NetscapeSPKI` :py:class:`NetscapeSPKIType`
445:py:class:`CRL` :py:class:`CRLType`
446========================= =============================
447
448Soem objects, such as py:class`Revoked`, don't have ``Type``
449equivalents, because they were added after the restriction had been
450lifted.