blob: 185db9d3a7f0a97887deb629ea22441094c9dd2c [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
Jonathan Balletc9e066c2011-07-17 22:56:05 +090010.. py:class:: X509()
11
12 A class representing X.509 certificates.
13
14
Jonathan Balletc9e066c2011-07-17 22:56:05 +090015.. py:class:: X509Name(x509name)
16
17 A class representing X.509 Distinguished Names.
18
19 This constructor creates a copy of *x509name* which should be an
20 instance of :py:class:`X509Name`.
21
22
Jonathan Balletc9e066c2011-07-17 22:56:05 +090023.. py:class:: X509Req()
24
25 A class representing X.509 certificate requests.
26
27
Laurens Van Houtven0c26a462015-04-20 11:00:08 -070028.. py:data:: X509Store
Stephen Holsapple0d9815f2014-08-27 19:36:53 -070029
30 A class representing the X.509 store.
31
32
33.. py:data:: X509StoreContext
34
35 A class representing the X.509 store context.
Jonathan Balletc9e066c2011-07-17 22:56:05 +090036
37
Jonathan Balletc9e066c2011-07-17 22:56:05 +090038.. py:class:: PKey()
39
40 A class representing DSA or RSA keys.
41
Jonathan Balletc9e066c2011-07-17 22:56:05 +090042.. py:data:: PKCS7Type
43
44 A Python type object representing the PKCS7 object type.
45
46
47.. py:data:: PKCS12Type
48
49 A Python type object representing the PKCS12 object type.
50
51
Jonathan Balletc9e066c2011-07-17 22:56:05 +090052.. py:class:: X509Extension(typename, critical, value[, subject][, issuer])
53
54 A class representing an X.509 v3 certificate extensions. See
55 http://openssl.org/docs/apps/x509v3_config.html#STANDARD_EXTENSIONS for
56 *typename* strings and their options. Optional parameters *subject* and
57 *issuer* must be X509 objects.
58
59
60.. py:data:: NetscapeSPKIType
61
62 See :py:class:`NetscapeSPKI`.
63
64
65.. py:class:: NetscapeSPKI([enc])
66
67 A class representing Netscape SPKI objects.
68
69 If the *enc* argument is present, it should be a base64-encoded string
70 representing a NetscapeSPKI object, as returned by the :py:meth:`b64_encode`
71 method.
72
73
74.. py:class:: CRL()
75
76 A class representing Certifcate Revocation List objects.
77
78
79.. py:class:: Revoked()
80
81 A class representing Revocation objects of CRL.
82
83
Jonathan Balletc9e066c2011-07-17 22:56:05 +090084.. py:data:: TYPE_RSA
Jonathan Ballet6381da32011-07-20 16:43:38 +090085 TYPE_DSA
Jonathan Balletc9e066c2011-07-17 22:56:05 +090086
87 Key type constants.
88
Jonathan Balletc9e066c2011-07-17 22:56:05 +090089.. py:exception:: Error
90
91 Generic exception used in the :py:mod:`.crypto` module.
92
Laurens Van Houtven07051d32014-06-19 12:00:30 +020093Elliptic curves
94---------------
Jonathan Balletc9e066c2011-07-17 22:56:05 +090095
Jean-Paul Calderonec09fd582014-04-18 22:00:10 -040096.. py:function:: get_elliptic_curves
97
98 Return a set of objects representing the elliptic curves supported in the
99 OpenSSL build in use.
100
101 The curve objects have a :py:class:`unicode` ``name`` attribute by which
Jean-Paul Calderoneaaf516d2014-04-19 09:10:45 -0400102 they identify themselves.
Jean-Paul Calderonec09fd582014-04-18 22:00:10 -0400103
104 The curve objects are useful as values for the argument accepted by
Jean-Paul Calderone3b04e352014-04-19 09:29:10 -0400105 :py:meth:`Context.set_tmp_ecdh` to specify which elliptical curve should be
106 used for ECDHE key exchange.
Jean-Paul Calderonec09fd582014-04-18 22:00:10 -0400107
108
109.. py:function:: get_elliptic_curve
110
111 Return a single curve object selected by name.
112
113 See :py:func:`get_elliptic_curves` for information about curve objects.
114
115 If the named curve is not supported then :py:class:`ValueError` is raised.
116
117
Laurens Van Houtven07051d32014-06-19 12:00:30 +0200118Serialization and deserialization
119---------------------------------
120
121The following serialization functions take one of these constants to
122determine the format:
123
124.. py:data:: FILETYPE_PEM
125 FILETYPE_ASN1
126
127Certificates
128~~~~~~~~~~~~
129
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900130.. py:function:: dump_certificate(type, cert)
131
132 Dump the certificate *cert* into a buffer string encoded with the type
133 *type*.
134
Laurens Van Houtven07051d32014-06-19 12:00:30 +0200135.. py:function:: load_certificate(type, buffer)
136
137 Load a certificate (X509) from the string *buffer* encoded with the
138 type *type*.
139
140Certificate signing requests
141~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900142
143.. py:function:: dump_certificate_request(type, req)
144
145 Dump the certificate request *req* into a buffer string encoded with the
146 type *type*.
147
Laurens Van Houtven07051d32014-06-19 12:00:30 +0200148.. py:function:: load_certificate_request(type, buffer)
149
150 Load a certificate request (X509Req) from the string *buffer* encoded with
151 the type *type*.
152
153Private keys
154~~~~~~~~~~~~
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900155
156.. py:function:: dump_privatekey(type, pkey[, cipher, passphrase])
157
158 Dump the private key *pkey* into a buffer string encoded with the type
159 *type*, optionally (if *type* is :py:const:`FILETYPE_PEM`) encrypting it
160 using *cipher* and *passphrase*.
161
162 *passphrase* must be either a string or a callback for providing the
163 pass phrase.
164
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900165.. py:function:: load_privatekey(type, buffer[, passphrase])
166
167 Load a private key (PKey) from the string *buffer* encoded with the type
168 *type* (must be one of :py:const:`FILETYPE_PEM` and
169 :py:const:`FILETYPE_ASN1`).
170
171 *passphrase* must be either a string or a callback for providing the pass
172 phrase.
173
Laurens Van Houtven07051d32014-06-19 12:00:30 +0200174Certificate revocation lists
175~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900176
177.. py:function:: load_crl(type, buffer)
178
179 Load Certificate Revocation List (CRL) data from a string *buffer*.
180 *buffer* encoded with the type *type*. The type *type* must either
181 :py:const:`FILETYPE_PEM` or :py:const:`FILETYPE_ASN1`).
182
183
184.. py:function:: load_pkcs7_data(type, buffer)
185
186 Load pkcs7 data from the string *buffer* encoded with the type *type*.
187
188
189.. py:function:: load_pkcs12(buffer[, passphrase])
190
191 Load pkcs12 data from the string *buffer*. If the pkcs12 structure is
192 encrypted, a *passphrase* must be included. The MAC is always
193 checked and thus required.
194
195 See also the man page for the C function :py:func:`PKCS12_parse`.
196
Laurens Van Houtven07051d32014-06-19 12:00:30 +0200197Signing and verifying signatures
198--------------------------------
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900199
200.. py:function:: sign(key, data, digest)
201
202 Sign a data string using the given key and message digest.
203
204 *key* is a :py:class:`PKey` instance. *data* is a ``str`` instance.
205 *digest* is a ``str`` naming a supported message digest type, for example
206 :py:const:`sha1`.
207
208 .. versionadded:: 0.11
209
210
211.. py:function:: verify(certificate, signature, data, digest)
212
213 Verify the signature for a data string.
214
215 *certificate* is a :py:class:`X509` instance corresponding to the private
216 key which generated the signature. *signature* is a *str* instance giving
217 the signature itself. *data* is a *str* instance giving the data to which
218 the signature applies. *digest* is a *str* instance naming the message
219 digest type of the signature, for example :py:const:`sha1`.
220
221 .. versionadded:: 0.11
222
223
224.. _openssl-x509:
225
226X509 objects
227------------
228
Laurens Van Houtvenc3baa7b2014-06-18 22:06:56 +0200229.. autoclass:: X509
230 :members:
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900231
232.. _openssl-x509name:
233
234X509Name objects
235----------------
236
Laurens Van Houtven196195b2014-06-17 17:06:34 +0200237.. autoclass:: X509Name
238 :members:
239 :special-members:
240 :exclude-members: __repr__, __getattr__, __weakref__
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900241
242.. _openssl-x509req:
243
244X509Req objects
245---------------
246
Laurens Van Houtven3e83d242014-06-18 14:29:47 +0200247.. autoclass:: X509Req
248 :members:
249 :special-members:
250 :exclude-members: __weakref__
Jean-Paul Calderone26e07d62014-03-02 08:08:23 -0500251
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900252.. _openssl-x509store:
253
254X509Store objects
255-----------------
256
Laurens Van Houtven8aeafdd2014-06-17 15:33:42 +0200257.. autoclass:: X509Store
258 :members:
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900259
Stephen Holsapple95a46652015-02-09 19:34:25 -0800260X509StoreContextError objects
261-----------------------------
262
263The X509StoreContextError is an exception raised from
264`X509StoreContext.verify_certificate` in circumstances where a certificate
265cannot be verified in a provided context.
266
Jean-Paul Calderone876b2ac2015-03-15 16:17:19 -0400267The certificate for which the verification error was detected is given by the
268``certificate`` attribute of the exception instance as a :class:`X509`
269instance.
270
271Details about the verification error are given in the exception's ``args`` attribute.
Stephen Holsapple95a46652015-02-09 19:34:25 -0800272
273
Stephen Holsapple08ffaa62015-01-30 17:18:40 -0800274X509StoreContext objects
275------------------------
276
277The X509StoreContext object is used for verifying a certificate against a set
278of trusted certificates.
279
280
281.. py:method:: X509StoreContext.verify_certificate()
282
283 Verify a certificate in the context of this initialized `X509StoreContext`.
284 On error, raises `X509StoreContextError`, otherwise does nothing.
285
286 .. versionadded:: 0.15
287
288
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900289.. _openssl-pkey:
290
291PKey objects
292------------
293
Laurens Van Houtven6e7dd432014-06-17 16:10:57 +0200294.. autoclass:: PKey
295 :members:
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900296
297.. _openssl-pkcs7:
298
299PKCS7 objects
300-------------
301
302PKCS7 objects have the following methods:
303
Jonathan Ballet6381da32011-07-20 16:43:38 +0900304.. py:method:: PKCS7.type_is_signed()
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900305
306 FIXME
307
Jonathan Ballet6381da32011-07-20 16:43:38 +0900308.. py:method:: PKCS7.type_is_enveloped()
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900309
310 FIXME
311
Jonathan Ballet6381da32011-07-20 16:43:38 +0900312.. py:method:: PKCS7.type_is_signedAndEnveloped()
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900313
314 FIXME
315
Jonathan Ballet6381da32011-07-20 16:43:38 +0900316.. py:method:: PKCS7.type_is_data()
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900317
318 FIXME
319
Jonathan Ballet6381da32011-07-20 16:43:38 +0900320.. py:method:: PKCS7.get_type_name()
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900321
322 Get the type name of the PKCS7.
323
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900324.. _openssl-pkcs12:
325
326PKCS12 objects
327--------------
328
Laurens Van Houtvenbb503a32014-06-19 12:28:08 +0200329.. autoclass:: PKCS12
330 :members:
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900331
332.. _openssl-509ext:
333
334X509Extension objects
335---------------------
336
Laurens Van Houtven2650de52014-06-18 13:47:47 +0200337.. autoclass:: X509Extension
338 :members:
339 :special-members:
340 :exclude-members: __weakref__
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900341
342.. _openssl-netscape-spki:
343
344NetscapeSPKI objects
345--------------------
346
Laurens Van Houtven59152b52014-06-19 16:42:30 +0200347.. autoclass:: NetscapeSPKI
348 :members:
349 :special-members:
350 :exclude-members: __weakref__
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900351
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900352.. _crl:
353
354CRL objects
355-----------
356
Laurens Van Houtvencb32e852014-06-19 17:36:28 +0200357.. autoclass:: CRL
358 :members:
359 :special-members:
360 :exclude-members: __weakref__
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900361
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900362.. _revoked:
363
364Revoked objects
365---------------
366
Laurens Van Houtvend92f55c2014-06-19 17:08:41 +0200367.. autoclass:: Revoked
368 :members:
Laurens Van Houtven13d56ba2014-06-17 16:00:26 +0200369
Laurens Van Houtvenc3baa7b2014-06-18 22:06:56 +0200370Digest names
371------------
372
373Several of the functions and methods in this module take a digest
374name. These must be strings describing a digest algorithm supported by
375OpenSSL (by ``EVP_get_digestbyname``, specifically). For example,
376:py:const:`b"md5"` or :py:const:`b"sha1"`.
377
378More information and a list of these digest names can be found in the
379``EVP_DigestInit(3)`` man page of your OpenSSL installation. This page
380can be found online for the latest version of OpenSSL:
381https://www.openssl.org/docs/crypto/EVP_DigestInit.html
382
Laurens Van Houtven13d56ba2014-06-17 16:00:26 +0200383Backwards compatible type names
384-------------------------------
385
386When PyOpenSSL was originally written, the most current version of
387Python was 2.1. It made a distinction between classes and types. None
388of the versions of Python currently supported by PyOpenSSL still
389enforce that distinction: the type of an instance of an
390:py:class:`X509` object is now simply :py:class:`X509`. Originally,
391the type would have been :py:class:`X509Type`. These days,
392:py:class:`X509Type` and :py:class:`X509` are literally the same
393object. PyOpenSSL maintains these old names for backwards
394compatibility.
395
396Here's a table of these backwards-compatible names:
397
398========================= =============================
399Type name Backwards-compatible name
400========================= =============================
401:py:class:`X509` :py:class:`X509Type`
402:py:class:`X509Name` :py:class:`X509NameType`
403:py:class:`X509Req` :py:class:`X509ReqType`
404:py:class:`X509Store` :py:class:`X509StoreType`
405:py:class:`X509Extension` :py:class:`X509ExtensionType`
406:py:class:`PKey` :py:class:`PKeyType`
407:py:class:`PKCS7` :py:class:`PKCS7Type`
408:py:class:`PKCS12` :py:class:`PKCS12Type`
409:py:class:`NetscapeSPKI` :py:class:`NetscapeSPKIType`
410:py:class:`CRL` :py:class:`CRLType`
411========================= =============================
412
413Soem objects, such as py:class`Revoked`, don't have ``Type``
414equivalents, because they were added after the restriction had been
415lifted.