.. _openssl-crypto: :py:mod:`crypto` --- Generic cryptographic module ================================================= .. py:module:: OpenSSL.crypto :synopsis: Generic cryptographic module .. py:data:: X509Type See :py:class:`X509`. .. py:class:: X509() A class representing X.509 certificates. .. py:data:: X509NameType See :py:class:`X509Name`. .. py:class:: X509Name(x509name) A class representing X.509 Distinguished Names. This constructor creates a copy of *x509name* which should be an instance of :py:class:`X509Name`. .. py:data:: X509ReqType See :py:class:`X509Req`. .. py:class:: X509Req() A class representing X.509 certificate requests. .. py:data:: X509StoreType A Python type object representing the X509Store object type. .. py:data:: PKeyType See :py:class:`PKey`. .. py:class:: PKey() A class representing DSA or RSA keys. .. py:data:: PKCS7Type A Python type object representing the PKCS7 object type. .. py:data:: PKCS12Type A Python type object representing the PKCS12 object type. .. py:data:: X509ExtensionType See :py:class:`X509Extension`. .. py:class:: X509Extension(typename, critical, value[, subject][, issuer]) A class representing an X.509 v3 certificate extensions. See http://openssl.org/docs/apps/x509v3_config.html#STANDARD_EXTENSIONS for *typename* strings and their options. Optional parameters *subject* and *issuer* must be X509 objects. .. py:data:: NetscapeSPKIType See :py:class:`NetscapeSPKI`. .. py:class:: NetscapeSPKI([enc]) A class representing Netscape SPKI objects. If the *enc* argument is present, it should be a base64-encoded string representing a NetscapeSPKI object, as returned by the :py:meth:`b64_encode` method. .. py:class:: CRL() A class representing Certifcate Revocation List objects. .. py:class:: Revoked() A class representing Revocation objects of CRL. .. py:data:: FILETYPE_PEM FILETYPE_ASN1 File type constants. .. py:data:: TYPE_RSA TYPE_DSA Key type constants. .. py:exception:: Error Generic exception used in the :py:mod:`.crypto` module. .. py:function:: get_elliptic_curves Return a set of objects representing the elliptic curves supported in the OpenSSL build in use. The curve objects have a :py:class:`unicode` ``name`` attribute by which they identify themselves. The curve objects are useful as values for the argument accepted by :py:meth:`Context.set_tmp_ecdh` to specify which elliptical curve should be used for ECDHE key exchange. .. py:function:: get_elliptic_curve Return a single curve object selected by name. See :py:func:`get_elliptic_curves` for information about curve objects. If the named curve is not supported then :py:class:`ValueError` is raised. .. py:function:: dump_certificate(type, cert) Dump the certificate *cert* into a buffer string encoded with the type *type*. .. py:function:: dump_certificate_request(type, req) Dump the certificate request *req* into a buffer string encoded with the type *type*. .. py:function:: dump_privatekey(type, pkey[, cipher, passphrase]) Dump the private key *pkey* into a buffer string encoded with the type *type*, optionally (if *type* is :py:const:`FILETYPE_PEM`) encrypting it using *cipher* and *passphrase*. *passphrase* must be either a string or a callback for providing the pass phrase. .. py:function:: load_certificate(type, buffer) Load a certificate (X509) from the string *buffer* encoded with the type *type*. .. py:function:: load_certificate_request(type, buffer) Load a certificate request (X509Req) from the string *buffer* encoded with the type *type*. .. py:function:: load_privatekey(type, buffer[, passphrase]) Load a private key (PKey) from the string *buffer* encoded with the type *type* (must be one of :py:const:`FILETYPE_PEM` and :py:const:`FILETYPE_ASN1`). *passphrase* must be either a string or a callback for providing the pass phrase. .. py:function:: load_crl(type, buffer) Load Certificate Revocation List (CRL) data from a string *buffer*. *buffer* encoded with the type *type*. The type *type* must either :py:const:`FILETYPE_PEM` or :py:const:`FILETYPE_ASN1`). .. py:function:: load_pkcs7_data(type, buffer) Load pkcs7 data from the string *buffer* encoded with the type *type*. .. py:function:: load_pkcs12(buffer[, passphrase]) Load pkcs12 data from the string *buffer*. If the pkcs12 structure is encrypted, a *passphrase* must be included. The MAC is always checked and thus required. See also the man page for the C function :py:func:`PKCS12_parse`. .. py:function:: sign(key, data, digest) Sign a data string using the given key and message digest. *key* is a :py:class:`PKey` instance. *data* is a ``str`` instance. *digest* is a ``str`` naming a supported message digest type, for example :py:const:`sha1`. .. versionadded:: 0.11 .. py:function:: verify(certificate, signature, data, digest) Verify the signature for a data string. *certificate* is a :py:class:`X509` instance corresponding to the private key which generated the signature. *signature* is a *str* instance giving the signature itself. *data* is a *str* instance giving the data to which the signature applies. *digest* is a *str* instance naming the message digest type of the signature, for example :py:const:`sha1`. .. versionadded:: 0.11 .. _openssl-x509: X509 objects ------------ X509 objects have the following methods: .. py:method:: X509.get_issuer() Return an X509Name object representing the issuer of the certificate. .. py:method:: X509.get_pubkey() Return a :py:class:`PKey` object representing the public key of the certificate. .. py:method:: X509.get_serial_number() Return the certificate serial number. .. py:method:: X509.get_signature_algorithm() Return the signature algorithm used in the certificate. If the algorithm is undefined, raise :py:data:`ValueError`. ..versionadded:: 0.13 .. py:method:: X509.get_subject() Return an :py:class:`X509Name` object representing the subject of the certificate. .. py:method:: X509.get_version() Return the certificate version. .. py:method:: X509.get_notBefore() Return a string giving the time before which the certificate is not valid. The string is formatted as an ASN1 GENERALIZEDTIME:: YYYYMMDDhhmmssZ YYYYMMDDhhmmss+hhmm YYYYMMDDhhmmss-hhmm If no value exists for this field, :py:data:`None` is returned. .. py:method:: X509.get_notAfter() Return a string giving the time after which the certificate is not valid. The string is formatted as an ASN1 GENERALIZEDTIME:: YYYYMMDDhhmmssZ YYYYMMDDhhmmss+hhmm YYYYMMDDhhmmss-hhmm If no value exists for this field, :py:data:`None` is returned. .. py:method:: X509.set_notBefore(when) Change the time before which the certificate is not valid. *when* is a string formatted as an ASN1 GENERALIZEDTIME:: YYYYMMDDhhmmssZ YYYYMMDDhhmmss+hhmm YYYYMMDDhhmmss-hhmm .. py:method:: X509.set_notAfter(when) Change the time after which the certificate is not valid. *when* is a string formatted as an ASN1 GENERALIZEDTIME:: YYYYMMDDhhmmssZ YYYYMMDDhhmmss+hhmm YYYYMMDDhhmmss-hhmm .. py:method:: X509.gmtime_adj_notBefore(time) Adjust the timestamp (in GMT) when the certificate starts being valid. .. py:method:: X509.gmtime_adj_notAfter(time) Adjust the timestamp (in GMT) when the certificate stops being valid. .. py:method:: X509.has_expired() Checks the certificate's time stamp against current time. Returns true if the certificate has expired and false otherwise. .. py:method:: X509.set_issuer(issuer) Set the issuer of the certificate to *issuer*. .. py:method:: X509.set_pubkey(pkey) Set the public key of the certificate to *pkey*. .. py:method:: X509.set_serial_number(serialno) Set the serial number of the certificate to *serialno*. .. py:method:: X509.set_subject(subject) Set the subject of the certificate to *subject*. .. py:method:: X509.set_version(version) Set the certificate version to *version*. .. py:method:: X509.sign(pkey, digest) Sign the certificate, using the key *pkey* and the message digest algorithm identified by the string *digest*. .. py:method:: X509.subject_name_hash() Return the hash of the certificate subject. .. py:method:: X509.digest(digest_name) Return a digest of the certificate, using the *digest_name* method. *digest_name* must be a string describing a digest algorithm supported by OpenSSL (by EVP_get_digestbyname, specifically). For example, :py:const:`"md5"` or :py:const:`"sha1"`. .. py:method:: X509.add_extensions(extensions) Add the extensions in the sequence *extensions* to the certificate. .. py:method:: X509.get_extension_count() Return the number of extensions on this certificate. .. versionadded:: 0.12 .. py:method:: X509.get_extension(index) Retrieve the extension on this certificate at the given index. Extensions on a certificate are kept in order. The index parameter selects which extension will be returned. The returned object will be an :py:class:`X509Extension` instance. .. versionadded:: 0.12 .. _openssl-x509name: X509Name objects ---------------- X509Name objects have the following methods: .. py:method:: X509Name.hash() Return an integer giving the first four bytes of the MD5 digest of the DER representation of the name. .. py:method:: X509Name.der() Return a string giving the DER representation of the name. .. py:method:: X509Name.get_components() Return a list of two-tuples of strings giving the components of the name. X509Name objects have the following members: .. py:attribute:: X509Name.countryName The country of the entity. :py:attr:`C` may be used as an alias for :py:attr:`countryName`. .. py:attribute:: X509Name.stateOrProvinceName The state or province of the entity. :py:attr:`ST` may be used as an alias for :py:attr:`stateOrProvinceName`. .. py:attribute:: X509Name.localityName The locality of the entity. :py:attr:`L` may be used as an alias for :py:attr:`localityName`. .. py:attribute:: X509Name.organizationName The organization name of the entity. :py:attr:`O` may be used as an alias for :py:attr:`organizationName`. .. py:attribute:: X509Name.organizationalUnitName The organizational unit of the entity. :py:attr:`OU` may be used as an alias for :py:attr:`organizationalUnitName`. .. py:attribute:: X509Name.commonName The common name of the entity. :py:attr:`CN` may be used as an alias for :py:attr:`commonName`. .. py:attribute:: X509Name.emailAddress The e-mail address of the entity. .. _openssl-x509req: X509Req objects --------------- X509Req objects have the following methods: .. py:method:: X509Req.get_pubkey() Return a :py:class:`PKey` object representing the public key of the certificate request. .. py:method:: X509Req.get_subject() Return an :py:class:`X509Name` object representing the subject of the certificate. .. py:method:: X509Req.set_pubkey(pkey) Set the public key of the certificate request to *pkey*. .. py:method:: X509Req.sign(pkey, digest) Sign the certificate request, using the key *pkey* and the message digest algorithm identified by the string *digest*. .. py:method:: X509Req.verify(pkey) Verify a certificate request using the public key *pkey*. .. py:method:: X509Req.set_version(version) Set the version (RFC 2459, 4.1.2.1) of the certificate request to *version*. .. py:method:: X509Req.get_version() Get the version (RFC 2459, 4.1.2.1) of the certificate request. .. py:method:: X509Req.get_extensions() Get extensions to the request. .. versionadded:: 0.15 .. _openssl-x509store: X509Store objects ----------------- The X509Store object has currently just one method: .. py:method:: X509Store.add_cert(cert) Add the certificate *cert* to the certificate store. .. _openssl-pkey: PKey objects ------------ The PKey object has the following methods: .. py:method:: PKey.bits() Return the number of bits of the key. .. py:method:: PKey.generate_key(type, bits) Generate a public/private key pair of the type *type* (one of :py:const:`TYPE_RSA` and :py:const:`TYPE_DSA`) with the size *bits*. .. py:method:: PKey.type() Return the type of the key. .. py:method:: PKey.check() Check the consistency of this key, returning True if it is consistent and raising an exception otherwise. This is only valid for RSA keys. See the OpenSSL RSA_check_key man page for further limitations. .. _openssl-pkcs7: PKCS7 objects ------------- PKCS7 objects have the following methods: .. py:method:: PKCS7.type_is_signed() FIXME .. py:method:: PKCS7.type_is_enveloped() FIXME .. py:method:: PKCS7.type_is_signedAndEnveloped() FIXME .. py:method:: PKCS7.type_is_data() FIXME .. py:method:: PKCS7.get_type_name() Get the type name of the PKCS7. .. _openssl-pkcs12: PKCS12 objects -------------- PKCS12 objects have the following methods: .. py:method:: PKCS12.export([passphrase=None][, iter=2048][, maciter=1]) Returns a PKCS12 object as a string. The optional *passphrase* must be a string not a callback. See also the man page for the C function :py:func:`PKCS12_create`. .. py:method:: PKCS12.get_ca_certificates() Return CA certificates within the PKCS12 object as a tuple. Returns :py:const:`None` if no CA certificates are present. .. py:method:: PKCS12.get_certificate() Return certificate portion of the PKCS12 structure. .. py:method:: PKCS12.get_friendlyname() Return friendlyName portion of the PKCS12 structure. .. py:method:: PKCS12.get_privatekey() Return private key portion of the PKCS12 structure .. py:method:: PKCS12.set_ca_certificates(cacerts) Replace or set the CA certificates within the PKCS12 object with the sequence *cacerts*. Set *cacerts* to :py:const:`None` to remove all CA certificates. .. py:method:: PKCS12.set_certificate(cert) Replace or set the certificate portion of the PKCS12 structure. .. py:method:: PKCS12.set_friendlyname(name) Replace or set the friendlyName portion of the PKCS12 structure. .. py:method:: PKCS12.set_privatekey(pkey) Replace or set private key portion of the PKCS12 structure .. _openssl-509ext: X509Extension objects --------------------- X509Extension objects have several methods: .. py:method:: X509Extension.get_critical() Return the critical field of the extension object. .. py:method:: X509Extension.get_short_name() Retrieve the short descriptive name for this extension. The result is a byte string like :py:const:`basicConstraints`. .. versionadded:: 0.12 .. py:method:: X509Extension.get_data() Retrieve the data for this extension. The result is the ASN.1 encoded form of the extension data as a byte string. .. versionadded:: 0.12 .. _openssl-netscape-spki: NetscapeSPKI objects -------------------- NetscapeSPKI objects have the following methods: .. py:method:: NetscapeSPKI.b64_encode() Return a base64-encoded string representation of the object. .. py:method:: NetscapeSPKI.get_pubkey() Return the public key of object. .. py:method:: NetscapeSPKI.set_pubkey(key) Set the public key of the object to *key*. .. py:method:: NetscapeSPKI.sign(key, digest_name) Sign the NetscapeSPKI object using the given *key* and *digest_name*. *digest_name* must be a string describing a digest algorithm supported by OpenSSL (by EVP_get_digestbyname, specifically). For example, :py:const:`"md5"` or :py:const:`"sha1"`. .. py:method:: NetscapeSPKI.verify(key) Verify the NetscapeSPKI object using the given *key*. .. _crl: CRL objects ----------- CRL objects have the following methods: .. py:method:: CRL.add_revoked(revoked) Add a Revoked object to the CRL, by value not reference. .. py:method:: CRL.export(cert, key[, type=FILETYPE_PEM][, days=100]) Use *cert* and *key* to sign the CRL and return the CRL as a string. *days* is the number of days before the next CRL is due. .. py:method:: CRL.get_revoked() Return a tuple of Revoked objects, by value not reference. .. _revoked: Revoked objects --------------- Revoked objects have the following methods: .. py:method:: Revoked.all_reasons() Return a list of all supported reasons. .. py:method:: Revoked.get_reason() Return the revocation reason as a str. Can be None, which differs from "Unspecified". .. py:method:: Revoked.get_rev_date() Return the revocation date as a str. The string is formatted as an ASN1 GENERALIZEDTIME. .. py:method:: Revoked.get_serial() Return a str containing a hex number of the serial of the revoked certificate. .. py:method:: Revoked.set_reason(reason) Set the revocation reason. *reason* must be None or a string, but the values are limited. Spaces and case are ignored. See :py:meth:`all_reasons`. .. py:method:: Revoked.set_rev_date(date) Set the revocation date. The string is formatted as an ASN1 GENERALIZEDTIME. .. py:method:: Revoked.set_serial(serial) *serial* is a string containing a hex number of the serial of the revoked certificate.