Python OpenSSL Manual

     __________________________________________________________________

                            Python OpenSSL Manual

                               Martin Sj�gren

                              [email protected]

  Abstract:

   This module is a rather thin wrapper around (a subset of) the OpenSSL

   library. With thin wrapper I mean that a lot of the object methods do

   nothing more than calling a corresponding function in the OpenSSL

   library.

Contents

     * 1 Introduction

     * 2 Building and Installing

          + 2.1 Building the Module on a Unix System

          + 2.2 Building the Module on a Windows System

     * 3 OpenSSL -- Python interface to OpenSSL

          + 3.1 crypto -- Generic cryptographic module

          + 3.2 rand -- An interface to the OpenSSL pseudo random number

            generator

          + 3.3 SSL -- An interface to the SSL-specific parts of OpenSSL

     * 4 Internals

          + 4.1 Exceptions

          + 4.2 Callbacks

          + 4.3 Acessing Socket Methods

                                 1 Introduction

   The reason pyOpenSSL was created is that the SSL support in the socket

   module in Python 2.1 (the contemporary version of Python when the

   pyOpenSSL project was begun) was severely limited. Other OpenSSL

   wrappers for Python at the time were also limited, though in different

   ways. Unfortunately, Python's standard library SSL support has remained

   weak, although other packages (such as M2Crypto^1) have made great

   advances and now equal or exceed pyOpenSSL's functionality.

   The reason pyOpenSSL continues to be maintained is that there is a

   significant user community around it, as well as a large amount of

   software which depends on it. It is a great benefit to many people for

   pyOpenSSL to continue to exist and advance.

                           2 Building and Installing

   These instructions can also be found in the file INSTALL.

   I have tested this on Debian Linux systems (woody and sid), Solaris 2.6

   and 2.7. Others have successfully compiled it on Windows and NT.

2.1 Building the Module on a Unix System

   pyOpenSSL uses distutils, so there really shouldn't be any problems. To

   build the library:

python setup.py build

   If your OpenSSL header files aren't in /usr/include, you may need to

   supply the -I flag to let the setup script know where to look. The same

   goes for the libraries of course, use the -L flag. Note that build

   won't accept these flags, so you have to run first build_ext and then

   build! Example:

python setup.py build_ext -I/usr/local/ssl/include -L/usr/local/ssl/lib

python setup.py build

   Now you should have a directory called OpenSSL that contains e.g.

   SSL.so and __init__.py somewhere in the build dicrectory, so just:

python setup.py install

   If you, for some arcane reason, don't want the module to appear in the

   site-packages directory, use the --prefix option.

   You can, of course, do

python setup.py --help

   to find out more about how to use the script.

2.2 Building the Module on a Windows System

   Big thanks to Itamar Shtull-Trauring and Oleg Orlov for their help with

   Windows build instructions. Same as for Unix systems, we have to

   separate the build_ext and the build.

   Building the library:

setup.py build_ext -I ...\openssl\inc32 -L ...\openssl\out32dll

setup.py build

   Where ...\openssl is of course the location of your OpenSSL

   installation.

   Installation is the same as for Unix systems:

setup.py install

   And similarily, you can do

setup.py --help

   to get more information.

                    3 OpenSSL -- Python interface to OpenSSL

   This package provides a high-level interface to the functions in the

   OpenSSL library. The following modules are defined:

   crypto

          Generic cryptographic module. Note that if anything is

          incomplete, this module is!

   rand

          An interface to the OpenSSL pseudo random number generator.

   SSL

          An interface to the SSL-specific parts of OpenSSL.

