blob: e3d4f148194f7a4fc86dc8cedd05aa55bdf28ea6 [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
Jonathan Balletc9e066c2011-07-17 22:56:05 +090027.. py:class:: X509Extension(typename, critical, value[, subject][, issuer])
28
29 A class representing an X.509 v3 certificate extensions. See
30 http://openssl.org/docs/apps/x509v3_config.html#STANDARD_EXTENSIONS for
31 *typename* strings and their options. Optional parameters *subject* and
32 *issuer* must be X509 objects.
33
34
Jonathan Balletc9e066c2011-07-17 22:56:05 +090035.. py:class:: NetscapeSPKI([enc])
36
37 A class representing Netscape SPKI objects.
38
39 If the *enc* argument is present, it should be a base64-encoded string
40 representing a NetscapeSPKI object, as returned by the :py:meth:`b64_encode`
41 method.
42
43
44.. py:class:: CRL()
45
46 A class representing Certifcate Revocation List objects.
47
48
49.. py:class:: Revoked()
50
51 A class representing Revocation objects of CRL.
52
53
54.. py:data:: FILETYPE_PEM
Jonathan Ballet6381da32011-07-20 16:43:38 +090055 FILETYPE_ASN1
Jonathan Balletc9e066c2011-07-17 22:56:05 +090056
57 File type constants.
58
59
60.. py:data:: TYPE_RSA
Jonathan Ballet6381da32011-07-20 16:43:38 +090061 TYPE_DSA
Jonathan Balletc9e066c2011-07-17 22:56:05 +090062
63 Key type constants.
64
65
66.. py:exception:: Error
67
68 Generic exception used in the :py:mod:`.crypto` module.
69
70
Jean-Paul Calderonec09fd582014-04-18 22:00:10 -040071.. py:function:: get_elliptic_curves
72
73 Return a set of objects representing the elliptic curves supported in the
74 OpenSSL build in use.
75
76 The curve objects have a :py:class:`unicode` ``name`` attribute by which
Jean-Paul Calderoneaaf516d2014-04-19 09:10:45 -040077 they identify themselves.
Jean-Paul Calderonec09fd582014-04-18 22:00:10 -040078
79 The curve objects are useful as values for the argument accepted by
Jean-Paul Calderone3b04e352014-04-19 09:29:10 -040080 :py:meth:`Context.set_tmp_ecdh` to specify which elliptical curve should be
81 used for ECDHE key exchange.
Jean-Paul Calderonec09fd582014-04-18 22:00:10 -040082
83
84.. py:function:: get_elliptic_curve
85
86 Return a single curve object selected by name.
87
88 See :py:func:`get_elliptic_curves` for information about curve objects.
89
90 If the named curve is not supported then :py:class:`ValueError` is raised.
91
92
Jonathan Balletc9e066c2011-07-17 22:56:05 +090093.. py:function:: dump_certificate(type, cert)
94
95 Dump the certificate *cert* into a buffer string encoded with the type
96 *type*.
97
98
99.. py:function:: dump_certificate_request(type, req)
100
101 Dump the certificate request *req* into a buffer string encoded with the
102 type *type*.
103
104
105.. py:function:: dump_privatekey(type, pkey[, cipher, passphrase])
106
107 Dump the private key *pkey* into a buffer string encoded with the type
108 *type*, optionally (if *type* is :py:const:`FILETYPE_PEM`) encrypting it
109 using *cipher* and *passphrase*.
110
111 *passphrase* must be either a string or a callback for providing the
112 pass phrase.
113
114
115.. py:function:: load_certificate(type, buffer)
116
117 Load a certificate (X509) from the string *buffer* encoded with the
118 type *type*.
119
120
121.. py:function:: load_certificate_request(type, buffer)
122
123 Load a certificate request (X509Req) from the string *buffer* encoded with
124 the type *type*.
125
126
127.. py:function:: load_privatekey(type, buffer[, passphrase])
128
129 Load a private key (PKey) from the string *buffer* encoded with the type
130 *type* (must be one of :py:const:`FILETYPE_PEM` and
131 :py:const:`FILETYPE_ASN1`).
132
133 *passphrase* must be either a string or a callback for providing the pass
134 phrase.
135
136
137.. py:function:: load_crl(type, buffer)
138
139 Load Certificate Revocation List (CRL) data from a string *buffer*.
140 *buffer* encoded with the type *type*. The type *type* must either
141 :py:const:`FILETYPE_PEM` or :py:const:`FILETYPE_ASN1`).
142
143
144.. py:function:: load_pkcs7_data(type, buffer)
145
146 Load pkcs7 data from the string *buffer* encoded with the type *type*.
147
148
149.. py:function:: load_pkcs12(buffer[, passphrase])
150
151 Load pkcs12 data from the string *buffer*. If the pkcs12 structure is
152 encrypted, a *passphrase* must be included. The MAC is always
153 checked and thus required.
154
155 See also the man page for the C function :py:func:`PKCS12_parse`.
156
157
158.. py:function:: sign(key, data, digest)
159
160 Sign a data string using the given key and message digest.
161
162 *key* is a :py:class:`PKey` instance. *data* is a ``str`` instance.
163 *digest* is a ``str`` naming a supported message digest type, for example
164 :py:const:`sha1`.
165
166 .. versionadded:: 0.11
167
168
169.. py:function:: verify(certificate, signature, data, digest)
170
171 Verify the signature for a data string.
172
173 *certificate* is a :py:class:`X509` instance corresponding to the private
174 key which generated the signature. *signature* is a *str* instance giving
175 the signature itself. *data* is a *str* instance giving the data to which
176 the signature applies. *digest* is a *str* instance naming the message
177 digest type of the signature, for example :py:const:`sha1`.
178
179 .. versionadded:: 0.11
180
181
182.. _openssl-x509:
183
184X509 objects
185------------
186
187X509 objects have the following methods:
188
189.. py:method:: X509.get_issuer()
190
191 Return an X509Name object representing the issuer of the certificate.
192
193
194.. py:method:: X509.get_pubkey()
195
196 Return a :py:class:`PKey` object representing the public key of the certificate.
197
198
199.. py:method:: X509.get_serial_number()
200
201 Return the certificate serial number.
202
203
204.. py:method:: X509.get_signature_algorithm()
205
206 Return the signature algorithm used in the certificate. If the algorithm is
207 undefined, raise :py:data:`ValueError`.
208
Jean-Paul Calderone54cc3902012-09-12 10:49:07 -0400209 ..versionadded:: 0.13
210
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900211
212.. py:method:: X509.get_subject()
213
214 Return an :py:class:`X509Name` object representing the subject of the certificate.
215
216
217.. py:method:: X509.get_version()
218
219 Return the certificate version.
220
221
222.. py:method:: X509.get_notBefore()
223
224 Return a string giving the time before which the certificate is not valid. The
225 string is formatted as an ASN1 GENERALIZEDTIME::
226
Jonathan Ballet6381da32011-07-20 16:43:38 +0900227 YYYYMMDDhhmmssZ
228 YYYYMMDDhhmmss+hhmm
229 YYYYMMDDhhmmss-hhmm
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900230
231 If no value exists for this field, :py:data:`None` is returned.
232
233
234.. py:method:: X509.get_notAfter()
235
236 Return a string giving the time after which the certificate is not valid. The
237 string is formatted as an ASN1 GENERALIZEDTIME::
238
Jonathan Ballet6381da32011-07-20 16:43:38 +0900239 YYYYMMDDhhmmssZ
240 YYYYMMDDhhmmss+hhmm
241 YYYYMMDDhhmmss-hhmm
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900242
243 If no value exists for this field, :py:data:`None` is returned.
244
245
246.. py:method:: X509.set_notBefore(when)
247
248 Change the time before which the certificate is not valid. *when* is a
249 string formatted as an ASN1 GENERALIZEDTIME::
250
Jonathan Ballet6381da32011-07-20 16:43:38 +0900251 YYYYMMDDhhmmssZ
252 YYYYMMDDhhmmss+hhmm
253 YYYYMMDDhhmmss-hhmm
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900254
255
256.. py:method:: X509.set_notAfter(when)
257
258 Change the time after which the certificate is not valid. *when* is a
259 string formatted as an ASN1 GENERALIZEDTIME::
260
Jonathan Ballet6381da32011-07-20 16:43:38 +0900261 YYYYMMDDhhmmssZ
262 YYYYMMDDhhmmss+hhmm
263 YYYYMMDDhhmmss-hhmm
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900264
265
266
267.. py:method:: X509.gmtime_adj_notBefore(time)
268
269 Adjust the timestamp (in GMT) when the certificate starts being valid.
270
271
272.. py:method:: X509.gmtime_adj_notAfter(time)
273
274 Adjust the timestamp (in GMT) when the certificate stops being valid.
275
276
277.. py:method:: X509.has_expired()
278
279 Checks the certificate's time stamp against current time. Returns true if the
280 certificate has expired and false otherwise.
281
282
283.. py:method:: X509.set_issuer(issuer)
284
285 Set the issuer of the certificate to *issuer*.
286
287
288.. py:method:: X509.set_pubkey(pkey)
289
290 Set the public key of the certificate to *pkey*.
291
292
293.. py:method:: X509.set_serial_number(serialno)
294
295 Set the serial number of the certificate to *serialno*.
296
297
298.. py:method:: X509.set_subject(subject)
299
300 Set the subject of the certificate to *subject*.
301
302
303.. py:method:: X509.set_version(version)
304
305 Set the certificate version to *version*.
306
307
308.. py:method:: X509.sign(pkey, digest)
309
310 Sign the certificate, using the key *pkey* and the message digest algorithm
311 identified by the string *digest*.
312
313
314.. py:method:: X509.subject_name_hash()
315
316 Return the hash of the certificate subject.
317
318.. py:method:: X509.digest(digest_name)
319
320 Return a digest of the certificate, using the *digest_name* method.
321 *digest_name* must be a string describing a digest algorithm supported
322 by OpenSSL (by EVP_get_digestbyname, specifically). For example,
323 :py:const:`"md5"` or :py:const:`"sha1"`.
324
325
326.. py:method:: X509.add_extensions(extensions)
327
328 Add the extensions in the sequence *extensions* to the certificate.
329
330
331.. py:method:: X509.get_extension_count()
332
333 Return the number of extensions on this certificate.
334
335 .. versionadded:: 0.12
336
337
338.. py:method:: X509.get_extension(index)
339
340 Retrieve the extension on this certificate at the given index.
341
342 Extensions on a certificate are kept in order. The index parameter selects
343 which extension will be returned. The returned object will be an
344 :py:class:`X509Extension` instance.
345
346 .. versionadded:: 0.12
347
348
349.. _openssl-x509name:
350
351X509Name objects
352----------------
353
354X509Name objects have the following methods:
355
356.. py:method:: X509Name.hash()
357
358 Return an integer giving the first four bytes of the MD5 digest of the DER
359 representation of the name.
360
361
362.. py:method:: X509Name.der()
363
364 Return a string giving the DER representation of the name.
365
366
367.. py:method:: X509Name.get_components()
368
369 Return a list of two-tuples of strings giving the components of the name.
370
371
372X509Name objects have the following members:
373
374.. py:attribute:: X509Name.countryName
375
376 The country of the entity. :py:attr:`C` may be used as an alias for
377 :py:attr:`countryName`.
378
379
380.. py:attribute:: X509Name.stateOrProvinceName
381
382 The state or province of the entity. :py:attr:`ST` may be used as an alias for
Jean-Paul Calderonef1b70302011-09-11 09:00:00 -0400383 :py:attr:`stateOrProvinceName`.
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900384
385
386.. py:attribute:: X509Name.localityName
387
388 The locality of the entity. :py:attr:`L` may be used as an alias for
389 :py:attr:`localityName`.
390
391
392.. py:attribute:: X509Name.organizationName
393
394 The organization name of the entity. :py:attr:`O` may be used as an alias for
395 :py:attr:`organizationName`.
396
397
398.. py:attribute:: X509Name.organizationalUnitName
399
400 The organizational unit of the entity. :py:attr:`OU` may be used as an alias for
401 :py:attr:`organizationalUnitName`.
402
403
404.. py:attribute:: X509Name.commonName
405
406 The common name of the entity. :py:attr:`CN` may be used as an alias for
407 :py:attr:`commonName`.
408
409
410.. py:attribute:: X509Name.emailAddress
411
412 The e-mail address of the entity.
413
414
415.. _openssl-x509req:
416
417X509Req objects
418---------------
419
420X509Req objects have the following methods:
421
422.. py:method:: X509Req.get_pubkey()
423
424 Return a :py:class:`PKey` object representing the public key of the certificate request.
425
426
427.. py:method:: X509Req.get_subject()
428
429 Return an :py:class:`X509Name` object representing the subject of the certificate.
430
431
432.. py:method:: X509Req.set_pubkey(pkey)
433
434 Set the public key of the certificate request to *pkey*.
435
436
437.. py:method:: X509Req.sign(pkey, digest)
438
439 Sign the certificate request, using the key *pkey* and the message digest
440 algorithm identified by the string *digest*.
441
442
443.. py:method:: X509Req.verify(pkey)
444
445 Verify a certificate request using the public key *pkey*.
446
447
448.. py:method:: X509Req.set_version(version)
449
450 Set the version (RFC 2459, 4.1.2.1) of the certificate request to
451 *version*.
452
453
454.. py:method:: X509Req.get_version()
455
456 Get the version (RFC 2459, 4.1.2.1) of the certificate request.
457
458
Jean-Paul Calderone26e07d62014-03-02 08:08:23 -0500459.. py:method:: X509Req.get_extensions()
460
461 Get extensions to the request.
462
463 .. versionadded:: 0.15
464
465
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900466.. _openssl-x509store:
467
468X509Store objects
469-----------------
470
Laurens Van Houtven8aeafdd2014-06-17 15:33:42 +0200471.. autoclass:: X509Store
472 :members:
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900473
474.. _openssl-pkey:
475
476PKey objects
477------------
478
Laurens Van Houtven6e7dd432014-06-17 16:10:57 +0200479.. autoclass:: PKey
480 :members:
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900481
482.. _openssl-pkcs7:
483
484PKCS7 objects
485-------------
486
487PKCS7 objects have the following methods:
488
Jonathan Ballet6381da32011-07-20 16:43:38 +0900489.. py:method:: PKCS7.type_is_signed()
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900490
491 FIXME
492
493
Jonathan Ballet6381da32011-07-20 16:43:38 +0900494.. py:method:: PKCS7.type_is_enveloped()
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900495
496 FIXME
497
498
Jonathan Ballet6381da32011-07-20 16:43:38 +0900499.. py:method:: PKCS7.type_is_signedAndEnveloped()
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900500
501 FIXME
502
503
Jonathan Ballet6381da32011-07-20 16:43:38 +0900504.. py:method:: PKCS7.type_is_data()
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900505
506 FIXME
507
508
Jonathan Ballet6381da32011-07-20 16:43:38 +0900509.. py:method:: PKCS7.get_type_name()
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900510
511 Get the type name of the PKCS7.
512
513
514.. _openssl-pkcs12:
515
516PKCS12 objects
517--------------
518
519PKCS12 objects have the following methods:
520
Jonathan Ballet6381da32011-07-20 16:43:38 +0900521.. py:method:: PKCS12.export([passphrase=None][, iter=2048][, maciter=1])
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900522
523 Returns a PKCS12 object as a string.
524
525 The optional *passphrase* must be a string not a callback.
526
527 See also the man page for the C function :py:func:`PKCS12_create`.
528
529
530.. py:method:: PKCS12.get_ca_certificates()
531
532 Return CA certificates within the PKCS12 object as a tuple. Returns
533 :py:const:`None` if no CA certificates are present.
534
535
536.. py:method:: PKCS12.get_certificate()
537
538 Return certificate portion of the PKCS12 structure.
539
540
541.. py:method:: PKCS12.get_friendlyname()
542
543 Return friendlyName portion of the PKCS12 structure.
544
545
546.. py:method:: PKCS12.get_privatekey()
547
548 Return private key portion of the PKCS12 structure
549
550
551.. py:method:: PKCS12.set_ca_certificates(cacerts)
552
553 Replace or set the CA certificates within the PKCS12 object with the sequence *cacerts*.
554
555 Set *cacerts* to :py:const:`None` to remove all CA certificates.
556
557
558.. py:method:: PKCS12.set_certificate(cert)
559
560 Replace or set the certificate portion of the PKCS12 structure.
561
562
563.. py:method:: PKCS12.set_friendlyname(name)
564
565 Replace or set the friendlyName portion of the PKCS12 structure.
566
567
568.. py:method:: PKCS12.set_privatekey(pkey)
569
570 Replace or set private key portion of the PKCS12 structure
571
572
573.. _openssl-509ext:
574
575X509Extension objects
576---------------------
577
578X509Extension objects have several methods:
579
580.. py:method:: X509Extension.get_critical()
581
582 Return the critical field of the extension object.
583
584
585.. py:method:: X509Extension.get_short_name()
586
587 Retrieve the short descriptive name for this extension.
588
589 The result is a byte string like :py:const:`basicConstraints`.
590
591 .. versionadded:: 0.12
592
593
594.. py:method:: X509Extension.get_data()
595
596 Retrieve the data for this extension.
597
598 The result is the ASN.1 encoded form of the extension data as a byte string.
599
600 .. versionadded:: 0.12
601
602
603.. _openssl-netscape-spki:
604
605NetscapeSPKI objects
606--------------------
607
608NetscapeSPKI objects have the following methods:
609
610.. py:method:: NetscapeSPKI.b64_encode()
611
612 Return a base64-encoded string representation of the object.
613
614
615.. py:method:: NetscapeSPKI.get_pubkey()
616
617 Return the public key of object.
618
619
620.. py:method:: NetscapeSPKI.set_pubkey(key)
621
622 Set the public key of the object to *key*.
623
624
625.. py:method:: NetscapeSPKI.sign(key, digest_name)
626
627 Sign the NetscapeSPKI object using the given *key* and *digest_name*.
628 *digest_name* must be a string describing a digest algorithm supported by
629 OpenSSL (by EVP_get_digestbyname, specifically). For example,
630 :py:const:`"md5"` or :py:const:`"sha1"`.
631
632
633.. py:method:: NetscapeSPKI.verify(key)
634
635 Verify the NetscapeSPKI object using the given *key*.
636
637
638.. _crl:
639
640CRL objects
641-----------
642
643CRL objects have the following methods:
644
645.. py:method:: CRL.add_revoked(revoked)
646
647 Add a Revoked object to the CRL, by value not reference.
648
649
650.. py:method:: CRL.export(cert, key[, type=FILETYPE_PEM][, days=100])
651
652 Use *cert* and *key* to sign the CRL and return the CRL as a string.
653 *days* is the number of days before the next CRL is due.
654
655
656.. py:method:: CRL.get_revoked()
657
658 Return a tuple of Revoked objects, by value not reference.
659
660
661.. _revoked:
662
663Revoked objects
664---------------
665
666Revoked objects have the following methods:
667
668.. py:method:: Revoked.all_reasons()
669
670 Return a list of all supported reasons.
671
672
673.. py:method:: Revoked.get_reason()
674
675 Return the revocation reason as a str. Can be
676 None, which differs from "Unspecified".
677
678
679.. py:method:: Revoked.get_rev_date()
680
681 Return the revocation date as a str.
682 The string is formatted as an ASN1 GENERALIZEDTIME.
683
684
685.. py:method:: Revoked.get_serial()
686
687 Return a str containing a hex number of the serial of the revoked certificate.
688
689
690.. py:method:: Revoked.set_reason(reason)
691
692 Set the revocation reason. *reason* must be None or a string, but the
693 values are limited. Spaces and case are ignored. See
694 :py:meth:`all_reasons`.
695
696
697.. py:method:: Revoked.set_rev_date(date)
698
699 Set the revocation date.
700 The string is formatted as an ASN1 GENERALIZEDTIME.
701
702
703.. py:method:: Revoked.set_serial(serial)
704
705 *serial* is a string containing a hex number of the serial of the revoked certificate.
Laurens Van Houtven13d56ba2014-06-17 16:00:26 +0200706
707Backwards compatible type names
708-------------------------------
709
710When PyOpenSSL was originally written, the most current version of
711Python was 2.1. It made a distinction between classes and types. None
712of the versions of Python currently supported by PyOpenSSL still
713enforce that distinction: the type of an instance of an
714:py:class:`X509` object is now simply :py:class:`X509`. Originally,
715the type would have been :py:class:`X509Type`. These days,
716:py:class:`X509Type` and :py:class:`X509` are literally the same
717object. PyOpenSSL maintains these old names for backwards
718compatibility.
719
720Here's a table of these backwards-compatible names:
721
722========================= =============================
723Type name Backwards-compatible name
724========================= =============================
725:py:class:`X509` :py:class:`X509Type`
726:py:class:`X509Name` :py:class:`X509NameType`
727:py:class:`X509Req` :py:class:`X509ReqType`
728:py:class:`X509Store` :py:class:`X509StoreType`
729:py:class:`X509Extension` :py:class:`X509ExtensionType`
730:py:class:`PKey` :py:class:`PKeyType`
731:py:class:`PKCS7` :py:class:`PKCS7Type`
732:py:class:`PKCS12` :py:class:`PKCS12Type`
733:py:class:`NetscapeSPKI` :py:class:`NetscapeSPKIType`
734:py:class:`CRL` :py:class:`CRLType`
735========================= =============================
736
737Soem objects, such as py:class`Revoked`, don't have ``Type``
738equivalents, because they were added after the restriction had been
739lifted.