blob: 803380525142755243ce1107e3234d0ef15838bd [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:: CRL()
10
11 A class representing Certifcate Revocation List objects.
12
Jonathan Balletc9e066c2011-07-17 22:56:05 +090013.. py:data:: TYPE_RSA
Jonathan Ballet6381da32011-07-20 16:43:38 +090014 TYPE_DSA
Jonathan Balletc9e066c2011-07-17 22:56:05 +090015
16 Key type constants.
17
Jonathan Balletc9e066c2011-07-17 22:56:05 +090018.. py:exception:: Error
19
20 Generic exception used in the :py:mod:`.crypto` module.
21
Laurens Van Houtven07051d32014-06-19 12:00:30 +020022Elliptic curves
23---------------
Jonathan Balletc9e066c2011-07-17 22:56:05 +090024
Jean-Paul Calderonec09fd582014-04-18 22:00:10 -040025.. py:function:: get_elliptic_curves
26
27 Return a set of objects representing the elliptic curves supported in the
28 OpenSSL build in use.
29
30 The curve objects have a :py:class:`unicode` ``name`` attribute by which
Jean-Paul Calderoneaaf516d2014-04-19 09:10:45 -040031 they identify themselves.
Jean-Paul Calderonec09fd582014-04-18 22:00:10 -040032
33 The curve objects are useful as values for the argument accepted by
Jean-Paul Calderone3b04e352014-04-19 09:29:10 -040034 :py:meth:`Context.set_tmp_ecdh` to specify which elliptical curve should be
35 used for ECDHE key exchange.
Jean-Paul Calderonec09fd582014-04-18 22:00:10 -040036
37
38.. py:function:: get_elliptic_curve
39
40 Return a single curve object selected by name.
41
42 See :py:func:`get_elliptic_curves` for information about curve objects.
43
44 If the named curve is not supported then :py:class:`ValueError` is raised.
45
46
Laurens Van Houtven07051d32014-06-19 12:00:30 +020047Serialization and deserialization
48---------------------------------
49
50The following serialization functions take one of these constants to
51determine the format:
52
53.. py:data:: FILETYPE_PEM
54 FILETYPE_ASN1
55
56Certificates
57~~~~~~~~~~~~
58
Jonathan Balletc9e066c2011-07-17 22:56:05 +090059.. py:function:: dump_certificate(type, cert)
60
61 Dump the certificate *cert* into a buffer string encoded with the type
62 *type*.
63
Laurens Van Houtven07051d32014-06-19 12:00:30 +020064.. py:function:: load_certificate(type, buffer)
65
66 Load a certificate (X509) from the string *buffer* encoded with the
67 type *type*.
68
69Certificate signing requests
70~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Jonathan Balletc9e066c2011-07-17 22:56:05 +090071
72.. py:function:: dump_certificate_request(type, req)
73
74 Dump the certificate request *req* into a buffer string encoded with the
75 type *type*.
76
Laurens Van Houtven07051d32014-06-19 12:00:30 +020077.. py:function:: load_certificate_request(type, buffer)
78
79 Load a certificate request (X509Req) from the string *buffer* encoded with
80 the type *type*.
81
82Private keys
83~~~~~~~~~~~~
Jonathan Balletc9e066c2011-07-17 22:56:05 +090084
85.. py:function:: dump_privatekey(type, pkey[, cipher, passphrase])
86
87 Dump the private key *pkey* into a buffer string encoded with the type
88 *type*, optionally (if *type* is :py:const:`FILETYPE_PEM`) encrypting it
89 using *cipher* and *passphrase*.
90
91 *passphrase* must be either a string or a callback for providing the
92 pass phrase.
93
Jonathan Balletc9e066c2011-07-17 22:56:05 +090094.. py:function:: load_privatekey(type, buffer[, passphrase])
95
96 Load a private key (PKey) from the string *buffer* encoded with the type
97 *type* (must be one of :py:const:`FILETYPE_PEM` and
98 :py:const:`FILETYPE_ASN1`).
99
100 *passphrase* must be either a string or a callback for providing the pass
101 phrase.
102
Laurens Van Houtven07051d32014-06-19 12:00:30 +0200103Certificate revocation lists
104~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900105
106.. py:function:: load_crl(type, buffer)
107
108 Load Certificate Revocation List (CRL) data from a string *buffer*.
109 *buffer* encoded with the type *type*. The type *type* must either
110 :py:const:`FILETYPE_PEM` or :py:const:`FILETYPE_ASN1`).
111
112
113.. py:function:: load_pkcs7_data(type, buffer)
114
115 Load pkcs7 data from the string *buffer* encoded with the type *type*.
116
117
118.. py:function:: load_pkcs12(buffer[, passphrase])
119
120 Load pkcs12 data from the string *buffer*. If the pkcs12 structure is
121 encrypted, a *passphrase* must be included. The MAC is always
122 checked and thus required.
123
124 See also the man page for the C function :py:func:`PKCS12_parse`.
125
Laurens Van Houtven07051d32014-06-19 12:00:30 +0200126Signing and verifying signatures
127--------------------------------
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900128
129.. py:function:: sign(key, data, digest)
130
131 Sign a data string using the given key and message digest.
132
133 *key* is a :py:class:`PKey` instance. *data* is a ``str`` instance.
134 *digest* is a ``str`` naming a supported message digest type, for example
135 :py:const:`sha1`.
136
137 .. versionadded:: 0.11
138
139
140.. py:function:: verify(certificate, signature, data, digest)
141
142 Verify the signature for a data string.
143
144 *certificate* is a :py:class:`X509` instance corresponding to the private
145 key which generated the signature. *signature* is a *str* instance giving
146 the signature itself. *data* is a *str* instance giving the data to which
147 the signature applies. *digest* is a *str* instance naming the message
148 digest type of the signature, for example :py:const:`sha1`.
149
150 .. versionadded:: 0.11
151
152
153.. _openssl-x509:
154
155X509 objects
156------------
157
Laurens Van Houtvenc3baa7b2014-06-18 22:06:56 +0200158.. autoclass:: X509
159 :members:
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900160
161.. _openssl-x509name:
162
163X509Name objects
164----------------
165
Laurens Van Houtven196195b2014-06-17 17:06:34 +0200166.. autoclass:: X509Name
167 :members:
168 :special-members:
169 :exclude-members: __repr__, __getattr__, __weakref__
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900170
171.. _openssl-x509req:
172
173X509Req objects
174---------------
175
Laurens Van Houtven3e83d242014-06-18 14:29:47 +0200176.. autoclass:: X509Req
177 :members:
178 :special-members:
179 :exclude-members: __weakref__
Jean-Paul Calderone26e07d62014-03-02 08:08:23 -0500180
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900181.. _openssl-x509store:
182
183X509Store objects
184-----------------
185
Laurens Van Houtven8aeafdd2014-06-17 15:33:42 +0200186.. autoclass:: X509Store
187 :members:
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900188
189.. _openssl-pkey:
190
191PKey objects
192------------
193
Laurens Van Houtven6e7dd432014-06-17 16:10:57 +0200194.. autoclass:: PKey
195 :members:
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900196
197.. _openssl-pkcs7:
198
199PKCS7 objects
200-------------
201
202PKCS7 objects have the following methods:
203
Jonathan Ballet6381da32011-07-20 16:43:38 +0900204.. py:method:: PKCS7.type_is_signed()
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900205
206 FIXME
207
Jonathan Ballet6381da32011-07-20 16:43:38 +0900208.. py:method:: PKCS7.type_is_enveloped()
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900209
210 FIXME
211
Jonathan Ballet6381da32011-07-20 16:43:38 +0900212.. py:method:: PKCS7.type_is_signedAndEnveloped()
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900213
214 FIXME
215
Jonathan Ballet6381da32011-07-20 16:43:38 +0900216.. py:method:: PKCS7.type_is_data()
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900217
218 FIXME
219
Jonathan Ballet6381da32011-07-20 16:43:38 +0900220.. py:method:: PKCS7.get_type_name()
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900221
222 Get the type name of the PKCS7.
223
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900224.. _openssl-pkcs12:
225
226PKCS12 objects
227--------------
228
Laurens Van Houtvenbb503a32014-06-19 12:28:08 +0200229.. autoclass:: PKCS12
230 :members:
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900231
232.. _openssl-509ext:
233
234X509Extension objects
235---------------------
236
Laurens Van Houtven2650de52014-06-18 13:47:47 +0200237.. autoclass:: X509Extension
238 :members:
239 :special-members:
240 :exclude-members: __weakref__
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900241
242.. _openssl-netscape-spki:
243
244NetscapeSPKI objects
245--------------------
246
Laurens Van Houtven59152b52014-06-19 16:42:30 +0200247.. autoclass:: NetscapeSPKI
248 :members:
249 :special-members:
250 :exclude-members: __weakref__
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900251
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900252.. _crl:
253
254CRL objects
255-----------
256
257CRL objects have the following methods:
258
259.. py:method:: CRL.add_revoked(revoked)
260
261 Add a Revoked object to the CRL, by value not reference.
262
263
264.. py:method:: CRL.export(cert, key[, type=FILETYPE_PEM][, days=100])
265
266 Use *cert* and *key* to sign the CRL and return the CRL as a string.
267 *days* is the number of days before the next CRL is due.
268
269
270.. py:method:: CRL.get_revoked()
271
272 Return a tuple of Revoked objects, by value not reference.
273
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900274.. _revoked:
275
276Revoked objects
277---------------
278
Laurens Van Houtvend92f55c2014-06-19 17:08:41 +0200279.. autoclass:: Revoked
280 :members:
Laurens Van Houtven13d56ba2014-06-17 16:00:26 +0200281
Laurens Van Houtvenc3baa7b2014-06-18 22:06:56 +0200282Digest names
283------------
284
285Several of the functions and methods in this module take a digest
286name. These must be strings describing a digest algorithm supported by
287OpenSSL (by ``EVP_get_digestbyname``, specifically). For example,
288:py:const:`b"md5"` or :py:const:`b"sha1"`.
289
290More information and a list of these digest names can be found in the
291``EVP_DigestInit(3)`` man page of your OpenSSL installation. This page
292can be found online for the latest version of OpenSSL:
293https://www.openssl.org/docs/crypto/EVP_DigestInit.html
294
Laurens Van Houtven13d56ba2014-06-17 16:00:26 +0200295Backwards compatible type names
296-------------------------------
297
298When PyOpenSSL was originally written, the most current version of
299Python was 2.1. It made a distinction between classes and types. None
300of the versions of Python currently supported by PyOpenSSL still
301enforce that distinction: the type of an instance of an
302:py:class:`X509` object is now simply :py:class:`X509`. Originally,
303the type would have been :py:class:`X509Type`. These days,
304:py:class:`X509Type` and :py:class:`X509` are literally the same
305object. PyOpenSSL maintains these old names for backwards
306compatibility.
307
308Here's a table of these backwards-compatible names:
309
310========================= =============================
311Type name Backwards-compatible name
312========================= =============================
313:py:class:`X509` :py:class:`X509Type`
314:py:class:`X509Name` :py:class:`X509NameType`
315:py:class:`X509Req` :py:class:`X509ReqType`
316:py:class:`X509Store` :py:class:`X509StoreType`
317:py:class:`X509Extension` :py:class:`X509ExtensionType`
318:py:class:`PKey` :py:class:`PKeyType`
319:py:class:`PKCS7` :py:class:`PKCS7Type`
320:py:class:`PKCS12` :py:class:`PKCS12Type`
321:py:class:`NetscapeSPKI` :py:class:`NetscapeSPKIType`
322:py:class:`CRL` :py:class:`CRLType`
323========================= =============================
324
325Soem objects, such as py:class`Revoked`, don't have ``Type``
326equivalents, because they were added after the restriction had been
327lifted.