3.1 crypto -- Generic cryptographic module

   X509Type

          A Python type object representing the X509 object type.

   X509()

          Factory function that creates an X509 object.

   X509NameType

          A Python type object representing the X509Name object type.

   X509Name(x509name)

          Factory function that creates a copy of x509name.

   X509ReqType

          A Python type object representing the X509Req object type.

   X509Req()

          Factory function that creates an X509Req object.

   X509StoreType

          A Python type object representing the X509Store object type.

   PKeyType

          A Python type object representing the PKey object type.

   PKey()

          Factory function that creates a PKey object.

   PKCS7Type

          A Python type object representing the PKCS7 object type.

   PKCS12Type

          A Python type object representing the PKCS12 object type.

   X509ExtensionType

          A Python type object representing the X509Extension object type.

   X509Extension(typename, critical, value)

          Factory function that creates a X509Extension object.

   NetscapeSPKIType

          A Python type object representing the NetscapeSPKI object type.

   NetscapeSPKI([enc])

          Factory function that creates a NetscapeSPKI object. If the enc

          argument is present, it should be a base64-encoded string

          representing a NetscapeSPKI object, as returned by the

          b64_encode method.

   FILETYPE_PEM

   FILETYPE_ASN1

          File type constants.

   TYPE_RSA

   TYPE_DSA

          Key type constants.

   exception Error

          Generic exception used in the crypto module.

   dump_certificate(type, cert)

          Dump the certificate cert into a buffer string encoded with the

          type type.

   dump_certificate_request(type, req)

          Dump the certificate request req into a buffer string encoded

          with the type type.

   dump_privatekey(type, pkey[, cipher, passphrase])

          Dump the private key pkey into a buffer string encoded with the

          type type, optionally (if type is FILETYPE_PEM) encrypting it

          using cipher and passphrase.

          passphrase must be either a string or a callback for providing

          the pass phrase.

   load_certificate(type, buffer)

          Load a certificate (X509) from the string buffer encoded with

          the type type.

   load_certificate_request(type, buffer)

          Load a certificate request (X509Req) from the string buffer

          encoded with the type type.

   load_privatekey(type, buffer[, passphrase])

          Load a private key (PKey) from the string buffer encoded with

          the type type (must be one of FILETYPE_PEM and FILETYPE_ASN1).

          passphrase must be either a string or a callback for providing

          the pass phrase.

   load_pkcs7_data(type, buffer)

          Load pkcs7 data from the string buffer encoded with the type

          type.

   load_pkcs12(buffer[, passphrase])

          Load pkcs12 data from the string buffer. If the pkcs12 structure

          is encrypted, a passphrase must be included.

  3.1.1 X509 objects

   X509 objects have the following methods:

   get_issuer()

          Return an X509Name object representing the issuer of the

          certificate.

   get_pubkey()

          Return a PKey object representing the public key of the

          certificate.

   get_serial_number()

          Return the certificate serial number.

   get_subject()

          Return an X509Name object representing the subject of the

          certificate.

   get_version()

          Return the certificate version.

   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, None is returned.

   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, None is returned.

   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

   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

   gmtime_adj_notBefore(time)

          Adjust the timestamp (in GMT) when the certificate starts being

          valid.

   gmtime_adj_notAfter(time)

          Adjust the timestamp (in GMT) when the certificate stops being

          valid.

   has_expired()

          Checks the certificate's time stamp against current time.

          Returns true if the certificate has expired and false otherwise.

   set_issuer(issuer)

          Set the issuer of the certificate to issuer.

   set_pubkey(pkey)

          Set the public key of the certificate to pkey.

   set_serial_number(serialno)

          Set the serial number of the certificate to serialno.

   set_subject(subject)

          Set the subject of the certificate to subject.

   set_version(version)

          Set the certificate version to version.

   sign(pkey, digest)

          Sign the certificate, using the key pkey and the message digest

          algorithm identified by the string digest.

   subject_name_hash()

          Return the hash of the certificate subject.

   digest(digest_name)

          Return a digest of the certificate, using the digest_name

          method.

   add_extensions(extensions)

          Add the extensions in the sequence extensions to the

          certificate.

  3.1.2 X509Name objects

   X509Name objects have the following methods:

   hash()

          Return an integer giving the first four bytes of the MD5 digest

          of the DER representation of the name.

   der()

          Return a string giving the DER representation of the name.

   get_components()

          Return a list of two-tuples of strings giving the components of

          the name.

   X509Name objects have the following members:

   countryName

          The country of the entity. C may be used as an alias for

          countryName.

   stateOrProvinceName

          The state or province of the entity. ST may be used as an alias

          for stateOrProvinceName�

   localityName

          The locality of the entity. L may be used as an alias for

          localityName.

   organizationName

          The organization name of the entity. O may be used as an alias

          for organizationName.

   organizationalUnitName

          The organizational unit of the entity. OU may be used as an

          alias for organizationalUnitName.

   commonName

          The common name of the entity. CN may be used as an alias for

          commonName.

   emailAddress

          The e-mail address of the entity.

  3.1.3 X509Req objects

   X509Req objects have the following methods:

   get_pubkey()

          Return a PKey object representing the public key of the

          certificate request.

   get_subject()

          Return an X509Name object representing the subject of the

          certificate.

   set_pubkey(pkey)

          Set the public key of the certificate request to pkey.

   sign(pkey, digest)

          Sign the certificate request, using the key pkey and the message

          digest algorithm identified by the string digest.

   verify(pkey)

          Verify a certificate request using the public key pkey.

  3.1.4 X509Store objects

   The X509Store object has currently just one method:

   add_cert(cert)

          Add the certificate cert to the certificate store.

  3.1.5 PKey objects

   The PKey object has the following methods:

   bits()

          Return the number of bits of the key.

   generate_key(type, bits)

          Generate a public/private key pair of the type type (one of

          TYPE_RSA and TYPE_DSA) with the size bits.

   type()

          Return the type of the key.

  3.1.6 PKCS7 objects

   PKCS7 objects have the following methods:

   type_is_signed()

          FIXME

   type_is_enveloped()

          FIXME

   type_is_signedAndEnveloped()

          FIXME

   type_is_data()

          FIXME

   get_type_name()

          Get the type name of the PKCS7.

  3.1.7 PKCS12 objects

   PKCS12 objects have the following methods:

   get_certificate()

          Return certificate portion of the PKCS12 structure.

   get_privatekey()

          Return private key portion of the PKCS12 structure

   get_ca_certificates()

          Return CA certificates within the PKCS12 object as a tuple.

          Returns None if no CA certificates are present.

  3.1.8 X509Extension objects

   X509Extension objects currently only have one method:

   get_critical()

          Return the critical field of the extension object.

  3.1.9 NetscapeSPKI objects

   NetscapeSPKI objects have the following methods:

   b64_encode()

          Return a base64-encoded string representation of the object.

   get_pubkey()

          Return the public key of object.

   set_pubkey(key)

          Set the public key of the object to key.

   sign(key, digest_name)

          Sign the NetscapeSPKI object using the given key and

          digest_name.

   verify(key)

          Verify the NetscapeSPKI object using the given key.

3.2 rand -- An interface to the OpenSSL pseudo random number generator

   This module handles the OpenSSL pseudo random number generator (PRNG)

   and declares the following:

   add(string, entropy)

          Mix bytes from string into the PRNG state. The entropy argument

          is (the lower bound of) an estimate of how much randomness is

          contained in string, measured in bytes. For more information,

          see e.g. RFC 1750.

   egd(path[, bytes])

          Query the Entropy Gathering Daemon^2 on socket path for bytes

          bytes of random data and and uses add to seed the PRNG. The

          default value of bytes is 255.

   load_file(path[, bytes])

          Read bytes bytes (or all of it, if bytes is negative) of data

          from the file path to seed the PRNG. The default value of bytes

          is -1.

   screen()

          Add the current contents of the screen to the PRNG state.

          Availability: Windows.

   seed(string)

          This is equivalent to calling add with entropy as the length of

          the string.

   status()

          Returns true if the PRNG has been seeded with enough data, and

          false otherwise.

   write_file(path)

          Write a number of random bytes (currently 1024) to the file

          path. This file can then be used with load_file to seed the PRNG

          again.

3.3 SSL -- An interface to the SSL-specific parts of OpenSSL