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