blob: 8cf4573670c84da4560f425b4bfe0fa1dd9dda3c [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:: PKCS7Type
15
16 A Python type object representing the PKCS7 object type.
17
18
19.. py:data:: PKCS12Type
20
21 A Python type object representing the PKCS12 object type.
22
23
Jonathan Balletc9e066c2011-07-17 22:56:05 +090024.. py:class:: X509Extension(typename, critical, value[, subject][, issuer])
25
26 A class representing an X.509 v3 certificate extensions. See
27 http://openssl.org/docs/apps/x509v3_config.html#STANDARD_EXTENSIONS for
28 *typename* strings and their options. Optional parameters *subject* and
29 *issuer* must be X509 objects.
30
31
32.. py:data:: NetscapeSPKIType
33
34 See :py:class:`NetscapeSPKI`.
35
36
37.. py:class:: NetscapeSPKI([enc])
38
39 A class representing Netscape SPKI objects.
40
41 If the *enc* argument is present, it should be a base64-encoded string
42 representing a NetscapeSPKI object, as returned by the :py:meth:`b64_encode`
43 method.
44
45
46.. py:class:: CRL()
47
48 A class representing Certifcate Revocation List objects.
49
50
51.. py:class:: Revoked()
52
53 A class representing Revocation objects of CRL.
54
55
Jonathan Balletc9e066c2011-07-17 22:56:05 +090056.. py:data:: TYPE_RSA
Jonathan Ballet6381da32011-07-20 16:43:38 +090057 TYPE_DSA
Jonathan Balletc9e066c2011-07-17 22:56:05 +090058
59 Key type constants.
60
Jonathan Balletc9e066c2011-07-17 22:56:05 +090061.. py:exception:: Error
62
63 Generic exception used in the :py:mod:`.crypto` module.
64
Laurens Van Houtven07051d32014-06-19 12:00:30 +020065Elliptic curves
66---------------
Jonathan Balletc9e066c2011-07-17 22:56:05 +090067
Jean-Paul Calderonec09fd582014-04-18 22:00:10 -040068.. py:function:: get_elliptic_curves
69
70 Return a set of objects representing the elliptic curves supported in the
71 OpenSSL build in use.
72
73 The curve objects have a :py:class:`unicode` ``name`` attribute by which
Jean-Paul Calderoneaaf516d2014-04-19 09:10:45 -040074 they identify themselves.
Jean-Paul Calderonec09fd582014-04-18 22:00:10 -040075
76 The curve objects are useful as values for the argument accepted by
Jean-Paul Calderone3b04e352014-04-19 09:29:10 -040077 :py:meth:`Context.set_tmp_ecdh` to specify which elliptical curve should be
78 used for ECDHE key exchange.
Jean-Paul Calderonec09fd582014-04-18 22:00:10 -040079
80
81.. py:function:: get_elliptic_curve
82
83 Return a single curve object selected by name.
84
85 See :py:func:`get_elliptic_curves` for information about curve objects.
86
87 If the named curve is not supported then :py:class:`ValueError` is raised.
88
89
Laurens Van Houtven07051d32014-06-19 12:00:30 +020090Serialization and deserialization
91---------------------------------
92
93The following serialization functions take one of these constants to
94determine the format:
95
96.. py:data:: FILETYPE_PEM
97 FILETYPE_ASN1
98
99Certificates
100~~~~~~~~~~~~
101
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900102.. py:function:: dump_certificate(type, cert)
103
104 Dump the certificate *cert* into a buffer string encoded with the type
105 *type*.
106
Laurens Van Houtven07051d32014-06-19 12:00:30 +0200107.. py:function:: load_certificate(type, buffer)
108
109 Load a certificate (X509) from the string *buffer* encoded with the
110 type *type*.
111
112Certificate signing requests
113~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900114
115.. py:function:: dump_certificate_request(type, req)
116
117 Dump the certificate request *req* into a buffer string encoded with the
118 type *type*.
119
Laurens Van Houtven07051d32014-06-19 12:00:30 +0200120.. py:function:: load_certificate_request(type, buffer)
121
122 Load a certificate request (X509Req) from the string *buffer* encoded with
123 the type *type*.
124
125Private keys
126~~~~~~~~~~~~
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900127
128.. py:function:: dump_privatekey(type, pkey[, cipher, passphrase])
129
130 Dump the private key *pkey* into a buffer string encoded with the type
131 *type*, optionally (if *type* is :py:const:`FILETYPE_PEM`) encrypting it
132 using *cipher* and *passphrase*.
133
134 *passphrase* must be either a string or a callback for providing the
135 pass phrase.
136
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900137.. py:function:: load_privatekey(type, buffer[, passphrase])
138
139 Load a private key (PKey) from the string *buffer* encoded with the type
140 *type* (must be one of :py:const:`FILETYPE_PEM` and
141 :py:const:`FILETYPE_ASN1`).
142
143 *passphrase* must be either a string or a callback for providing the pass
144 phrase.
145
Laurens Van Houtven07051d32014-06-19 12:00:30 +0200146Certificate revocation lists
147~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900148
149.. py:function:: load_crl(type, buffer)
150
151 Load Certificate Revocation List (CRL) data from a string *buffer*.
152 *buffer* encoded with the type *type*. The type *type* must either
153 :py:const:`FILETYPE_PEM` or :py:const:`FILETYPE_ASN1`).
154
155
156.. py:function:: load_pkcs7_data(type, buffer)
157
Laurens Van Houtven0f820872015-04-20 11:25:57 -0700158 Load pkcs7 data from the string *buffer* encoded with the type
159 *type*. The type *type* must either :py:const:`FILETYPE_PEM` or
160 :py:const:`FILETYPE_ASN1`).
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900161
162
163.. py:function:: load_pkcs12(buffer[, passphrase])
164
165 Load pkcs12 data from the string *buffer*. If the pkcs12 structure is
166 encrypted, a *passphrase* must be included. The MAC is always
167 checked and thus required.
168
169 See also the man page for the C function :py:func:`PKCS12_parse`.
170
Laurens Van Houtven07051d32014-06-19 12:00:30 +0200171Signing and verifying signatures
172--------------------------------
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900173
174.. py:function:: sign(key, data, digest)
175
176 Sign a data string using the given key and message digest.
177
178 *key* is a :py:class:`PKey` instance. *data* is a ``str`` instance.
179 *digest* is a ``str`` naming a supported message digest type, for example
180 :py:const:`sha1`.
181
182 .. versionadded:: 0.11
183
184
185.. py:function:: verify(certificate, signature, data, digest)
186
187 Verify the signature for a data string.
188
189 *certificate* is a :py:class:`X509` instance corresponding to the private
190 key which generated the signature. *signature* is a *str* instance giving
191 the signature itself. *data* is a *str* instance giving the data to which
192 the signature applies. *digest* is a *str* instance naming the message
193 digest type of the signature, for example :py:const:`sha1`.
194
195 .. versionadded:: 0.11
196
197
198.. _openssl-x509:
199
200X509 objects
201------------
202
Laurens Van Houtvenc3baa7b2014-06-18 22:06:56 +0200203.. autoclass:: X509
204 :members:
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900205
206.. _openssl-x509name:
207
208X509Name objects
209----------------
210
Laurens Van Houtven196195b2014-06-17 17:06:34 +0200211.. autoclass:: X509Name
212 :members:
213 :special-members:
214 :exclude-members: __repr__, __getattr__, __weakref__
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900215
216.. _openssl-x509req:
217
218X509Req objects
219---------------
220
Laurens Van Houtven3e83d242014-06-18 14:29:47 +0200221.. autoclass:: X509Req
222 :members:
223 :special-members:
224 :exclude-members: __weakref__
Jean-Paul Calderone26e07d62014-03-02 08:08:23 -0500225
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900226.. _openssl-x509store:
227
228X509Store objects
229-----------------
230
Laurens Van Houtven8aeafdd2014-06-17 15:33:42 +0200231.. autoclass:: X509Store
232 :members:
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900233
Stephen Holsapple95a46652015-02-09 19:34:25 -0800234X509StoreContextError objects
235-----------------------------
236
237The X509StoreContextError is an exception raised from
238`X509StoreContext.verify_certificate` in circumstances where a certificate
239cannot be verified in a provided context.
240
Jean-Paul Calderone876b2ac2015-03-15 16:17:19 -0400241The certificate for which the verification error was detected is given by the
242``certificate`` attribute of the exception instance as a :class:`X509`
243instance.
244
Laurens Van Houtven9313a4e2015-04-20 11:27:28 -0700245Details about the verification error are given in the exception's
246``args`` attribute.
Stephen Holsapple95a46652015-02-09 19:34:25 -0800247
Stephen Holsapple08ffaa62015-01-30 17:18:40 -0800248X509StoreContext objects
249------------------------
250
251The X509StoreContext object is used for verifying a certificate against a set
252of trusted certificates.
253
254
255.. py:method:: X509StoreContext.verify_certificate()
256
257 Verify a certificate in the context of this initialized `X509StoreContext`.
258 On error, raises `X509StoreContextError`, otherwise does nothing.
259
260 .. versionadded:: 0.15
261
262
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900263.. _openssl-pkey:
264
265PKey objects
266------------
267
Laurens Van Houtven6e7dd432014-06-17 16:10:57 +0200268.. autoclass:: PKey
269 :members:
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900270
271.. _openssl-pkcs7:
272
273PKCS7 objects
274-------------
275
276PKCS7 objects have the following methods:
277
Jonathan Ballet6381da32011-07-20 16:43:38 +0900278.. py:method:: PKCS7.type_is_signed()
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900279
280 FIXME
281
Jonathan Ballet6381da32011-07-20 16:43:38 +0900282.. py:method:: PKCS7.type_is_enveloped()
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900283
284 FIXME
285
Jonathan Ballet6381da32011-07-20 16:43:38 +0900286.. py:method:: PKCS7.type_is_signedAndEnveloped()
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900287
288 FIXME
289
Jonathan Ballet6381da32011-07-20 16:43:38 +0900290.. py:method:: PKCS7.type_is_data()
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900291
292 FIXME
293
Jonathan Ballet6381da32011-07-20 16:43:38 +0900294.. py:method:: PKCS7.get_type_name()
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900295
296 Get the type name of the PKCS7.
297
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900298.. _openssl-pkcs12:
299
300PKCS12 objects
301--------------
302
Laurens Van Houtvenbb503a32014-06-19 12:28:08 +0200303.. autoclass:: PKCS12
304 :members:
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900305
306.. _openssl-509ext:
307
308X509Extension objects
309---------------------
310
Laurens Van Houtven2650de52014-06-18 13:47:47 +0200311.. autoclass:: X509Extension
312 :members:
313 :special-members:
314 :exclude-members: __weakref__
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900315
316.. _openssl-netscape-spki:
317
318NetscapeSPKI objects
319--------------------
320
Laurens Van Houtven59152b52014-06-19 16:42:30 +0200321.. autoclass:: NetscapeSPKI
322 :members:
323 :special-members:
324 :exclude-members: __weakref__
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900325
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900326.. _crl:
327
328CRL objects
329-----------
330
Laurens Van Houtvencb32e852014-06-19 17:36:28 +0200331.. autoclass:: CRL
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.. _revoked:
337
338Revoked objects
339---------------
340
Laurens Van Houtvend92f55c2014-06-19 17:08:41 +0200341.. autoclass:: Revoked
342 :members:
Laurens Van Houtven13d56ba2014-06-17 16:00:26 +0200343
Laurens Van Houtvenc3baa7b2014-06-18 22:06:56 +0200344Digest names
345------------
346
347Several of the functions and methods in this module take a digest
348name. These must be strings describing a digest algorithm supported by
349OpenSSL (by ``EVP_get_digestbyname``, specifically). For example,
350:py:const:`b"md5"` or :py:const:`b"sha1"`.
351
352More information and a list of these digest names can be found in the
353``EVP_DigestInit(3)`` man page of your OpenSSL installation. This page
354can be found online for the latest version of OpenSSL:
355https://www.openssl.org/docs/crypto/EVP_DigestInit.html
356
Laurens Van Houtven13d56ba2014-06-17 16:00:26 +0200357Backwards compatible type names
358-------------------------------
359
360When PyOpenSSL was originally written, the most current version of
361Python was 2.1. It made a distinction between classes and types. None
362of the versions of Python currently supported by PyOpenSSL still
363enforce that distinction: the type of an instance of an
364:py:class:`X509` object is now simply :py:class:`X509`. Originally,
365the type would have been :py:class:`X509Type`. These days,
366:py:class:`X509Type` and :py:class:`X509` are literally the same
367object. PyOpenSSL maintains these old names for backwards
368compatibility.
369
370Here's a table of these backwards-compatible names:
371
372========================= =============================
373Type name Backwards-compatible name
374========================= =============================
375:py:class:`X509` :py:class:`X509Type`
376:py:class:`X509Name` :py:class:`X509NameType`
377:py:class:`X509Req` :py:class:`X509ReqType`
378:py:class:`X509Store` :py:class:`X509StoreType`
379:py:class:`X509Extension` :py:class:`X509ExtensionType`
380:py:class:`PKey` :py:class:`PKeyType`
381:py:class:`PKCS7` :py:class:`PKCS7Type`
382:py:class:`PKCS12` :py:class:`PKCS12Type`
383:py:class:`NetscapeSPKI` :py:class:`NetscapeSPKIType`
384:py:class:`CRL` :py:class:`CRLType`
385========================= =============================
386
Laurens Van Houtven2ec1fba2015-04-20 11:48:12 -0700387Some objects, such as py:class`Revoked`, don't have ``Type``
Laurens Van Houtven13d56ba2014-06-17 16:00:26 +0200388equivalents, because they were added after the restriction had been
389lifted.