blob: 588e26af0d5c0f592523b07d0496fbe813459520 [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:data:: PKCS12Type
15
16 A Python type object representing the PKCS12 object type.
17
18
Jonathan Balletc9e066c2011-07-17 22:56:05 +090019.. py:class:: X509Extension(typename, critical, value[, subject][, issuer])
20
21 A class representing an X.509 v3 certificate extensions. See
22 http://openssl.org/docs/apps/x509v3_config.html#STANDARD_EXTENSIONS for
23 *typename* strings and their options. Optional parameters *subject* and
24 *issuer* must be X509 objects.
25
26
27.. py:data:: NetscapeSPKIType
28
29 See :py:class:`NetscapeSPKI`.
30
31
32.. py:class:: NetscapeSPKI([enc])
33
34 A class representing Netscape SPKI objects.
35
36 If the *enc* argument is present, it should be a base64-encoded string
37 representing a NetscapeSPKI object, as returned by the :py:meth:`b64_encode`
38 method.
39
40
41.. py:class:: CRL()
42
43 A class representing Certifcate Revocation List objects.
44
45
46.. py:class:: Revoked()
47
48 A class representing Revocation objects of CRL.
49
50
Jonathan Balletc9e066c2011-07-17 22:56:05 +090051.. py:data:: TYPE_RSA
Jonathan Ballet6381da32011-07-20 16:43:38 +090052 TYPE_DSA
Jonathan Balletc9e066c2011-07-17 22:56:05 +090053
54 Key type constants.
55
Jonathan Balletc9e066c2011-07-17 22:56:05 +090056.. py:exception:: Error
57
58 Generic exception used in the :py:mod:`.crypto` module.
59
Laurens Van Houtven07051d32014-06-19 12:00:30 +020060Elliptic curves
61---------------
Jonathan Balletc9e066c2011-07-17 22:56:05 +090062
Jean-Paul Calderonec09fd582014-04-18 22:00:10 -040063.. py:function:: get_elliptic_curves
64
65 Return a set of objects representing the elliptic curves supported in the
66 OpenSSL build in use.
67
68 The curve objects have a :py:class:`unicode` ``name`` attribute by which
Jean-Paul Calderoneaaf516d2014-04-19 09:10:45 -040069 they identify themselves.
Jean-Paul Calderonec09fd582014-04-18 22:00:10 -040070
71 The curve objects are useful as values for the argument accepted by
Jean-Paul Calderone3b04e352014-04-19 09:29:10 -040072 :py:meth:`Context.set_tmp_ecdh` to specify which elliptical curve should be
73 used for ECDHE key exchange.
Jean-Paul Calderonec09fd582014-04-18 22:00:10 -040074
75
76.. py:function:: get_elliptic_curve
77
78 Return a single curve object selected by name.
79
80 See :py:func:`get_elliptic_curves` for information about curve objects.
81
82 If the named curve is not supported then :py:class:`ValueError` is raised.
83
84
Laurens Van Houtven07051d32014-06-19 12:00:30 +020085Serialization and deserialization
86---------------------------------
87
88The following serialization functions take one of these constants to
89determine the format:
90
91.. py:data:: FILETYPE_PEM
92 FILETYPE_ASN1
93
94Certificates
95~~~~~~~~~~~~
96
Jonathan Balletc9e066c2011-07-17 22:56:05 +090097.. py:function:: dump_certificate(type, cert)
98
99 Dump the certificate *cert* into a buffer string encoded with the type
100 *type*.
101
Laurens Van Houtven07051d32014-06-19 12:00:30 +0200102.. py:function:: load_certificate(type, buffer)
103
104 Load a certificate (X509) from the string *buffer* encoded with the
105 type *type*.
106
107Certificate signing requests
108~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900109
110.. py:function:: dump_certificate_request(type, req)
111
112 Dump the certificate request *req* into a buffer string encoded with the
113 type *type*.
114
Laurens Van Houtven07051d32014-06-19 12:00:30 +0200115.. py:function:: load_certificate_request(type, buffer)
116
117 Load a certificate request (X509Req) from the string *buffer* encoded with
118 the type *type*.
119
120Private keys
121~~~~~~~~~~~~
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900122
123.. py:function:: dump_privatekey(type, pkey[, cipher, passphrase])
124
125 Dump the private key *pkey* into a buffer string encoded with the type
126 *type*, optionally (if *type* is :py:const:`FILETYPE_PEM`) encrypting it
127 using *cipher* and *passphrase*.
128
129 *passphrase* must be either a string or a callback for providing the
130 pass phrase.
131
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900132.. py:function:: load_privatekey(type, buffer[, passphrase])
133
134 Load a private key (PKey) from the string *buffer* encoded with the type
135 *type* (must be one of :py:const:`FILETYPE_PEM` and
136 :py:const:`FILETYPE_ASN1`).
137
138 *passphrase* must be either a string or a callback for providing the pass
139 phrase.
140
Laurens Van Houtven07051d32014-06-19 12:00:30 +0200141Certificate revocation lists
142~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900143
144.. py:function:: load_crl(type, buffer)
145
146 Load Certificate Revocation List (CRL) data from a string *buffer*.
147 *buffer* encoded with the type *type*. The type *type* must either
148 :py:const:`FILETYPE_PEM` or :py:const:`FILETYPE_ASN1`).
149
150
151.. py:function:: load_pkcs7_data(type, buffer)
152
Laurens Van Houtven0f820872015-04-20 11:25:57 -0700153 Load pkcs7 data from the string *buffer* encoded with the type
154 *type*. The type *type* must either :py:const:`FILETYPE_PEM` or
155 :py:const:`FILETYPE_ASN1`).
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900156
157
158.. py:function:: load_pkcs12(buffer[, passphrase])
159
160 Load pkcs12 data from the string *buffer*. If the pkcs12 structure is
161 encrypted, a *passphrase* must be included. The MAC is always
162 checked and thus required.
163
164 See also the man page for the C function :py:func:`PKCS12_parse`.
165
Laurens Van Houtven07051d32014-06-19 12:00:30 +0200166Signing and verifying signatures
167--------------------------------
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900168
169.. py:function:: sign(key, data, digest)
170
171 Sign a data string using the given key and message digest.
172
173 *key* is a :py:class:`PKey` instance. *data* is a ``str`` instance.
174 *digest* is a ``str`` naming a supported message digest type, for example
175 :py:const:`sha1`.
176
177 .. versionadded:: 0.11
178
179
180.. py:function:: verify(certificate, signature, data, digest)
181
182 Verify the signature for a data string.
183
184 *certificate* is a :py:class:`X509` instance corresponding to the private
185 key which generated the signature. *signature* is a *str* instance giving
186 the signature itself. *data* is a *str* instance giving the data to which
187 the signature applies. *digest* is a *str* instance naming the message
188 digest type of the signature, for example :py:const:`sha1`.
189
190 .. versionadded:: 0.11
191
192
193.. _openssl-x509:
194
195X509 objects
196------------
197
Laurens Van Houtvenc3baa7b2014-06-18 22:06:56 +0200198.. autoclass:: X509
199 :members:
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900200
201.. _openssl-x509name:
202
203X509Name objects
204----------------
205
Laurens Van Houtven196195b2014-06-17 17:06:34 +0200206.. autoclass:: X509Name
207 :members:
208 :special-members:
209 :exclude-members: __repr__, __getattr__, __weakref__
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900210
211.. _openssl-x509req:
212
213X509Req objects
214---------------
215
Laurens Van Houtven3e83d242014-06-18 14:29:47 +0200216.. autoclass:: X509Req
217 :members:
218 :special-members:
219 :exclude-members: __weakref__
Jean-Paul Calderone26e07d62014-03-02 08:08:23 -0500220
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900221.. _openssl-x509store:
222
223X509Store objects
224-----------------
225
Laurens Van Houtven8aeafdd2014-06-17 15:33:42 +0200226.. autoclass:: X509Store
227 :members:
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900228
Stephen Holsapple95a46652015-02-09 19:34:25 -0800229X509StoreContextError objects
230-----------------------------
231
232The X509StoreContextError is an exception raised from
233`X509StoreContext.verify_certificate` in circumstances where a certificate
234cannot be verified in a provided context.
235
Jean-Paul Calderone876b2ac2015-03-15 16:17:19 -0400236The certificate for which the verification error was detected is given by the
237``certificate`` attribute of the exception instance as a :class:`X509`
238instance.
239
Laurens Van Houtven9313a4e2015-04-20 11:27:28 -0700240Details about the verification error are given in the exception's
241``args`` attribute.
Stephen Holsapple95a46652015-02-09 19:34:25 -0800242
Stephen Holsapple08ffaa62015-01-30 17:18:40 -0800243X509StoreContext objects
244------------------------
245
246The X509StoreContext object is used for verifying a certificate against a set
247of trusted certificates.
248
249
250.. py:method:: X509StoreContext.verify_certificate()
251
252 Verify a certificate in the context of this initialized `X509StoreContext`.
253 On error, raises `X509StoreContextError`, otherwise does nothing.
254
255 .. versionadded:: 0.15
256
257
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900258.. _openssl-pkey:
259
260PKey objects
261------------
262
Laurens Van Houtven6e7dd432014-06-17 16:10:57 +0200263.. autoclass:: PKey
264 :members:
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900265
266.. _openssl-pkcs7:
267
268PKCS7 objects
269-------------
270
271PKCS7 objects have the following methods:
272
Jonathan Ballet6381da32011-07-20 16:43:38 +0900273.. py:method:: PKCS7.type_is_signed()
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900274
275 FIXME
276
Jonathan Ballet6381da32011-07-20 16:43:38 +0900277.. py:method:: PKCS7.type_is_enveloped()
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900278
279 FIXME
280
Jonathan Ballet6381da32011-07-20 16:43:38 +0900281.. py:method:: PKCS7.type_is_signedAndEnveloped()
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900282
283 FIXME
284
Jonathan Ballet6381da32011-07-20 16:43:38 +0900285.. py:method:: PKCS7.type_is_data()
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900286
287 FIXME
288
Jonathan Ballet6381da32011-07-20 16:43:38 +0900289.. py:method:: PKCS7.get_type_name()
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900290
291 Get the type name of the PKCS7.
292
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900293.. _openssl-pkcs12:
294
295PKCS12 objects
296--------------
297
Laurens Van Houtvenbb503a32014-06-19 12:28:08 +0200298.. autoclass:: PKCS12
299 :members:
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900300
301.. _openssl-509ext:
302
303X509Extension objects
304---------------------
305
Laurens Van Houtven2650de52014-06-18 13:47:47 +0200306.. autoclass:: X509Extension
307 :members:
308 :special-members:
309 :exclude-members: __weakref__
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900310
311.. _openssl-netscape-spki:
312
313NetscapeSPKI objects
314--------------------
315
Laurens Van Houtven59152b52014-06-19 16:42:30 +0200316.. autoclass:: NetscapeSPKI
317 :members:
318 :special-members:
319 :exclude-members: __weakref__
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900320
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900321.. _crl:
322
323CRL objects
324-----------
325
Laurens Van Houtvencb32e852014-06-19 17:36:28 +0200326.. autoclass:: CRL
327 :members:
328 :special-members:
329 :exclude-members: __weakref__
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900330
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900331.. _revoked:
332
333Revoked objects
334---------------
335
Laurens Van Houtvend92f55c2014-06-19 17:08:41 +0200336.. autoclass:: Revoked
337 :members:
Laurens Van Houtven13d56ba2014-06-17 16:00:26 +0200338
Laurens Van Houtvenc3baa7b2014-06-18 22:06:56 +0200339Digest names
340------------
341
342Several of the functions and methods in this module take a digest
343name. These must be strings describing a digest algorithm supported by
344OpenSSL (by ``EVP_get_digestbyname``, specifically). For example,
345:py:const:`b"md5"` or :py:const:`b"sha1"`.
346
347More information and a list of these digest names can be found in the
348``EVP_DigestInit(3)`` man page of your OpenSSL installation. This page
349can be found online for the latest version of OpenSSL:
350https://www.openssl.org/docs/crypto/EVP_DigestInit.html
351
Laurens Van Houtven13d56ba2014-06-17 16:00:26 +0200352Backwards compatible type names
353-------------------------------
354
355When PyOpenSSL was originally written, the most current version of
356Python was 2.1. It made a distinction between classes and types. None
357of the versions of Python currently supported by PyOpenSSL still
358enforce that distinction: the type of an instance of an
359:py:class:`X509` object is now simply :py:class:`X509`. Originally,
360the type would have been :py:class:`X509Type`. These days,
361:py:class:`X509Type` and :py:class:`X509` are literally the same
362object. PyOpenSSL maintains these old names for backwards
363compatibility.
364
365Here's a table of these backwards-compatible names:
366
367========================= =============================
368Type name Backwards-compatible name
369========================= =============================
370:py:class:`X509` :py:class:`X509Type`
371:py:class:`X509Name` :py:class:`X509NameType`
372:py:class:`X509Req` :py:class:`X509ReqType`
373:py:class:`X509Store` :py:class:`X509StoreType`
374:py:class:`X509Extension` :py:class:`X509ExtensionType`
375:py:class:`PKey` :py:class:`PKeyType`
376:py:class:`PKCS7` :py:class:`PKCS7Type`
377:py:class:`PKCS12` :py:class:`PKCS12Type`
378:py:class:`NetscapeSPKI` :py:class:`NetscapeSPKIType`
379:py:class:`CRL` :py:class:`CRLType`
380========================= =============================
381
Laurens Van Houtven2ec1fba2015-04-20 11:48:12 -0700382Some objects, such as py:class`Revoked`, don't have ``Type``
Laurens Van Houtven13d56ba2014-06-17 16:00:26 +0200383equivalents, because they were added after the restriction had been
384lifted.