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