blob: 5637ea321941f7180e5b7558897ad423f8e0bf97 [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:data:: X509Type
Jonathan Ballet648875f2011-07-16 14:14:58 +090011
Jonathan Balletc9e066c2011-07-17 22:56:05 +090012 See :py:class:`X509`.
Jonathan Ballet648875f2011-07-16 14:14:58 +090013
14
Jonathan Balletc9e066c2011-07-17 22:56:05 +090015.. py:class:: X509()
16
17 A class representing X.509 certificates.
18
19
20.. py:data:: X509NameType
21
22 See :py:class:`X509Name`.
23
24
25.. py:class:: X509Name(x509name)
26
27 A class representing X.509 Distinguished Names.
28
29 This constructor creates a copy of *x509name* which should be an
30 instance of :py:class:`X509Name`.
31
32
33.. py:data:: X509ReqType
34
35 See :py:class:`X509Req`.
36
37
38.. py:class:: X509Req()
39
40 A class representing X.509 certificate requests.
41
42
Jonathan Balletc9e066c2011-07-17 22:56:05 +090043.. py:data:: PKeyType
44
45 See :py:class:`PKey`.
46
47
48.. py:class:: PKey()
49
50 A class representing DSA or RSA keys.
51
52
53.. py:data:: PKCS7Type
54
55 A Python type object representing the PKCS7 object type.
56
57
58.. py:data:: PKCS12Type
59
60 A Python type object representing the PKCS12 object type.
61
62
63.. py:data:: X509ExtensionType
64
65 See :py:class:`X509Extension`.
66
67
68.. py:class:: X509Extension(typename, critical, value[, subject][, issuer])
69
70 A class representing an X.509 v3 certificate extensions. See
71 http://openssl.org/docs/apps/x509v3_config.html#STANDARD_EXTENSIONS for
72 *typename* strings and their options. Optional parameters *subject* and
73 *issuer* must be X509 objects.
74
75
76.. py:data:: NetscapeSPKIType
77
78 See :py:class:`NetscapeSPKI`.
79
80
81.. py:class:: NetscapeSPKI([enc])
82
83 A class representing Netscape SPKI objects.
84
85 If the *enc* argument is present, it should be a base64-encoded string
86 representing a NetscapeSPKI object, as returned by the :py:meth:`b64_encode`
87 method.
88
89
90.. py:class:: CRL()
91
92 A class representing Certifcate Revocation List objects.
93
94
95.. py:class:: Revoked()
96
97 A class representing Revocation objects of CRL.
98
99
100.. py:data:: FILETYPE_PEM
Jonathan Ballet6381da32011-07-20 16:43:38 +0900101 FILETYPE_ASN1
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900102
103 File type constants.
104
105
106.. py:data:: TYPE_RSA
Jonathan Ballet6381da32011-07-20 16:43:38 +0900107 TYPE_DSA
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900108
109 Key type constants.
110
111
112.. py:exception:: Error
113
114 Generic exception used in the :py:mod:`.crypto` module.
115
116
Jean-Paul Calderonec09fd582014-04-18 22:00:10 -0400117.. py:function:: get_elliptic_curves
118
119 Return a set of objects representing the elliptic curves supported in the
120 OpenSSL build in use.
121
122 The curve objects have a :py:class:`unicode` ``name`` attribute by which
Jean-Paul Calderoneaaf516d2014-04-19 09:10:45 -0400123 they identify themselves.
Jean-Paul Calderonec09fd582014-04-18 22:00:10 -0400124
125 The curve objects are useful as values for the argument accepted by
Jean-Paul Calderone3b04e352014-04-19 09:29:10 -0400126 :py:meth:`Context.set_tmp_ecdh` to specify which elliptical curve should be
127 used for ECDHE key exchange.
Jean-Paul Calderonec09fd582014-04-18 22:00:10 -0400128
129
130.. py:function:: get_elliptic_curve
131
132 Return a single curve object selected by name.
133
134 See :py:func:`get_elliptic_curves` for information about curve objects.
135
136 If the named curve is not supported then :py:class:`ValueError` is raised.
137
138
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900139.. py:function:: dump_certificate(type, cert)
140
141 Dump the certificate *cert* into a buffer string encoded with the type
142 *type*.
143
144
145.. py:function:: dump_certificate_request(type, req)
146
147 Dump the certificate request *req* into a buffer string encoded with the
148 type *type*.
149
150
151.. py:function:: dump_privatekey(type, pkey[, cipher, passphrase])
152
153 Dump the private key *pkey* into a buffer string encoded with the type
154 *type*, optionally (if *type* is :py:const:`FILETYPE_PEM`) encrypting it
155 using *cipher* and *passphrase*.
156
157 *passphrase* must be either a string or a callback for providing the
158 pass phrase.
159
160
161.. py:function:: load_certificate(type, buffer)
162
163 Load a certificate (X509) from the string *buffer* encoded with the
164 type *type*.
165
166
167.. py:function:: load_certificate_request(type, buffer)
168
169 Load a certificate request (X509Req) from the string *buffer* encoded with
170 the type *type*.
171
172
173.. py:function:: load_privatekey(type, buffer[, passphrase])
174
175 Load a private key (PKey) from the string *buffer* encoded with the type
176 *type* (must be one of :py:const:`FILETYPE_PEM` and
177 :py:const:`FILETYPE_ASN1`).
178
179 *passphrase* must be either a string or a callback for providing the pass
180 phrase.
181
182
183.. py:function:: load_crl(type, buffer)
184
185 Load Certificate Revocation List (CRL) data from a string *buffer*.
186 *buffer* encoded with the type *type*. The type *type* must either
187 :py:const:`FILETYPE_PEM` or :py:const:`FILETYPE_ASN1`).
188
189
190.. py:function:: load_pkcs7_data(type, buffer)
191
192 Load pkcs7 data from the string *buffer* encoded with the type *type*.
193
194
195.. py:function:: load_pkcs12(buffer[, passphrase])
196
197 Load pkcs12 data from the string *buffer*. If the pkcs12 structure is
198 encrypted, a *passphrase* must be included. The MAC is always
199 checked and thus required.
200
201 See also the man page for the C function :py:func:`PKCS12_parse`.
202
203
204.. py:function:: sign(key, data, digest)
205
206 Sign a data string using the given key and message digest.
207
208 *key* is a :py:class:`PKey` instance. *data* is a ``str`` instance.
209 *digest* is a ``str`` naming a supported message digest type, for example
210 :py:const:`sha1`.
211
212 .. versionadded:: 0.11
213
214
215.. py:function:: verify(certificate, signature, data, digest)
216
217 Verify the signature for a data string.
218
219 *certificate* is a :py:class:`X509` instance corresponding to the private
220 key which generated the signature. *signature* is a *str* instance giving
221 the signature itself. *data* is a *str* instance giving the data to which
222 the signature applies. *digest* is a *str* instance naming the message
223 digest type of the signature, for example :py:const:`sha1`.
224
225 .. versionadded:: 0.11
226
227
228.. _openssl-x509:
229
230X509 objects
231------------
232
233X509 objects have the following methods:
234
235.. py:method:: X509.get_issuer()
236
237 Return an X509Name object representing the issuer of the certificate.
238
239
240.. py:method:: X509.get_pubkey()
241
242 Return a :py:class:`PKey` object representing the public key of the certificate.
243
244
245.. py:method:: X509.get_serial_number()
246
247 Return the certificate serial number.
248
249
250.. py:method:: X509.get_signature_algorithm()
251
252 Return the signature algorithm used in the certificate. If the algorithm is
253 undefined, raise :py:data:`ValueError`.
254
Jean-Paul Calderone54cc3902012-09-12 10:49:07 -0400255 ..versionadded:: 0.13
256
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900257
258.. py:method:: X509.get_subject()
259
260 Return an :py:class:`X509Name` object representing the subject of the certificate.
261
262
263.. py:method:: X509.get_version()
264
265 Return the certificate version.
266
267
268.. py:method:: X509.get_notBefore()
269
270 Return a string giving the time before which the certificate is not valid. The
271 string is formatted as an ASN1 GENERALIZEDTIME::
272
Jonathan Ballet6381da32011-07-20 16:43:38 +0900273 YYYYMMDDhhmmssZ
274 YYYYMMDDhhmmss+hhmm
275 YYYYMMDDhhmmss-hhmm
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900276
277 If no value exists for this field, :py:data:`None` is returned.
278
279
280.. py:method:: X509.get_notAfter()
281
282 Return a string giving the time after which the certificate is not valid. The
283 string is formatted as an ASN1 GENERALIZEDTIME::
284
Jonathan Ballet6381da32011-07-20 16:43:38 +0900285 YYYYMMDDhhmmssZ
286 YYYYMMDDhhmmss+hhmm
287 YYYYMMDDhhmmss-hhmm
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900288
289 If no value exists for this field, :py:data:`None` is returned.
290
291
292.. py:method:: X509.set_notBefore(when)
293
294 Change the time before which the certificate is not valid. *when* is a
295 string formatted as an ASN1 GENERALIZEDTIME::
296
Jonathan Ballet6381da32011-07-20 16:43:38 +0900297 YYYYMMDDhhmmssZ
298 YYYYMMDDhhmmss+hhmm
299 YYYYMMDDhhmmss-hhmm
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900300
301
302.. py:method:: X509.set_notAfter(when)
303
304 Change the time after which the certificate is not valid. *when* is a
305 string formatted as an ASN1 GENERALIZEDTIME::
306
Jonathan Ballet6381da32011-07-20 16:43:38 +0900307 YYYYMMDDhhmmssZ
308 YYYYMMDDhhmmss+hhmm
309 YYYYMMDDhhmmss-hhmm
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900310
311
312
313.. py:method:: X509.gmtime_adj_notBefore(time)
314
315 Adjust the timestamp (in GMT) when the certificate starts being valid.
316
317
318.. py:method:: X509.gmtime_adj_notAfter(time)
319
320 Adjust the timestamp (in GMT) when the certificate stops being valid.
321
322
323.. py:method:: X509.has_expired()
324
325 Checks the certificate's time stamp against current time. Returns true if the
326 certificate has expired and false otherwise.
327
328
329.. py:method:: X509.set_issuer(issuer)
330
331 Set the issuer of the certificate to *issuer*.
332
333
334.. py:method:: X509.set_pubkey(pkey)
335
336 Set the public key of the certificate to *pkey*.
337
338
339.. py:method:: X509.set_serial_number(serialno)
340
341 Set the serial number of the certificate to *serialno*.
342
343
344.. py:method:: X509.set_subject(subject)
345
346 Set the subject of the certificate to *subject*.
347
348
349.. py:method:: X509.set_version(version)
350
351 Set the certificate version to *version*.
352
353
354.. py:method:: X509.sign(pkey, digest)
355
356 Sign the certificate, using the key *pkey* and the message digest algorithm
357 identified by the string *digest*.
358
359
360.. py:method:: X509.subject_name_hash()
361
362 Return the hash of the certificate subject.
363
364.. py:method:: X509.digest(digest_name)
365
366 Return a digest of the certificate, using the *digest_name* method.
367 *digest_name* must be a string describing a digest algorithm supported
368 by OpenSSL (by EVP_get_digestbyname, specifically). For example,
369 :py:const:`"md5"` or :py:const:`"sha1"`.
370
371
372.. py:method:: X509.add_extensions(extensions)
373
374 Add the extensions in the sequence *extensions* to the certificate.
375
376
377.. py:method:: X509.get_extension_count()
378
379 Return the number of extensions on this certificate.
380
381 .. versionadded:: 0.12
382
383
384.. py:method:: X509.get_extension(index)
385
386 Retrieve the extension on this certificate at the given index.
387
388 Extensions on a certificate are kept in order. The index parameter selects
389 which extension will be returned. The returned object will be an
390 :py:class:`X509Extension` instance.
391
392 .. versionadded:: 0.12
393
394
395.. _openssl-x509name:
396
397X509Name objects
398----------------
399
400X509Name objects have the following methods:
401
402.. py:method:: X509Name.hash()
403
404 Return an integer giving the first four bytes of the MD5 digest of the DER
405 representation of the name.
406
407
408.. py:method:: X509Name.der()
409
410 Return a string giving the DER representation of the name.
411
412
413.. py:method:: X509Name.get_components()
414
415 Return a list of two-tuples of strings giving the components of the name.
416
417
418X509Name objects have the following members:
419
420.. py:attribute:: X509Name.countryName
421
422 The country of the entity. :py:attr:`C` may be used as an alias for
423 :py:attr:`countryName`.
424
425
426.. py:attribute:: X509Name.stateOrProvinceName
427
428 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 -0400429 :py:attr:`stateOrProvinceName`.
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900430
431
432.. py:attribute:: X509Name.localityName
433
434 The locality of the entity. :py:attr:`L` may be used as an alias for
435 :py:attr:`localityName`.
436
437
438.. py:attribute:: X509Name.organizationName
439
440 The organization name of the entity. :py:attr:`O` may be used as an alias for
441 :py:attr:`organizationName`.
442
443
444.. py:attribute:: X509Name.organizationalUnitName
445
446 The organizational unit of the entity. :py:attr:`OU` may be used as an alias for
447 :py:attr:`organizationalUnitName`.
448
449
450.. py:attribute:: X509Name.commonName
451
452 The common name of the entity. :py:attr:`CN` may be used as an alias for
453 :py:attr:`commonName`.
454
455
456.. py:attribute:: X509Name.emailAddress
457
458 The e-mail address of the entity.
459
460
461.. _openssl-x509req:
462
463X509Req objects
464---------------
465
466X509Req objects have the following methods:
467
468.. py:method:: X509Req.get_pubkey()
469
470 Return a :py:class:`PKey` object representing the public key of the certificate request.
471
472
473.. py:method:: X509Req.get_subject()
474
475 Return an :py:class:`X509Name` object representing the subject of the certificate.
476
477
478.. py:method:: X509Req.set_pubkey(pkey)
479
480 Set the public key of the certificate request to *pkey*.
481
482
483.. py:method:: X509Req.sign(pkey, digest)
484
485 Sign the certificate request, using the key *pkey* and the message digest
486 algorithm identified by the string *digest*.
487
488
489.. py:method:: X509Req.verify(pkey)
490
491 Verify a certificate request using the public key *pkey*.
492
493
494.. py:method:: X509Req.set_version(version)
495
496 Set the version (RFC 2459, 4.1.2.1) of the certificate request to
497 *version*.
498
499
500.. py:method:: X509Req.get_version()
501
502 Get the version (RFC 2459, 4.1.2.1) of the certificate request.
503
504
Jean-Paul Calderone26e07d62014-03-02 08:08:23 -0500505.. py:method:: X509Req.get_extensions()
506
507 Get extensions to the request.
508
509 .. versionadded:: 0.15
510
511
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900512.. _openssl-x509store:
513
514X509Store objects
515-----------------
516
Laurens Van Houtven8aeafdd2014-06-17 15:33:42 +0200517.. autoclass:: X509Store
518 :members:
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900519
520.. _openssl-pkey:
521
522PKey objects
523------------
524
525The PKey object has the following methods:
526
Jonathan Ballet6381da32011-07-20 16:43:38 +0900527.. py:method:: PKey.bits()
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900528
529 Return the number of bits of the key.
530
531
Jonathan Ballet6381da32011-07-20 16:43:38 +0900532.. py:method:: PKey.generate_key(type, bits)
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900533
534 Generate a public/private key pair of the type *type* (one of
535 :py:const:`TYPE_RSA` and :py:const:`TYPE_DSA`) with the size *bits*.
536
537
Jonathan Ballet6381da32011-07-20 16:43:38 +0900538.. py:method:: PKey.type()
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900539
540 Return the type of the key.
541
542
Jonathan Ballet6381da32011-07-20 16:43:38 +0900543.. py:method:: PKey.check()
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900544
545 Check the consistency of this key, returning True if it is consistent and
546 raising an exception otherwise. This is only valid for RSA keys. See the
547 OpenSSL RSA_check_key man page for further limitations.
548
549
550.. _openssl-pkcs7:
551
552PKCS7 objects
553-------------
554
555PKCS7 objects have the following methods:
556
Jonathan Ballet6381da32011-07-20 16:43:38 +0900557.. py:method:: PKCS7.type_is_signed()
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900558
559 FIXME
560
561
Jonathan Ballet6381da32011-07-20 16:43:38 +0900562.. py:method:: PKCS7.type_is_enveloped()
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900563
564 FIXME
565
566
Jonathan Ballet6381da32011-07-20 16:43:38 +0900567.. py:method:: PKCS7.type_is_signedAndEnveloped()
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900568
569 FIXME
570
571
Jonathan Ballet6381da32011-07-20 16:43:38 +0900572.. py:method:: PKCS7.type_is_data()
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900573
574 FIXME
575
576
Jonathan Ballet6381da32011-07-20 16:43:38 +0900577.. py:method:: PKCS7.get_type_name()
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900578
579 Get the type name of the PKCS7.
580
581
582.. _openssl-pkcs12:
583
584PKCS12 objects
585--------------
586
587PKCS12 objects have the following methods:
588
Jonathan Ballet6381da32011-07-20 16:43:38 +0900589.. py:method:: PKCS12.export([passphrase=None][, iter=2048][, maciter=1])
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900590
591 Returns a PKCS12 object as a string.
592
593 The optional *passphrase* must be a string not a callback.
594
595 See also the man page for the C function :py:func:`PKCS12_create`.
596
597
598.. py:method:: PKCS12.get_ca_certificates()
599
600 Return CA certificates within the PKCS12 object as a tuple. Returns
601 :py:const:`None` if no CA certificates are present.
602
603
604.. py:method:: PKCS12.get_certificate()
605
606 Return certificate portion of the PKCS12 structure.
607
608
609.. py:method:: PKCS12.get_friendlyname()
610
611 Return friendlyName portion of the PKCS12 structure.
612
613
614.. py:method:: PKCS12.get_privatekey()
615
616 Return private key portion of the PKCS12 structure
617
618
619.. py:method:: PKCS12.set_ca_certificates(cacerts)
620
621 Replace or set the CA certificates within the PKCS12 object with the sequence *cacerts*.
622
623 Set *cacerts* to :py:const:`None` to remove all CA certificates.
624
625
626.. py:method:: PKCS12.set_certificate(cert)
627
628 Replace or set the certificate portion of the PKCS12 structure.
629
630
631.. py:method:: PKCS12.set_friendlyname(name)
632
633 Replace or set the friendlyName portion of the PKCS12 structure.
634
635
636.. py:method:: PKCS12.set_privatekey(pkey)
637
638 Replace or set private key portion of the PKCS12 structure
639
640
641.. _openssl-509ext:
642
643X509Extension objects
644---------------------
645
646X509Extension objects have several methods:
647
648.. py:method:: X509Extension.get_critical()
649
650 Return the critical field of the extension object.
651
652
653.. py:method:: X509Extension.get_short_name()
654
655 Retrieve the short descriptive name for this extension.
656
657 The result is a byte string like :py:const:`basicConstraints`.
658
659 .. versionadded:: 0.12
660
661
662.. py:method:: X509Extension.get_data()
663
664 Retrieve the data for this extension.
665
666 The result is the ASN.1 encoded form of the extension data as a byte string.
667
668 .. versionadded:: 0.12
669
670
671.. _openssl-netscape-spki:
672
673NetscapeSPKI objects
674--------------------
675
676NetscapeSPKI objects have the following methods:
677
678.. py:method:: NetscapeSPKI.b64_encode()
679
680 Return a base64-encoded string representation of the object.
681
682
683.. py:method:: NetscapeSPKI.get_pubkey()
684
685 Return the public key of object.
686
687
688.. py:method:: NetscapeSPKI.set_pubkey(key)
689
690 Set the public key of the object to *key*.
691
692
693.. py:method:: NetscapeSPKI.sign(key, digest_name)
694
695 Sign the NetscapeSPKI object using the given *key* and *digest_name*.
696 *digest_name* must be a string describing a digest algorithm supported by
697 OpenSSL (by EVP_get_digestbyname, specifically). For example,
698 :py:const:`"md5"` or :py:const:`"sha1"`.
699
700
701.. py:method:: NetscapeSPKI.verify(key)
702
703 Verify the NetscapeSPKI object using the given *key*.
704
705
706.. _crl:
707
708CRL objects
709-----------
710
711CRL objects have the following methods:
712
713.. py:method:: CRL.add_revoked(revoked)
714
715 Add a Revoked object to the CRL, by value not reference.
716
717
718.. py:method:: CRL.export(cert, key[, type=FILETYPE_PEM][, days=100])
719
720 Use *cert* and *key* to sign the CRL and return the CRL as a string.
721 *days* is the number of days before the next CRL is due.
722
723
724.. py:method:: CRL.get_revoked()
725
726 Return a tuple of Revoked objects, by value not reference.
727
728
729.. _revoked:
730
731Revoked objects
732---------------
733
734Revoked objects have the following methods:
735
736.. py:method:: Revoked.all_reasons()
737
738 Return a list of all supported reasons.
739
740
741.. py:method:: Revoked.get_reason()
742
743 Return the revocation reason as a str. Can be
744 None, which differs from "Unspecified".
745
746
747.. py:method:: Revoked.get_rev_date()
748
749 Return the revocation date as a str.
750 The string is formatted as an ASN1 GENERALIZEDTIME.
751
752
753.. py:method:: Revoked.get_serial()
754
755 Return a str containing a hex number of the serial of the revoked certificate.
756
757
758.. py:method:: Revoked.set_reason(reason)
759
760 Set the revocation reason. *reason* must be None or a string, but the
761 values are limited. Spaces and case are ignored. See
762 :py:meth:`all_reasons`.
763
764
765.. py:method:: Revoked.set_rev_date(date)
766
767 Set the revocation date.
768 The string is formatted as an ASN1 GENERALIZEDTIME.
769
770
771.. py:method:: Revoked.set_serial(serial)
772
773 *serial* is a string containing a hex number of the serial of the revoked certificate.