blob: 0118cbf8b570ae261ce0fd364871ab8f6671667c [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
Laurens Van Houtven0c26a462015-04-20 11:00:08 -070010.. py:data:: X509Store
Stephen Holsapple0d9815f2014-08-27 19:36:53 -070011
12 A class representing the X.509 store.
13
14
15.. py:data:: X509StoreContext
16
17 A class representing the X.509 store context.
Jonathan Balletc9e066c2011-07-17 22:56:05 +090018
19
Jonathan Balletc9e066c2011-07-17 22:56:05 +090020.. py:class:: PKey()
21
22 A class representing DSA or RSA keys.
23
Jonathan Balletc9e066c2011-07-17 22:56:05 +090024.. py:data:: PKCS7Type
25
26 A Python type object representing the PKCS7 object type.
27
28
29.. py:data:: PKCS12Type
30
31 A Python type object representing the PKCS12 object type.
32
33
Jonathan Balletc9e066c2011-07-17 22:56:05 +090034.. py:class:: X509Extension(typename, critical, value[, subject][, issuer])
35
36 A class representing an X.509 v3 certificate extensions. See
37 http://openssl.org/docs/apps/x509v3_config.html#STANDARD_EXTENSIONS for
38 *typename* strings and their options. Optional parameters *subject* and
39 *issuer* must be X509 objects.
40
41
42.. py:data:: NetscapeSPKIType
43
44 See :py:class:`NetscapeSPKI`.
45
46
47.. py:class:: NetscapeSPKI([enc])
48
49 A class representing Netscape SPKI objects.
50
51 If the *enc* argument is present, it should be a base64-encoded string
52 representing a NetscapeSPKI object, as returned by the :py:meth:`b64_encode`
53 method.
54
55
56.. py:class:: CRL()
57
58 A class representing Certifcate Revocation List objects.
59
60
61.. py:class:: Revoked()
62
63 A class representing Revocation objects of CRL.
64
65
Jonathan Balletc9e066c2011-07-17 22:56:05 +090066.. py:data:: TYPE_RSA
Jonathan Ballet6381da32011-07-20 16:43:38 +090067 TYPE_DSA
Jonathan Balletc9e066c2011-07-17 22:56:05 +090068
69 Key type constants.
70
Jonathan Balletc9e066c2011-07-17 22:56:05 +090071.. py:exception:: Error
72
73 Generic exception used in the :py:mod:`.crypto` module.
74
Laurens Van Houtven07051d32014-06-19 12:00:30 +020075Elliptic curves
76---------------
Jonathan Balletc9e066c2011-07-17 22:56:05 +090077
Jean-Paul Calderonec09fd582014-04-18 22:00:10 -040078.. py:function:: get_elliptic_curves
79
80 Return a set of objects representing the elliptic curves supported in the
81 OpenSSL build in use.
82
83 The curve objects have a :py:class:`unicode` ``name`` attribute by which
Jean-Paul Calderoneaaf516d2014-04-19 09:10:45 -040084 they identify themselves.
Jean-Paul Calderonec09fd582014-04-18 22:00:10 -040085
86 The curve objects are useful as values for the argument accepted by
Jean-Paul Calderone3b04e352014-04-19 09:29:10 -040087 :py:meth:`Context.set_tmp_ecdh` to specify which elliptical curve should be
88 used for ECDHE key exchange.
Jean-Paul Calderonec09fd582014-04-18 22:00:10 -040089
90
91.. py:function:: get_elliptic_curve
92
93 Return a single curve object selected by name.
94
95 See :py:func:`get_elliptic_curves` for information about curve objects.
96
97 If the named curve is not supported then :py:class:`ValueError` is raised.
98
99
Laurens Van Houtven07051d32014-06-19 12:00:30 +0200100Serialization and deserialization
101---------------------------------
102
103The following serialization functions take one of these constants to
104determine the format:
105
106.. py:data:: FILETYPE_PEM
107 FILETYPE_ASN1
108
109Certificates
110~~~~~~~~~~~~
111
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900112.. py:function:: dump_certificate(type, cert)
113
114 Dump the certificate *cert* into a buffer string encoded with the type
115 *type*.
116
Laurens Van Houtven07051d32014-06-19 12:00:30 +0200117.. py:function:: load_certificate(type, buffer)
118
119 Load a certificate (X509) from the string *buffer* encoded with the
120 type *type*.
121
122Certificate signing requests
123~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900124
125.. py:function:: dump_certificate_request(type, req)
126
127 Dump the certificate request *req* into a buffer string encoded with the
128 type *type*.
129
Laurens Van Houtven07051d32014-06-19 12:00:30 +0200130.. py:function:: load_certificate_request(type, buffer)
131
132 Load a certificate request (X509Req) from the string *buffer* encoded with
133 the type *type*.
134
135Private keys
136~~~~~~~~~~~~
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900137
138.. py:function:: dump_privatekey(type, pkey[, cipher, passphrase])
139
140 Dump the private key *pkey* into a buffer string encoded with the type
141 *type*, optionally (if *type* is :py:const:`FILETYPE_PEM`) encrypting it
142 using *cipher* and *passphrase*.
143
144 *passphrase* must be either a string or a callback for providing the
145 pass phrase.
146
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900147.. py:function:: load_privatekey(type, buffer[, passphrase])
148
149 Load a private key (PKey) from the string *buffer* encoded with the type
150 *type* (must be one of :py:const:`FILETYPE_PEM` and
151 :py:const:`FILETYPE_ASN1`).
152
153 *passphrase* must be either a string or a callback for providing the pass
154 phrase.
155
Laurens Van Houtven07051d32014-06-19 12:00:30 +0200156Certificate revocation lists
157~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900158
159.. py:function:: load_crl(type, buffer)
160
161 Load Certificate Revocation List (CRL) data from a string *buffer*.
162 *buffer* encoded with the type *type*. The type *type* must either
163 :py:const:`FILETYPE_PEM` or :py:const:`FILETYPE_ASN1`).
164
165
166.. py:function:: load_pkcs7_data(type, buffer)
167
Laurens Van Houtven0f820872015-04-20 11:25:57 -0700168 Load pkcs7 data from the string *buffer* encoded with the type
169 *type*. The type *type* must either :py:const:`FILETYPE_PEM` or
170 :py:const:`FILETYPE_ASN1`).
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900171
172
173.. py:function:: load_pkcs12(buffer[, passphrase])
174
175 Load pkcs12 data from the string *buffer*. If the pkcs12 structure is
176 encrypted, a *passphrase* must be included. The MAC is always
177 checked and thus required.
178
179 See also the man page for the C function :py:func:`PKCS12_parse`.
180
Laurens Van Houtven07051d32014-06-19 12:00:30 +0200181Signing and verifying signatures
182--------------------------------
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900183
184.. py:function:: sign(key, data, digest)
185
186 Sign a data string using the given key and message digest.
187
188 *key* is a :py:class:`PKey` instance. *data* is a ``str`` instance.
189 *digest* is a ``str`` naming a supported message digest type, for example
190 :py:const:`sha1`.
191
192 .. versionadded:: 0.11
193
194
195.. py:function:: verify(certificate, signature, data, digest)
196
197 Verify the signature for a data string.
198
199 *certificate* is a :py:class:`X509` instance corresponding to the private
200 key which generated the signature. *signature* is a *str* instance giving
201 the signature itself. *data* is a *str* instance giving the data to which
202 the signature applies. *digest* is a *str* instance naming the message
203 digest type of the signature, for example :py:const:`sha1`.
204
205 .. versionadded:: 0.11
206
207
208.. _openssl-x509:
209
210X509 objects
211------------
212
Laurens Van Houtvenc3baa7b2014-06-18 22:06:56 +0200213.. autoclass:: X509
214 :members:
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900215
216.. _openssl-x509name:
217
218X509Name objects
219----------------
220
Laurens Van Houtven196195b2014-06-17 17:06:34 +0200221.. autoclass:: X509Name
222 :members:
223 :special-members:
224 :exclude-members: __repr__, __getattr__, __weakref__
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900225
226.. _openssl-x509req:
227
228X509Req objects
229---------------
230
Laurens Van Houtven3e83d242014-06-18 14:29:47 +0200231.. autoclass:: X509Req
232 :members:
233 :special-members:
234 :exclude-members: __weakref__
Jean-Paul Calderone26e07d62014-03-02 08:08:23 -0500235
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900236.. _openssl-x509store:
237
238X509Store objects
239-----------------
240
Laurens Van Houtven8aeafdd2014-06-17 15:33:42 +0200241.. autoclass:: X509Store
242 :members:
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900243
Stephen Holsapple95a46652015-02-09 19:34:25 -0800244X509StoreContextError objects
245-----------------------------
246
247The X509StoreContextError is an exception raised from
248`X509StoreContext.verify_certificate` in circumstances where a certificate
249cannot be verified in a provided context.
250
Jean-Paul Calderone876b2ac2015-03-15 16:17:19 -0400251The certificate for which the verification error was detected is given by the
252``certificate`` attribute of the exception instance as a :class:`X509`
253instance.
254
Laurens Van Houtven9313a4e2015-04-20 11:27:28 -0700255Details about the verification error are given in the exception's
256``args`` attribute.
Stephen Holsapple95a46652015-02-09 19:34:25 -0800257
Stephen Holsapple08ffaa62015-01-30 17:18:40 -0800258X509StoreContext objects
259------------------------
260
261The X509StoreContext object is used for verifying a certificate against a set
262of trusted certificates.
263
264
265.. py:method:: X509StoreContext.verify_certificate()
266
267 Verify a certificate in the context of this initialized `X509StoreContext`.
268 On error, raises `X509StoreContextError`, otherwise does nothing.
269
270 .. versionadded:: 0.15
271
272
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900273.. _openssl-pkey:
274
275PKey objects
276------------
277
Laurens Van Houtven6e7dd432014-06-17 16:10:57 +0200278.. autoclass:: PKey
279 :members:
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900280
281.. _openssl-pkcs7:
282
283PKCS7 objects
284-------------
285
286PKCS7 objects have the following methods:
287
Jonathan Ballet6381da32011-07-20 16:43:38 +0900288.. py:method:: PKCS7.type_is_signed()
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900289
290 FIXME
291
Jonathan Ballet6381da32011-07-20 16:43:38 +0900292.. py:method:: PKCS7.type_is_enveloped()
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900293
294 FIXME
295
Jonathan Ballet6381da32011-07-20 16:43:38 +0900296.. py:method:: PKCS7.type_is_signedAndEnveloped()
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900297
298 FIXME
299
Jonathan Ballet6381da32011-07-20 16:43:38 +0900300.. py:method:: PKCS7.type_is_data()
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900301
302 FIXME
303
Jonathan Ballet6381da32011-07-20 16:43:38 +0900304.. py:method:: PKCS7.get_type_name()
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900305
306 Get the type name of the PKCS7.
307
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900308.. _openssl-pkcs12:
309
310PKCS12 objects
311--------------
312
Laurens Van Houtvenbb503a32014-06-19 12:28:08 +0200313.. autoclass:: PKCS12
314 :members:
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900315
316.. _openssl-509ext:
317
318X509Extension objects
319---------------------
320
Laurens Van Houtven2650de52014-06-18 13:47:47 +0200321.. autoclass:: X509Extension
322 :members:
323 :special-members:
324 :exclude-members: __weakref__
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900325
326.. _openssl-netscape-spki:
327
328NetscapeSPKI objects
329--------------------
330
Laurens Van Houtven59152b52014-06-19 16:42:30 +0200331.. autoclass:: NetscapeSPKI
332 :members:
333 :special-members:
334 :exclude-members: __weakref__
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900335
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900336.. _crl:
337
338CRL objects
339-----------
340
Laurens Van Houtvencb32e852014-06-19 17:36:28 +0200341.. autoclass:: CRL
342 :members:
343 :special-members:
344 :exclude-members: __weakref__
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900345
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900346.. _revoked:
347
348Revoked objects
349---------------
350
Laurens Van Houtvend92f55c2014-06-19 17:08:41 +0200351.. autoclass:: Revoked
352 :members:
Laurens Van Houtven13d56ba2014-06-17 16:00:26 +0200353
Laurens Van Houtvenc3baa7b2014-06-18 22:06:56 +0200354Digest names
355------------
356
357Several of the functions and methods in this module take a digest
358name. These must be strings describing a digest algorithm supported by
359OpenSSL (by ``EVP_get_digestbyname``, specifically). For example,
360:py:const:`b"md5"` or :py:const:`b"sha1"`.
361
362More information and a list of these digest names can be found in the
363``EVP_DigestInit(3)`` man page of your OpenSSL installation. This page
364can be found online for the latest version of OpenSSL:
365https://www.openssl.org/docs/crypto/EVP_DigestInit.html
366
Laurens Van Houtven13d56ba2014-06-17 16:00:26 +0200367Backwards compatible type names
368-------------------------------
369
370When PyOpenSSL was originally written, the most current version of
371Python was 2.1. It made a distinction between classes and types. None
372of the versions of Python currently supported by PyOpenSSL still
373enforce that distinction: the type of an instance of an
374:py:class:`X509` object is now simply :py:class:`X509`. Originally,
375the type would have been :py:class:`X509Type`. These days,
376:py:class:`X509Type` and :py:class:`X509` are literally the same
377object. PyOpenSSL maintains these old names for backwards
378compatibility.
379
380Here's a table of these backwards-compatible names:
381
382========================= =============================
383Type name Backwards-compatible name
384========================= =============================
385:py:class:`X509` :py:class:`X509Type`
386:py:class:`X509Name` :py:class:`X509NameType`
387:py:class:`X509Req` :py:class:`X509ReqType`
388:py:class:`X509Store` :py:class:`X509StoreType`
389:py:class:`X509Extension` :py:class:`X509ExtensionType`
390:py:class:`PKey` :py:class:`PKeyType`
391:py:class:`PKCS7` :py:class:`PKCS7Type`
392:py:class:`PKCS12` :py:class:`PKCS12Type`
393:py:class:`NetscapeSPKI` :py:class:`NetscapeSPKIType`
394:py:class:`CRL` :py:class:`CRLType`
395========================= =============================
396
397Soem objects, such as py:class`Revoked`, don't have ``Type``
398equivalents, because they were added after the restriction had been
399lifted.