Translate the Latex doc to Sphinx doc

Don't rely on the docstrings anymor, which aren't sufficient anyway to generate
this kind of documentation.

7 files changed, 1487 insertions, 1302 deletions

diff --git a/doc/api.rst b/doc/api.rst
index bcebd43..55a33ec 100644
--- a/doc/api.rst
+++ b/doc/api.rst
@@ -1,7 +1,14 @@
-API
-===
+.. py:module:: OpenSSL
 
-.. automodule:: OpenSSL
+
+.. _api-openssl:
+
+
+OpenSSL -- Python interface to OpenSSL
+======================================
+
+This package provides a high-level interface to the functions in the
+OpenSSL library. The following modules are defined:
 
 
 .. toctree::
@@ -9,4 +16,4 @@ API
 
    api/crypto
    api/rand
-   api/SSL
+   api/ssl
diff --git a/doc/api/SSL.rst b/doc/api/SSL.rst
deleted file mode 100644
index 248bc63..0000000
--- a/doc/api/SSL.rst
+++ /dev/null
@@ -1,13 +0,0 @@
-.. _openssl-ssl:
-
-OpenSSL.SSL module
-==================
-
-.. automodule:: OpenSSL.SSL
-   :members:
-
-.. autoclass:: OpenSSL.SSL.Context
-   :members:
-
-.. autoclass:: OpenSSL.SSL.Connection
-   :members:
diff --git a/doc/api/crypto.rst b/doc/api/crypto.rst
index 222431d..907bdf5 100644
--- a/doc/api/crypto.rst
+++ b/doc/api/crypto.rst
@@ -1,38 +1,753 @@
-OpenSSL.crypto module
-=====================
+.. py:module:: OpenSSL.crypto
 
+.. _api-openssl-crypto:
 
-.. automodule:: OpenSSL.crypto
-   :members:
+``crypto`` -- Generic cryptographic module
+==========================================
 
-.. autoclass:: OpenSSL.crypto.X509
-   :members:
 
-.. autoclass:: OpenSSL.crypto.X509Name
-   :members:
+.. py:data:: X509Type
 
-.. autoclass:: OpenSSL.crypto.X509Req
-   :members:
+    See :py:class:`X509`.
 
-.. autoclass:: OpenSSL.crypto.X509StoreType
-   :members:
 
-.. autoclass:: OpenSSL.crypto.PKey
-   :members:
+.. py:class:: X509()
 
-.. autoclass:: OpenSSL.crypto.PKCS7Type
-   :members:
+    A class representing X.509 certificates.
 
-.. autoclass:: OpenSSL.crypto.PKCS12
-   :members:
 
-.. autoclass:: OpenSSL.crypto.NetscapeSPKI
-   :members:
+.. py:data:: X509NameType
 
-.. autoclass:: OpenSSL.crypto.CRL
-   :members:
+    See :py:class:`X509Name`.
 
-.. autoclass:: OpenSSL.crypto.Revoked
-   :members:
 
+.. 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
+.. py:data:: FILETYPE_ASN1
+
+    File type constants.
+
+
+.. py:data:: TYPE_RSA
+.. py:data:: TYPE_DSA
+
+    Key type constants.
+
+
+.. py:exception:: Error
+
+    Generic exception used in the :py:mod:`.crypto` module.
+
+
+.. 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`.
+
+
+.. 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` ·
+
+.. Wut? Sphinx is not happy if there is no space between the ` and the . just
+    above...
+
+
+.. 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.
+
+
+.. _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:: Pkey.type_is_signed()
+
+    FIXME
+
+
+.. py:method:: Pkey.type_is_enveloped()
+
+    FIXME
+
+
+.. py:method:: Pkey.type_is_signedAndEnveloped()
+
+    FIXME
+
+
+.. py:method:: Pkey.type_is_data()
+
+    FIXME
+
+
+.. py:method:: Pkey.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.
diff --git a/doc/api/rand.rst b/doc/api/rand.rst
index 640cf85..b531254 100644
--- a/doc/api/rand.rst
+++ b/doc/api/rand.rst
@@ -1,6 +1,80 @@
-OpenSSL.rand module
-===================
+.. py:module:: OpenSSL.rand
 
+.. _api-openssl-rand:
 
-.. automodule:: OpenSSL.rand
-   :members:
+``rand`` -- An interface to the OpenSSL pseudo random number generator
+======================================================================
+
+This module handles the OpenSSL pseudo random number generator (PRNG) and
+declares the following:
+
+.. py:function:: 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`.
+
+
+.. py:function:: bytes(num_bytes)
+
+    Get some random bytes from the PRNG as a string.
+
+    This is a wrapper for the C function :py:func:`RAND_bytes`.
+
+
+.. py:function:: cleanup()
+
+    Erase the memory used by the PRNG.
+
+    This is a wrapper for the C function :py:func:`RAND_cleanup`.
+
+
+.. py:function:: egd(path[, bytes])
+
+    Query the Entropy Gathering Daemon [#entropy-gathering-daemon]_ on socket
+    *path* for *bytes* bytes of random data and uses :py:func:`add` to seed
+    the PRNG. The default value of *bytes* is 255.
+
+
+.. py:function:: 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.
+
+
+.. py:function:: screen()
+
+    Add the current contents of the screen to the PRNG state.
+
+    Availability: Windows.
+
+
+.. py:function:: seed(string)
+
+    This is equivalent to calling :py:func:`add` with *entropy* as the length
+    of the string.
+
+
+.. py:function:: status()
+
+    Returns true if the PRNG has been seeded with enough data, and false otherwise.
+
+
+.. py:function:: write_file(path)
+
+    Write a number of random bytes (currently 1024) to the file *path*. This
+    file can then be used with :py:func:`load_file` to seed the PRNG again.
+
+
+.. py:exception:: Error
+
+    If the current RAND method supports any errors, this is raised when needed.
+    The default method does not raise this when the entropy pool is depleted.
+
+    Whenever this exception is raised directly, it has a list of error messages
+    from the OpenSSL error queue, where each item is a tuple *(lib, function,
+    reason)*. Here *lib*, *function* and *reason* are all strings, describing
+    where and what the problem is. See :manpage:`err(3)` for more information.
+
+
+.. [#entropy-gathering-daemon] See http://www.lothar.com/tech/crypto/.
diff --git a/doc/api/ssl.rst b/doc/api/ssl.rst
new file mode 100644
index 0000000..76bb981
--- /dev/null
+++ b/doc/api/ssl.rst
@@ -0,0 +1,658 @@
+.. py:module:: OpenSSL.SSL
+
+.. _api-openssl-ssl:
+
+``SSL`` -- An interface to the SSL-specific parts of OpenSSL
+============================================================
+
+This module handles things specific to SSL. There are two objects defined:
+Context, Connection.
+
+.. py:data:: SSLv2_METHOD
+.. py:data:: SSLv3_METHOD
+.. py:data:: SSLv23_METHOD
+.. py:data:: TLSv1_METHOD
+
+    These constants represent the different SSL methods to use when creating a
+    context object.
+
+
+.. py:data:: VERIFY_NONE
+.. py:data:: VERIFY_PEER
+.. py:data:: VERIFY_FAIL_IF_NO_PEER_CERT
+
+    These constants represent the verification mode used by the Context
+    object's :py:meth:`set_verify` method.
+
+
+.. py:data:: FILETYPE_PEM
+.. py:data:: FILETYPE_ASN1
+
+    File type constants used with the :py:meth:`use_certificate_file` and
+    :py:meth:`use_privatekey_file` methods of Context objects.
+
+
+.. py:data:: OP_SINGLE_DH_USE
+.. py:data:: OP_EPHEMERAL_RSA
+.. py:data:: OP_NO_SSLv2
+.. py:data:: OP_NO_SSLv3
+.. py:data:: OP_NO_TLSv1
+
+    Constants used with :py:meth:`set_options` of Context objects.
+
+    :py:const:`OP_SINGLE_DH_USE` means to always create a new key when using
+    ephemeral Diffie-Hellman. :py:const:`OP_EPHEMERAL_RSA` means to always use
+    ephemeral RSA keys when doing RSA operations. :py:const:`OP_NO_SSLv2`,
+    :py:const:`OP_NO_SSLv3` and :py:const:`OP_NO_TLSv1` means to disable those
+    specific protocols. This is interesting if you're using e.g.
+    :py:const:`SSLv23_METHOD` to get an SSLv2-compatible handshake, but don't want
+    to use SSLv2.
+
+
+.. py:data:: SSLEAY_VERSION
+.. py:data:: SSLEAY_CFLAGS
+.. py:data:: SSLEAY_BUILT_ON
+.. py:data:: SSLEAY_PLATFORM
+.. py:data:: SSLEAY_DIR
+
+    Constants used with :py:meth:`SSLeay_version` to specify what OpenSSL version
+    information to retrieve.  See the man page for the :py:func:`SSLeay_version` C
+    API for details.
+
+
+.. py:data:: OPENSSL_VERSION_NUMBER
+
+    An integer giving the version number of the OpenSSL library used to build this
+    version of pyOpenSSL.  See the man page for the :py:func:`SSLeay_version` C API
+    for details.
+
+
+.. py:function:: SSLeay_version(type)
+
+    Retrieve a string describing some aspect of the underlying OpenSSL version.  The
+    type passed in should be one of the :py:const:`SSLEAY_*` constants defined in
+    this module.
+
+
+.. py:data:: ContextType
+
+    See :py:class:`Context`.
+
+
+.. py:class:: Context(method)
+
+    A class representing SSL contexts.  Contexts define the parameters of one or
+    more SSL connections.
+
+    *method* should be :py:const:`SSLv2_METHOD`, :py:const:`SSLv3_METHOD`,
+    :py:const:`SSLv23_METHOD` or :py:const:`TLSv1_METHOD`.
+
+
+.. py:data:: ConnectionType
+
+    See :py:class:`Connection`.
+
+
+.. py:class:: Connection(context, socket)
+
+    A class representing SSL connections.
+
+    *context* should be an instance of :py:class:`Context` and *socket*
+    should be a socket [#connection-context-socket]_  object.  *socket* may be
+    *None*; in this case, the Connection is created with a memory BIO: see
+    the :py:meth:`bio_read`, :py:meth:`bio_write`, and :py:meth:`bio_shutdown`
+    methods.
+
+.. py:exception:: Error
+
+    This exception is used as a base class for the other SSL-related
+    exceptions, but may also be raised directly.
+
+    Whenever this exception is raised directly, it has a list of error messages
+    from the OpenSSL error queue, where each item is a tuple *(lib, function,
+    reason)*. Here *lib*, *function* and *reason* are all strings, describing
+    where and what the problem is. See :manpage:`err(3)` for more information.
+
+
+.. py:exception:: ZeroReturnError
+
+    This exception matches the error return code
+    :py:data:`SSL_ERROR_ZERO_RETURN`, and is raised when the SSL Connection has
+    been closed. In SSL 3.0 and TLS 1.0, this only occurs if a closure alert has
+    occurred in the protocol, i.e.  the connection has been closed cleanly. Note
+    that this does not necessarily mean that the transport layer (e.g. a socket)
+    has been closed.
+
+    It may seem a little strange that this is an exception, but it does match an
+    :py:data:`SSL_ERROR` code, and is very convenient.
+
+
+.. py:exception:: WantReadError
+
+    The operation did not complete; the same I/O method should be called again
+    later, with the same arguments. Any I/O method can lead to this since new
+    handshakes can occur at any time.
+
+    The wanted read is for **dirty** data sent over the network, not the
+    **clean** data inside the tunnel.  For a socket based SSL connection,
+    **read** means data coming at us over the network.  Until that read
+    succeeds, the attempted :py:meth:`OpenSSL.SSL.Connection.recv`,
+    :py:meth:`OpenSSL.SSL.Connection.send`, or
+    :py:meth:`OpenSSL.SSL.Connection.do_handshake` is prevented or incomplete. You
+    probably want to :py:meth:`select()` on the socket before trying again.
+
+
+.. py:exception:: WantWriteError
+
+    See :py:exc:`WantReadError`.  The socket send buffer may be too full to
+    write more data.
+
+
+.. py:exception:: WantX509LookupError
+
+    The operation did not complete because an application callback has asked to be
+    called again. The I/O method should be called again later, with the same
+    arguments.
+
+    .. note:: This won't occur in this version, as there are no such
+        callbacks in this version.
+
+
+.. py:exception:: SysCallError
+
+    The :py:exc:`SysCallError` occurs when there's an I/O error and OpenSSL's
+    error queue does not contain any information. This can mean two things: An
+    error in the transport protocol, or an end of file that violates the protocol.
+    The parameter to the exception is always a pair *(errnum,
+    errstr)*.
+
+
+
+.. _openssl-context:
+
+Context objects
+---------------
+
+Context objects have the following methods:
+
+.. :py:class:: OpenSSL.SSL.Context
+
+.. py:method:: Context.check_privatekey()
+
+    Check if the private key (loaded with :py:meth:`use_privatekey`) matches the
+    certificate (loaded with :py:meth:`use_certificate`).  Returns
+    :py:data:`None` if they match, raises :py:exc:`Error` otherwise.
+
+
+.. py:method:: Context.get_app_data()
+
+    Retrieve application data as set by :py:meth:`set_app_data`.
+
+
+.. py:method:: Context.get_cert_store()
+
+    Retrieve the certificate store (a X509Store object) that the context uses.
+    This can be used to add "trusted" certificates without using the.
+    :py:meth:`load_verify_locations` method.
+
+
+.. py:method:: Context.get_timeout()
+
+    Retrieve session timeout, as set by :py:meth:`set_timeout`. The default is 300
+    seconds.
+
+
+.. py:method:: Context.get_verify_depth()
+
+    Retrieve the Context object's verify depth, as set by
+    :py:meth:`set_verify_depth`.
+
+
+.. py:method:: Context.get_verify_mode()
+
+    Retrieve the Context object's verify mode, as set by :py:meth:`set_verify`.
+
+
+.. py:method:: Context.load_client_ca(pemfile)
+
+    Read a file with PEM-formatted certificates that will be sent to the client
+    when requesting a client certificate.
+
+
+.. py:method:: Context.set_client_ca_list(certificate_authorities)
+
+    Replace the current list of preferred certificate signers that would be
+    sent to the client when requesting a client certificate with the
+    *certificate_authorities* sequence of :py:class:`OpenSSL.crypto.X509Name`'s.
+
+    .. versionadded:: 0.10
+
+
+.. py:method:: Context.add_client_ca(certificate_authority)
+
+    Extract a :py:class:`OpenSSL.crypto.X509Name` from the *certificate_authority*
+    :py:class:`OpenSSL.crypto.X509` certificate and add it to the list of preferred
+    certificate signers sent to the client when requesting a client certificate.
+
+    .. versionadded:: 0.10
+
+
+.. py:method:: Context.load_verify_locations(pemfile, capath)
+
+    Specify where CA certificates for verification purposes are located. These
+    are trusted certificates. Note that the certificates have to be in PEM
+    format.  If capath is passed, it must be a directory prepared using the
+    ``_rehash`` tool included with OpenSSL.  Either, but not both, of
+    *pemfile* or *capath* may be :py:data:`None`.
+
+
+.. py:method:: Context.set_default_verify_paths()
+
+    Specify that the platform provided CA certificates are to be used for
+    verification purposes.  This method may not work properly on OS X.
+
+
+.. py:method:: Context.load_tmp_dh(dhfile)
+
+    Load parameters for Ephemeral Diffie-Hellman from *dhfile*.
+
+
+.. py:method:: Context.set_app_data(data)
+
+    Associate *data* with this Context object. *data* can be retrieved
+    later using the :py:meth:`get_app_data` method.
+
+
+.. py:method:: Context.set_cipher_list(ciphers)
+
+    Set the list of ciphers to be used in this context. See the OpenSSL manual for
+    more information (e.g. :manpage:`ciphers(1)`)
+
+
+.. py:method:: Context.set_info_callback(callback)
+
+    Set the information callback to *callback*. This function will be called
+    from time to time during SSL handshakes.
+
+    *callback* should take three arguments: a Connection object and two
+    integers. The first integer specifies where in the SSL handshake the function
+    was called, and the other the return code from a (possibly failed) internal
+    function call.
+
+
+.. py:method:: Context.set_options(options)
+
+    Add SSL options. Options you have set before are not cleared!
+    This method should be used with the :py:const:`OP_*` constants.
+
+
+.. py:method:: Context.set_passwd_cb(callback[, userdata])
+
+    Set the passphrase callback to *callback*. This function will be called
+    when a private key with a passphrase is loaded. *callback* must accept
+    three positional arguments.  First, an integer giving the maximum length of
+    the passphrase it may return.  If the returned passphrase is longer than
+    this, it will be truncated.  Second, a boolean value which will be true if
+    the user should be prompted for the passphrase twice and the callback should
+    verify that the two values supplied are equal. Third, the value given as the
+    *userdata* parameter to :py:meth:`set_passwd_cb`.  If an error occurs,
+    *callback* should return a false value (e.g. an empty string).
+
+
+.. py:method:: Context.set_session_id(name)
+
+    Set the context *name* within which a session can be reused for this
+    Context object. This is needed when doing session resumption, because there is
+    no way for a stored session to know which Context object it is associated with.
+    *name* may be any binary data.
+
+
+.. py:method:: Context.set_timeout(timeout)
+
+    Set the timeout for newly created sessions for this Context object to
+    *timeout*. *timeout* must be given in (whole) seconds. The default
+    value is 300 seconds. See the OpenSSL manual for more information (e.g.
+    :manpage:`SSL_CTX_set_timeout(3)`).
+
+
+.. py:method:: Context.set_verify(mode, callback)
+
+    Set the verification flags for this Context object to *mode* and specify
+    that *callback* should be used for verification callbacks. *mode* should be
+    one of :py:const:`VERIFY_NONE` and :py:const:`VERIFY_PEER`. If
+    :py:const:`VERIFY_PEER` is used, *mode* can be OR:ed with
+    :py:const:`VERIFY_FAIL_IF_NO_PEER_CERT` and :py:const:`VERIFY_CLIENT_ONCE`
+    to further control the behaviour.
+
+    *callback* should take five arguments: A Connection object, an X509 object,
+    and three integer variables, which are in turn potential error number, error
+    depth and return code. *callback* should return true if verification passes
+    and false otherwise.
+
+
+.. py:method:: Context.set_verify_depth(depth)
+
+    Set the maximum depth for the certificate chain verification that shall be
+    allowed for this Context object.
+
+
+.. py:method:: Context.use_certificate(cert)
+
+    Use the certificate *cert* which has to be a X509 object.
+
+
+.. py:method:: Context.add_extra_chain_cert(cert)
+
+    Adds the certificate *cert*, which has to be a X509 object, to the
+    certificate chain presented together with the certificate.
+
+
+.. py:method:: Context.use_certificate_chain_file(file)
+
+    Load a certificate chain from *file* which must be PEM encoded.
+
+
+.. py:method:: Context.use_privatekey(pkey)
+
+    Use the private key *pkey* which has to be a PKey object.
+
+
+.. py:method:: Context.use_certificate_file(file[, format])
+
+    Load the first certificate found in *file*. The certificate must be in the
+    format specified by *format*, which is either :py:const:`FILETYPE_PEM` or
+    :py:const:`FILETYPE_ASN1`. The default is :py:const:`FILETYPE_PEM`.
+
+
+.. py:method:: Context.use_privatekey_file(file[, format])
+
+    Load the first private key found in *file*. The private key must be in the
+    format specified by *format*, which is either :py:const:`FILETYPE_PEM` or
+    :py:const:`FILETYPE_ASN1`. The default is :py:const:`FILETYPE_PEM`.
+
+
+.. py:method:: Context.set_tlsext_servername_callback(callback)
+
+    Specify a one-argument callable to use as the TLS extension server name
+    callback.  When a connection using the server name extension is made using this
+    context, the callback will be invoked with the \code{Connection} instance.
+
+    .. versionadded:: 0.13
+
+
+.. _openssl-connection:
+
+Connection objects
+------------------
+
+Connection objects have the following methods:
+
+.. py:method:: Connection.accept()
+
+    Call the :py:meth:`accept` method of the underlying socket and set up SSL on the
+    returned socket, using the Context object supplied to this Connection object at
+    creation. Returns a pair *(conn, address)*. where *conn* is the new
+    Connection object created, and *address* is as returned by the socket's
+    :py:meth:`accept`.
+
+
+.. py:method:: Connection.bind(address)
+
+    Call the :py:meth:`bind` method of the underlying socket.
+
+
+.. py:method:: Connection.close()
+
+    Call the :py:meth:`close` method of the underlying socket. Note: If you want
+    correct SSL closure, you need to call the :py:meth:`shutdown` method first.
+
+
+.. py:method:: Connection.connect(address)
+
+    Call the :py:meth:`connect` method of the underlying socket and set up SSL on the
+    socket, using the Context object supplied to this Connection object at
+    creation.
+
+
+.. py:method:: Connection.connect_ex(address)
+
+    Call the :py:meth:`connect_ex` method of the underlying socket and set up SSL on
+    the socket, using the Context object supplied to this Connection object at
+    creation. Note that if the :py:meth:`connect_ex` method of the socket doesn't
+    return 0, SSL won't be initialized.
+
+
+.. py:method:: Connection.do_handshake()
+
+    Perform an SSL handshake (usually called after :py:meth:`renegotiate` or one of
+    :py:meth:`set_accept_state` or :py:meth:`set_accept_state`). This can raise the
+    same exceptions as :py:meth:`send` and :py:meth:`recv`.
+
+
+.. py:method:: Connection.fileno()
+
+    Retrieve the file descriptor number for the underlying socket.
+
+
+.. py:method:: Connection.listen(backlog)
+
+    Call the :py:meth:`listen` method of the underlying socket.
+
+
+.. py:method:: Connection.get_app_data()
+
+    Retrieve application data as set by :py:meth:`set_app_data`.
+
+
+.. py:method:: Connection.get_cipher_list()
+
+    Retrieve the list of ciphers used by the Connection object. WARNING: This API
+    has changed. It used to take an optional parameter and just return a string,
+    but not it returns the entire list in one go.
+
+
+.. py:method:: Connection.get_client_ca_list()
+
+    Retrieve the list of preferred client certificate issuers sent by the server
+    as :py:class:`OpenSSL.crypto.X509Name` objects.
+
+    If this is a client :py:class:`Connection`, the list will be empty until the
+    connection with the server is established.
+
+    If this is a server :py:class:`Connection`, return the list of certificate
+    authorities that will be sent or has been sent to the client, as controlled
+    by this :py:class:`Connection`'s :py:class:`Context`.
+
+    .. versionadded:: 0.10
+
+
+.. py:method:: Connection.get_context()
+
+    Retrieve the Context object associated with this Connection.
+
+
+.. py:method:: Connection.set_context(context)
+
+    Specify a replacement Context object for this Connection.
+
+
+.. py:method:: Connection.get_peer_certificate()
+
+    Retrieve the other side's certificate (if any)
+
+
+.. py:method:: Connection.get_peer_cert_chain()
+
+    Retrieve the tuple of the other side's certificate chain (if any)
+
+
+.. py:method:: Connection.getpeername()
+
+    Call the :py:meth:`getpeername` method of the underlying socket.
+
+
+.. py:method:: Connection.getsockname()
+
+    Call the :py:meth:`getsockname` method of the underlying socket.
+
+
+.. py:method:: Connection.getsockopt(level, optname[, buflen])
+
+    Call the :py:meth:`getsockopt` method of the underlying socket.
+
+
+.. py:method:: Connection.pending()
+
+    Retrieve the number of bytes that can be safely read from the SSL buffer
+    (**not** the underlying transport buffer).
+
+
+.. py:method:: Connection.recv(bufsize)
+
+    Receive data from the Connection. The return value is a string representing the
+    data received. The maximum amount of data to be received at once, is specified
+    by *bufsize*.
+
+
+.. py:method:: Connection.bio_write(bytes)
+
+    If the Connection was created with a memory BIO, this method can be used to add
+    bytes to the read end of that memory BIO.  The Connection can then read the
+    bytes (for example, in response to a call to :py:meth:`recv`).
+
+
+.. py:method:: Connection.renegotiate()
+
+    Renegotiate the SSL session. Call this if you wish to change cipher suites or
+    anything like that.
+
+
+.. py:method:: Connection.send(string)
+
+    Send the *string* data to the Connection.
+
+
+.. py:method:: Connection.bio_read(bufsize)
+
+    If the Connection was created with a memory BIO, this method can be used to
+    read bytes from the write end of that memory BIO.  Many Connection methods will
+    add bytes which must be read in this manner or the buffer will eventually fill
+    up and the Connection will be able to take no further actions.
+
+
+.. py:method:: Connection.sendall(string)
+
+    Send all of the *string* data to the Connection. This calls :py:meth:`send`
+    repeatedly until all data is sent. If an error occurs, it's impossible to tell
+    how much data has been sent.
+
+
+.. py:method:: Connection.set_accept_state()
+
+    Set the connection to work in server mode. The handshake will be handled
+    automatically by read/write.
+
+
+.. py:method:: Connection.set_app_data(data)
+
+    Associate *data* with this Connection object. *data* can be retrieved
+    later using the :py:meth:`get_app_data` method.
+
+
+.. py:method:: Connection.set_connect_state()
+
+    Set the connection to work in client mode. The handshake will be handled
+    automatically by read/write.
+
+
+.. py:method:: Connection.setblocking(flag)
+
+    Call the :py:meth:`setblocking` method of the underlying socket.
+
+
+.. py:method:: Connection.setsockopt(level, optname, value)
+
+    Call the :py:meth:`setsockopt` method of the underlying socket.
+
+
+.. py:method:: Connection.shutdown()
+
+    Send the shutdown message to the Connection. Returns true if the shutdown
+    message exchange is completed and false otherwise (in which case you call
+    :py:meth:`recv` or :py:meth:`send` when the connection becomes
+    readable/writeable.
+
+
+.. py:method:: Connection.get_shutdown()
+
+    Get the shutdown state of the Connection.  Returns a bitvector of either or
+    both of *SENT_SHUTDOWN* and *RECEIVED_SHUTDOWN*.
+
+
+.. py:method:: Connection.set_shutdown(state)
+
+    Set the shutdown state of the Connection.  *state* is a bitvector of
+    either or both of *SENT_SHUTDOWN* and *RECEIVED_SHUTDOWN*.
+
+
+.. py:method:: Connection.sock_shutdown(how)
+
+    Call the :py:meth:`shutdown` method of the underlying socket.
+
+
+.. py:method:: Connection.bio_shutdown()
+
+    If the Connection was created with a memory BIO, this method can be used to
+    indicate that *end of file* has been reached on the read end of that memory
+    BIO.
+
+
+.. py:method:: Connection.state_string()
+
+    Retrieve a verbose string detailing the state of the Connection.
+
+
+.. py:method:: Connection.client_random()
+
+    Retrieve the random value used with the client hello message.
+
+
+.. py:method:: Connection.server_random()
+
+    Retrieve the random value used with the server hello message.
+
+
+.. py:method:: Connection.master_key()
+
+    Retrieve the value of the master key for this session.
+
+
+.. py:method:: Connection.want_read()
+
+    Checks if more data has to be read from the transport layer to complete an
+    operation.
+
+
+.. py:method:: Connection.want_write()
+
+    Checks if there is data to write to the transport layer to complete an
+    operation.
+
+
+.. py:method:: Connection.set_tlsext_host_name(name)
+
+    Specify the byte string to send as the server name in the client hello message.
+
+    .. versionadded:: 0.13
+
+
+.. py:method:: Connection.get_servername()
+
+    Get the value of the server name received in the client hello message.
+
+    .. versionadded:: 0.13
+
+
+.. [#connection-context-socket] Actually, all that is required is an object that
+    **behaves** like a socket, you could even use files, even though it'd be
+    tricky to get the handshakes right!
diff --git a/doc/index.rst b/doc/index.rst
index b9c80cf..8f1d336 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -13,7 +13,7 @@ calling a corresponding function in the OpenSSL library.
 Contents:
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 3
 
    introduction
    install
diff --git a/old-doc/pyOpenSSL.tex b/old-doc/pyOpenSSL.tex
deleted file mode 100644
index 434cb70..0000000
--- a/old-doc/pyOpenSSL.tex
+++ /dev/null
@@ -1,1256 +0,0 @@
-\section{\module{OpenSSL} --- Python interface to OpenSSL \label{openssl}}
-
-\declaremodule{extension}{OpenSSL}
-\modulesynopsis{Python interface to OpenSSL}
-
-This package provides a high-level interface to the functions in the
-OpenSSL library. The following modules are defined:
-
-\begin{datadesc}{crypto}
-Generic cryptographic module. Note that if anything is incomplete, this module is!
-\end{datadesc}
-
-\begin{datadesc}{rand}
-An interface to the OpenSSL pseudo random number generator.
-\end{datadesc}
-
-\begin{datadesc}{SSL}
-An interface to the SSL-specific parts of OpenSSL.
-\end{datadesc}
-
-
-% % % crypto moduleOpenSSL
-
-\subsection{\module{crypto} --- Generic cryptographic module \label{openssl-crypto}}
-
-\declaremodule{extension}{crypto}
-\modulesynopsis{Generic cryptographic module}
-
-\begin{datadesc}{X509Type}
-See \class{X509}.
-\end{datadesc}
-
-\begin{classdesc}{X509}{}
-A class representing X.509 certificates.
-\end{classdesc}
-
-\begin{datadesc}{X509NameType}
-See \class{X509Name}.
-\end{datadesc}
-
-\begin{classdesc}{X509Name}{x509name}
-A class representing X.509 Distinguished Names.
-
-This constructor creates a copy of \var{x509name} which should be an
-instance of \class{X509Name}.
-\end{classdesc}
-
-\begin{datadesc}{X509ReqType}
-See \class{X509Req}.
-\end{datadesc}
-
-\begin{classdesc}{X509Req}{}
-A class representing X.509 certificate requests.
-\end{classdesc}
-
-\begin{datadesc}{X509StoreType}
-A Python type object representing the X509Store object type.
-\end{datadesc}
-
-\begin{datadesc}{PKeyType}
-See \class{PKey}.
-\end{datadesc}
-
-\begin{classdesc}{PKey}{}
-A class representing DSA or RSA keys.
-\end{classdesc}
-
-\begin{datadesc}{PKCS7Type}
-A Python type object representing the PKCS7 object type.
-\end{datadesc}
-
-\begin{datadesc}{PKCS12Type}
-A Python type object representing the PKCS12 object type.
-\end{datadesc}
-
-\begin{datadesc}{X509ExtensionType}
-See \class{X509Extension}.
-\end{datadesc}
-
-\begin{classdesc}{X509Extension}{typename, critical, value\optional{, subject}\optional{, issuer}}
-A class representing an X.509 v3 certificate extensions.
-See \url{http://openssl.org/docs/apps/x509v3_config.html\#STANDARD_EXTENSIONS}
-for \var{typename} strings and their options.
-Optional parameters \var{subject} and \var{issuer} must be X509 objects.
-\end{classdesc}
-
-\begin{datadesc}{NetscapeSPKIType}
-See \class{NetscapeSPKI}.
-\end{datadesc}
-
-\begin{classdesc}{NetscapeSPKI}{\optional{enc}}
-A class representing Netscape SPKI objects.
-
-If the \var{enc} argument is present, it should be a base64-encoded string
-representing a NetscapeSPKI object, as returned by the \method{b64_encode}
-method.
-\end{classdesc}
-
-\begin{classdesc}{CRL}{}
-A class representing Certifcate Revocation List objects.
-\end{classdesc}
-
-\begin{classdesc}{Revoked}{}
-A class representing Revocation objects of CRL.
-\end{classdesc}
-
-\begin{datadesc}{FILETYPE_PEM}
-\dataline{FILETYPE_ASN1}
-File type constants.
-\end{datadesc}
-
-\begin{datadesc}{TYPE_RSA}
-\dataline{TYPE_DSA}
-Key type constants.
-\end{datadesc}
-
-\begin{excdesc}{Error}
-Generic exception used in the \module{crypto} module.
-\end{excdesc}
-
-\begin{funcdesc}{dump_certificate}{type, cert}
-Dump the certificate \var{cert} into a buffer string encoded with the type
-\var{type}.
-\end{funcdesc}
-
-\begin{funcdesc}{dump_certificate_request}{type, req}
-Dump the certificate request \var{req} into a buffer string encoded with the
-type \var{type}.
-\end{funcdesc}
-
-\begin{funcdesc}{dump_privatekey}{type, pkey\optional{, cipher, passphrase}}
-Dump the private key \var{pkey} into a buffer string encoded with the type
-\var{type}, optionally (if \var{type} is \constant{FILETYPE_PEM}) encrypting it
-using \var{cipher} and \var{passphrase}.
-
-\var{passphrase} must be either a string or a callback for providing the
-pass phrase.
-\end{funcdesc}
-
-\begin{funcdesc}{load_certificate}{type, buffer}
-Load a certificate (X509) from the string \var{buffer} encoded with the
-type \var{type}.
-\end{funcdesc}
-
-\begin{funcdesc}{load_certificate_request}{type, buffer}
-Load a certificate request (X509Req) from the string \var{buffer} encoded with
-the type \var{type}.
-\end{funcdesc}
-
-\begin{funcdesc}{load_privatekey}{type, buffer\optional{, passphrase}}
-Load a private key (PKey) from the string \var{buffer} encoded with
-the type \var{type} (must be one of \constant{FILETYPE_PEM} and
-\constant{FILETYPE_ASN1}).
-
-\var{passphrase} must be either a string or a callback for providing the
-pass phrase.
-\end{funcdesc}
-
-\begin{funcdesc}{load_crl}{type, buffer}
-Load Certificate Revocation List (CRL) data from a string \var{buffer}.
-\var{buffer} encoded with the type \var{type}.  The type \var{type}
-must either \constant{FILETYPE_PEM} or \constant{FILETYPE_ASN1}).
-\end{funcdesc}
-
-\begin{funcdesc}{load_pkcs7_data}{type, buffer}
-Load pkcs7 data from the string \var{buffer} encoded with the type \var{type}.
-\end{funcdesc}
-
-\begin{funcdesc}{load_pkcs12}{buffer\optional{, passphrase}}
-Load pkcs12 data from the string \var{buffer}. If the pkcs12 structure is
-encrypted, a \var{passphrase} must be included.  The MAC is always
-checked and thus required.
-
-See also the man page for the C function \function{PKCS12_parse}.
-\end{funcdesc}
-
-\begin{funcdesc}{sign}{key, data, digest}
-Sign a data string using the given key and message digest.
-
-\var{key} is a \code{PKey} instance.  \var{data} is a \code{str} instance.
-\var{digest} is a \code{str} naming a supported message digest type, for example
-\code{``sha1''}.
-\versionadded{0.11}
-\end{funcdesc}
-
-\begin{funcdesc}{verify}{certificate, signature, data, digest}
-Verify the signature for a data string.
-
-\var{certificate} is a \code{X509} instance corresponding to the private key
-which generated the signature.  \var{signature} is a \var{str} instance giving
-the signature itself.  \var{data} is a \var{str} instance giving the data to
-which the signature applies.  \var{digest} is a \var{str} instance naming the
-message digest type of the signature, for example \code{``sha1''}.
-\versionadded{0.11}
-\end{funcdesc}
-
-\subsubsection{X509 objects \label{openssl-x509}}
-
-X509 objects have the following methods:
-
-\begin{methoddesc}[X509]{get_issuer}{}
-Return an X509Name object representing the issuer of the certificate.
-\end{methoddesc}
-
-\begin{methoddesc}[X509]{get_pubkey}{}
-Return a PKey object representing the public key of the certificate.
-\end{methoddesc}
-
-\begin{methoddesc}[X509]{get_serial_number}{}
-Return the certificate serial number.
-\end{methoddesc}
-
-\begin{methoddesc}[X509]{get_signature_algorithm}{}
-Return the signature algorithm used in the certificate.  If the algorithm is
-undefined, raise \code{ValueError}.
-\end{methoddesc}
-
-\begin{methoddesc}[X509]{get_subject}{}
-Return an X509Name object representing the subject of the certificate.
-\end{methoddesc}
-
-\begin{methoddesc}[X509]{get_version}{}
-Return the certificate version.
-\end{methoddesc}
-
-\begin{methoddesc}[X509]{get_notBefore}{}
-Return a string giving the time before which the certificate is not valid.  The
-string is formatted as an ASN1 GENERALIZEDTIME:
-\begin{verbatim}
-                 YYYYMMDDhhmmssZ
-                 YYYYMMDDhhmmss+hhmm
-                 YYYYMMDDhhmmss-hhmm
-\end{verbatim}
-If no value exists for this field, \code{None} is returned.
-\end{methoddesc}
-
-\begin{methoddesc}[X509]{get_notAfter}{}
-Return a string giving the time after which the certificate is not valid.  The
-string is formatted as an ASN1 GENERALIZEDTIME:
-\begin{verbatim}
-                 YYYYMMDDhhmmssZ
-                 YYYYMMDDhhmmss+hhmm
-                 YYYYMMDDhhmmss-hhmm
-\end{verbatim}
-If no value exists for this field, \code{None} is returned.
-\end{methoddesc}
-
-\begin{methoddesc}[X509]{set_notBefore}{when}
-Change the time before which the certificate is not valid.  \var{when} is a
-string formatted as an ASN1 GENERALIZEDTIME:
-\begin{verbatim}
-                 YYYYMMDDhhmmssZ
-                 YYYYMMDDhhmmss+hhmm
-                 YYYYMMDDhhmmss-hhmm
-\end{verbatim}
-\end{methoddesc}
-
-\begin{methoddesc}[X509]{set_notAfter}{when}
-Change the time after which the certificate is not valid.  \var{when} is a
-string formatted as an ASN1 GENERALIZEDTIME:
-\begin{verbatim}
-                 YYYYMMDDhhmmssZ
-                 YYYYMMDDhhmmss+hhmm
-                 YYYYMMDDhhmmss-hhmm
-\end{verbatim}
-\end{methoddesc}
-
-\begin{methoddesc}[X509]{gmtime_adj_notBefore}{time}
-Adjust the timestamp (in GMT) when the certificate starts being valid.
-\end{methoddesc}
-
-\begin{methoddesc}[X509]{gmtime_adj_notAfter}{time}
-Adjust the timestamp (in GMT) when the certificate stops being valid.
-\end{methoddesc}
-
-\begin{methoddesc}[X509]{has_expired}{}
-Checks the certificate's time stamp against current time. Returns true if the
-certificate has expired and false otherwise.
-\end{methoddesc}
-
-\begin{methoddesc}[X509]{set_issuer}{issuer}
-Set the issuer of the certificate to \var{issuer}.
-\end{methoddesc}
-
-\begin{methoddesc}[X509]{set_pubkey}{pkey}
-Set the public key of the certificate to \var{pkey}.
-\end{methoddesc}
-
-\begin{methoddesc}[X509]{set_serial_number}{serialno}
-Set the serial number of the certificate to \var{serialno}.
-\end{methoddesc}
-
-\begin{methoddesc}[X509]{set_subject}{subject}
-Set the subject of the certificate to \var{subject}.
-\end{methoddesc}
-
-\begin{methoddesc}[X509]{set_version}{version}
-Set the certificate version to \var{version}.
-\end{methoddesc}
-
-\begin{methoddesc}[X509]{sign}{pkey, digest}
-Sign the certificate, using the key \var{pkey} and the message digest algorithm
-identified by the string \var{digest}.
-\end{methoddesc}
-
-\begin{methoddesc}[X509]{subject_name_hash}{}
-Return the hash of the certificate subject.
-\end{methoddesc}
-
-\begin{methoddesc}[X509]{digest}{digest_name}
-Return a digest of the certificate, using the \var{digest_name} method.
-\var{digest_name} must be a string describing a digest algorithm supported
-by OpenSSL (by EVP_get_digestbyname, specifically).  For example,
-\constant{"md5"} or \constant{"sha1"}.
-\end{methoddesc}
-
-\begin{methoddesc}[X509]{add_extensions}{extensions}
-Add the extensions in the sequence \var{extensions} to the certificate.
-\end{methoddesc}
-
-\begin{methoddesc}[X509]{get_extension_count}{}
-Return the number of extensions on this certificate.
-\versionadded{0.12}
-\end{methoddesc}
-
-\begin{methoddesc}[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 X509Extension
-instance.
-\versionadded{0.12}
-\end{methoddesc}
-
-\subsubsection{X509Name objects \label{openssl-x509name}}
-
-X509Name objects have the following methods:
-
-\begin{methoddesc}[X509Name]{hash}{}
-Return an integer giving the first four bytes of the MD5 digest of the DER
-representation of the name.
-\end{methoddesc}
-
-\begin{methoddesc}[X509Name]{der}{}
-Return a string giving the DER representation of the name.
-\end{methoddesc}
-
-\begin{methoddesc}[X509Name]{get_components}{}
-Return a list of two-tuples of strings giving the components of the name.
-\end{methoddesc}
-
-X509Name objects have the following members:
-
-\begin{memberdesc}[X509Name]{countryName}
-The country of the entity. \code{C} may be used as an alias for
-\code{countryName}.
-\end{memberdesc}
-
-\begin{memberdesc}[X509Name]{stateOrProvinceName}
-The state or province of the entity. \code{ST} may be used as an alias for
-\code{stateOrProvinceName}·
-\end{memberdesc}
-
-\begin{memberdesc}[X509Name]{localityName}
-The locality of the entity. \code{L} may be used as an alias for
-\code{localityName}.
-\end{memberdesc}
-
-\begin{memberdesc}[X509Name]{organizationName}
-The organization name of the entity. \code{O} may be used as an alias for
-\code{organizationName}.
-\end{memberdesc}
-
-\begin{memberdesc}[X509Name]{organizationalUnitName}
-The organizational unit of the entity. \code{OU} may be used as an alias for
-\code{organizationalUnitName}.
-\end{memberdesc}
-
-\begin{memberdesc}[X509Name]{commonName}
-The common name of the entity. \code{CN} may be used as an alias for
-\code{commonName}.
-\end{memberdesc}
-
-\begin{memberdesc}[X509Name]{emailAddress}
-The e-mail address of the entity.
-\end{memberdesc}
-
-\subsubsection{X509Req objects \label{openssl-x509req}}
-
-X509Req objects have the following methods:
-
-\begin{methoddesc}[X509Req]{get_pubkey}{}
-Return a PKey object representing the public key of the certificate request.
-\end{methoddesc}
-
-\begin{methoddesc}[X509Req]{get_subject}{}
-Return an X509Name object representing the subject of the certificate.
-\end{methoddesc}
-
-\begin{methoddesc}[X509Req]{set_pubkey}{pkey}
-Set the public key of the certificate request to \var{pkey}.
-\end{methoddesc}
-
-\begin{methoddesc}[X509Req]{sign}{pkey, digest}
-Sign the certificate request, using the key \var{pkey} and the message digest
-algorithm identified by the string \var{digest}.
-\end{methoddesc}
-
-\begin{methoddesc}[X509Req]{verify}{pkey}
-Verify a certificate request using the public key \var{pkey}.
-\end{methoddesc}
-
-\begin{methoddesc}[X509Req]{set_version}{version}
-Set the version (RFC 2459, 4.1.2.1) of the certificate request to
-\var{version}.
-\end{methoddesc}
-
-\begin{methoddesc}[X509Req]{get_version}{}
-Get the version (RFC 2459, 4.1.2.1) of the certificate request.
-\end{methoddesc}
-
-\subsubsection{X509Store objects \label{openssl-x509store}}
-
-The X509Store object has currently just one method:
-
-\begin{methoddesc}[X509Store]{add_cert}{cert}
-Add the certificate \var{cert} to the certificate store.
-\end{methoddesc}
-
-\subsubsection{PKey objects \label{openssl-pkey}}
-
-The PKey object has the following methods:
-
-\begin{methoddesc}[PKey]{bits}{}
-Return the number of bits of the key.
-\end{methoddesc}
-
-\begin{methoddesc}[PKey]{generate_key}{type, bits}
-Generate a public/private key pair of the type \var{type} (one of
-\constant{TYPE_RSA} and \constant{TYPE_DSA}) with the size \var{bits}.
-\end{methoddesc}
-
-\begin{methoddesc}[PKey]{type}{}
-Return the type of the key.
-\end{methoddesc}
-
-\begin{methoddesc}[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.
-\end{methoddesc}
-
-\subsubsection{PKCS7 objects \label{openssl-pkcs7}}
-
-PKCS7 objects have the following methods:
-
-\begin{methoddesc}[PKCS7]{type_is_signed}{}
-FIXME
-\end{methoddesc}
-
-\begin{methoddesc}[PKCS7]{type_is_enveloped}{}
-FIXME
-\end{methoddesc}
-
-\begin{methoddesc}[PKCS7]{type_is_signedAndEnveloped}{}
-FIXME
-\end{methoddesc}
-
-\begin{methoddesc}[PKCS7]{type_is_data}{}
-FIXME
-\end{methoddesc}
-
-\begin{methoddesc}[PKCS7]{get_type_name}{}
-Get the type name of the PKCS7.
-\end{methoddesc}
-
-\subsubsection{PKCS12 objects \label{openssl-pkcs12}}
-
-PKCS12 objects have the following methods:
-
-\begin{methoddesc}[PKCS12]{export}{\optional{passphrase=None}\optional{, iter=2048}\optional{, maciter=1}}
-Returns a PKCS12 object as a string.
-
-The optional \var{passphrase} must be a string not a callback.
-
-See also the man page for the C function \function{PKCS12_create}.
-\end{methoddesc}
-
-\begin{methoddesc}[PKCS12]{get_ca_certificates}{}
-Return CA certificates within the PKCS12 object as a tuple. Returns
-\constant{None} if no CA certificates are present.
-\end{methoddesc}
-
-\begin{methoddesc}[PKCS12]{get_certificate}{}
-Return certificate portion of the PKCS12 structure.
-\end{methoddesc}
-
-\begin{methoddesc}[PKCS12]{get_friendlyname}{}
-Return friendlyName portion of the PKCS12 structure.
-\end{methoddesc}
-
-\begin{methoddesc}[PKCS12]{get_privatekey}{}
-Return private key portion of the PKCS12 structure
-\end{methoddesc}
-
-\begin{methoddesc}[PKCS12]{set_ca_certificates}{cacerts}
-Replace or set the CA certificates within the PKCS12 object with the sequence \var{cacerts}.
-
-Set \var{cacerts} to \constant{None} to remove all CA certificates.
-\end{methoddesc}
-
-\begin{methoddesc}[PKCS12]{set_certificate}{cert}
-Replace or set the certificate portion of the PKCS12 structure.
-\end{methoddesc}
-
-\begin{methoddesc}[PKCS12]{set_friendlyname}{name}
-Replace or set the friendlyName portion of the PKCS12 structure.
-\end{methoddesc}
-
-\begin{methoddesc}[PKCS12]{set_privatekey}{pkey}
-Replace or set private key portion of the PKCS12 structure
-\end{methoddesc}
-
-\subsubsection{X509Extension objects \label{openssl-509ext}}
-
-X509Extension objects have several methods:
-
-\begin{methoddesc}[X509Extension]{get_critical}{}
-Return the critical field of the extension object.
-\end{methoddesc}
-
-\begin{methoddesc}[X509Extension]{get_short_name}{}
-Retrieve the short descriptive name for this extension.
-
-The result is a byte string like \code{``basicConstraints''}.
-\versionadded{0.12}
-\end{methoddesc}
-
-\begin{methoddesc}[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}
-\end{methoddesc}
-
-\subsubsection{NetscapeSPKI objects \label{openssl-netscape-spki}}
-
-NetscapeSPKI objects have the following methods:
-
-\begin{methoddesc}[NetscapeSPKI]{b64_encode}{}
-Return a base64-encoded string representation of the object.
-\end{methoddesc}
-
-\begin{methoddesc}[NetscapeSPKI]{get_pubkey}{}
-Return the public key of object.
-\end{methoddesc}
-
-\begin{methoddesc}[NetscapeSPKI]{set_pubkey}{key}
-Set the public key of the object to \var{key}.
-\end{methoddesc}
-
-\begin{methoddesc}[NetscapeSPKI]{sign}{key, digest_name}
-Sign the NetscapeSPKI object using the given \var{key} and
-\var{digest_name}.  \var{digest_name} must be a string describing a digest
-algorithm supported by OpenSSL (by EVP_get_digestbyname, specifically).  For
-example, \constant{"md5"} or \constant{"sha1"}.
-\end{methoddesc}
-
-\begin{methoddesc}[NetscapeSPKI]{verify}{key}
-Verify the NetscapeSPKI object using the given \var{key}.
-\end{methoddesc}
-
-\subsubsection{CRL objects \label{crl}}
-
-CRL objects have the following methods:
-
-\begin{methoddesc}[CRL]{add_revoked}{revoked}
-Add a Revoked object to the CRL, by value not reference.
-\end{methoddesc}
-
-\begin{methoddesc}[CRL]{export}{cert, key\optional{, type=FILETYPE_PEM}\optional{, days=100}}
-Use \var{cert} and \var{key} to sign the CRL and return the CRL as a string.
-\var{days} is the number of days before the next CRL is due.
-\end{methoddesc}
-
-\begin{methoddesc}[CRL]{get_revoked}{}
-Return a tuple of Revoked objects, by value not reference.
-\end{methoddesc}
-
-\subsubsection{Revoked objects \label{revoked}}
-
-Revoked objects have the following methods:
-
-\begin{methoddesc}[Revoked]{all_reasons}{}
-Return a list of all supported reasons.
-\end{methoddesc}
-
-\begin{methoddesc}[Revoked]{get_reason}{}
-Return the revocation reason as a str.  Can be
-None, which differs from "Unspecified".
-\end{methoddesc}
-
-\begin{methoddesc}[Revoked]{get_rev_date}{}
-Return the revocation date as a str.
-The string is formatted as an ASN1 GENERALIZEDTIME.
-\end{methoddesc}
-
-\begin{methoddesc}[Revoked]{get_serial}{}
-Return a str containing a hex number of the serial of the revoked certificate.
-\end{methoddesc}
-
-\begin{methoddesc}[Revoked]{set_reason}{reason}
-Set the revocation reason.  \var{reason} must
-be None or a string, but the values are limited.  
-Spaces and case are ignored.  See \method{all_reasons}.
-\end{methoddesc}
-
-\begin{methoddesc}[Revoked]{set_rev_date}{date}
-Set the revocation date.
-The string is formatted as an ASN1 GENERALIZEDTIME.
-\end{methoddesc}
-
-\begin{methoddesc}[Revoked]{set_serial}{serial}
-\var{serial} is a string containing a hex number of the serial of the revoked certificate.
-\end{methoddesc}
-
-
-% % % rand module
-
-\subsection{\module{rand} --- An interface to the OpenSSL pseudo random number generator \label{openssl-rand}}
-
-\declaremodule{extension}{rand}
-\modulesynopsis{An interface to the OpenSSL pseudo random number generator}
-
-This module handles the OpenSSL pseudo random number generator (PRNG) and
-declares the following:
-
-\begin{funcdesc}{add}{string, entropy}
-Mix bytes from \var{string} into the PRNG state. The \var{entropy} argument is
-(the lower bound of) an estimate of how much randomness is contained in
-\var{string}, measured in bytes. For more information, see e.g. \rfc{1750}.
-\end{funcdesc}
-
-\begin{funcdesc}{bytes}{num_bytes}
-Get some random bytes from the PRNG as a string.
-
-This is a wrapper for the C function \function{RAND_bytes}.
-\end{funcdesc}
-
-\begin{funcdesc}{cleanup}{}
-Erase the memory used by the PRNG.
-
-This is a wrapper for the C function \function{RAND_cleanup}.
-\end{funcdesc}
-
-\begin{funcdesc}{egd}{path\optional{, bytes}}
-Query the Entropy Gathering Daemon\footnote{See
-\url{http://www.lothar.com/tech/crypto/}} on socket \var{path} for \var{bytes}
-bytes of random data and and uses \function{add} to seed the PRNG. The default
-value of \var{bytes} is 255.
-\end{funcdesc}
-
-\begin{funcdesc}{load_file}{path\optional{, bytes}}
-Read \var{bytes} bytes (or all of it, if \var{bytes} is negative) of data from
-the file \var{path} to seed the PRNG. The default value of \var{bytes} is -1.
-\end{funcdesc}
-
-\begin{funcdesc}{screen}{}
-Add the current contents of the screen to the PRNG state.
-Availability: Windows.
-\end{funcdesc}
-
-\begin{funcdesc}{seed}{string}
-This is equivalent to calling \function{add} with \var{entropy} as the length
-of the string.
-\end{funcdesc}
-
-\begin{funcdesc}{status}{}
-Returns true if the PRNG has been seeded with enough data, and false otherwise.
-\end{funcdesc}
-
-\begin{funcdesc}{write_file}{path}
-Write a number of random bytes (currently 1024) to the file \var{path}. This
-file can then be used with \function{load_file} to seed the PRNG again.
-\end{funcdesc}
-
-\begin{excdesc}{Error}
-If the current RAND method supports any errors, this is raised when needed.
-The default method does not raise this when the entropy pool is depleted.
-
-Whenever this exception is raised directly, it has a list of error messages
-from the OpenSSL error queue, where each item is a tuple \code{(\var{lib},
-\var{function}, \var{reason})}. Here \var{lib}, \var{function} and \var{reason}
-are all strings, describing where and what the problem is. See \manpage{err}{3}
-for more information.
-\end{excdesc}
-
-
-% % % SSL module
-
-\subsection{\module{SSL} --- An interface to the SSL-specific parts of OpenSSL \label{openssl-ssl}}
-
-\declaremodule{extension}{SSL}
-\modulesynopsis{An interface to the SSL-specific parts of OpenSSL}
-
-This module handles things specific to SSL. There are two objects defined:
-Context, Connection.
-
-\begin{datadesc}{SSLv2_METHOD}
-\dataline{SSLv3_METHOD}
-\dataline{SSLv23_METHOD}
-\dataline{TLSv1_METHOD}
-These constants represent the different SSL methods to use when creating a
-context object.
-\end{datadesc}
-
-\begin{datadesc}{VERIFY_NONE}
-\dataline{VERIFY_PEER}
-\dataline{VERIFY_FAIL_IF_NO_PEER_CERT}
-These constants represent the verification mode used by the Context
-object's \method{set_verify} method.
-\end{datadesc}
-
-\begin{datadesc}{FILETYPE_PEM}
-\dataline{FILETYPE_ASN1}
-File type constants used with the \method{use_certificate_file} and
-\method{use_privatekey_file} methods of Context objects.
-\end{datadesc}
-
-\begin{datadesc}{OP_SINGLE_DH_USE}
-\dataline{OP_EPHEMERAL_RSA}
-\dataline{OP_NO_SSLv2}
-\dataline{OP_NO_SSLv3}
-\dataline{OP_NO_TLSv1}
-Constants used with \method{set_options} of Context objects.
-\constant{OP_SINGLE_DH_USE} means to always create a new key when using ephemeral
-Diffie-Hellman. \constant{OP_EPHEMERAL_RSA} means to always use ephemeral RSA keys
-when doing RSA operations. \constant{OP_NO_SSLv2}, \constant{OP_NO_SSLv3} and
-\constant{OP_NO_TLSv1} means to disable those specific protocols. This is
-interesting if you're using e.g. \constant{SSLv23_METHOD} to get an SSLv2-compatible
-handshake, but don't want to use SSLv2.
-\end{datadesc}
-
-\begin{datadesc}{SSLEAY_VERSION}
-\dataline{SSLEAY_CFLAGS}
-\dataline{SSLEAY_BUILT_ON}
-\dataline{SSLEAY_PLATFORM}
-\dataline{SSLEAY_DIR}
-Constants used with \method{SSLeay_version} to specify what OpenSSL version
-information to retrieve.  See the man page for the \function{SSLeay_version} C
-API for details.
-\end{datadesc}
-
-\begin{datadesc}{OPENSSL_VERSION_NUMBER}
-An integer giving the version number of the OpenSSL library used to build this
-version of pyOpenSSL.  See the man page for the \function{SSLeay_version} C API
-for details.
-\end{datadesc}
-
-\begin{funcdesc}{SSLeay_version}{type}
-Retrieve a string describing some aspect of the underlying OpenSSL version.  The
-type passed in should be one of the \constant{SSLEAY_*} constants defined in
-this module.
-\end{funcdesc}
-
-\begin{datadesc}{ContextType}
-See \class{Context}.
-\end{datadesc}
-
-\begin{classdesc}{Context}{method}
-A class representing SSL contexts.  Contexts define the parameters of one or
-more SSL connections.
-
-\var{method} should be \constant{SSLv2_METHOD}, \constant{SSLv3_METHOD},
-\constant{SSLv23_METHOD} or \constant{TLSv1_METHOD}.
-\end{classdesc}
-
-\begin{datadesc}{ConnectionType}
-See \class{Connection}.
-\end{datadesc}
-
-\begin{classdesc}{Connection}{context, socket}
-A class representing SSL connections.
-
-\var{context} should be an instance of \class{Context} and \var{socket}
-should be a socket \footnote{Actually, all that is required is an object
-that \emph{behaves} like a socket, you could even use files, even though
-it'd be tricky to get the handshakes right!} object.  \var{socket} may be
-\var{None}; in this case, the Connection is created with a memory BIO: see
-the \method{bio_read}, \method{bio_write}, and \method{bio_shutdown}
-methods.
-\end{classdesc}
-
-\begin{excdesc}{Error}
-This exception is used as a base class for the other SSL-related
-exceptions, but may also be raised directly.
-
-Whenever this exception is raised directly, it has a list of error messages
-from the OpenSSL error queue, where each item is a tuple \code{(\var{lib},
-\var{function}, \var{reason})}. Here \var{lib}, \var{function} and \var{reason}
-are all strings, describing where and what the problem is. See \manpage{err}{3}
-for more information.
-\end{excdesc}
-
-\begin{excdesc}{ZeroReturnError}
-This exception matches the error return code \code{SSL_ERROR_ZERO_RETURN}, and
-is raised when the SSL Connection has been closed. In SSL 3.0 and TLS 1.0, this
-only occurs if a closure alert has occurred in the protocol, i.e. the
-connection has been closed cleanly. Note that this does not necessarily
-mean that the transport layer (e.g. a socket) has been closed.
-
-It may seem a little strange that this is an exception, but it does match an
-\code{SSL_ERROR} code, and is very convenient.
-\end{excdesc}
-
-\begin{excdesc}{WantReadError}
-The operation did not complete; the same I/O method should be called again
-later, with the same arguments. Any I/O method can lead to this since new
-handshakes can occur at any time.
-
-The wanted read is for \emph{dirty} data sent over the network, not the
-\emph{clean} data inside the tunnel.  For a socket based SSL connection,
-\emph{read} means data coming at us over the network.  Until that read
-succeeds, the attempted \method{OpenSSL.SSL.Connection.recv},
-\method{OpenSSL.SSL.Connection.send}, or
-\method{OpenSSL.SSL.Connection.do_handshake} is prevented or incomplete. You
-probably want to \method{select()} on the socket before trying again.
-\end{excdesc}
-
-\begin{excdesc}{WantWriteError}
-See \exception{WantReadError}.  The socket send buffer may be too full to
-write more data.
-\end{excdesc}
-
-\begin{excdesc}{WantX509LookupError}
-The operation did not complete because an application callback has asked to be
-called again. The I/O method should be called again later, with the same
-arguments. Note: This won't occur in this version, as there are no such
-callbacks in this version.
-\end{excdesc}
-
-\begin{excdesc}{SysCallError}
-The \exception{SysCallError} occurs when there's an I/O error and OpenSSL's
-error queue does not contain any information. This can mean two things: An
-error in the transport protocol, or an end of file that violates the protocol.
-The parameter to the exception is always a pair \code{(\var{errnum},
-\var{errstr})}.
-\end{excdesc}
-
-
-\subsubsection{Context objects \label{openssl-context}}
-
-Context objects have the following methods:
-
-\begin{methoddesc}[Context]{check_privatekey}{}
-Check if the private key (loaded with \method{use_privatekey\optional{_file}})
-matches the certificate (loaded with \method{use_certificate\optional{_file}}).
-Returns \code{None} if they match, raises \exception{Error} otherwise.
-\end{methoddesc}
-
-\begin{methoddesc}[Context]{get_app_data}{}
-Retrieve application data as set by \method{set_app_data}.
-\end{methoddesc}
-
-\begin{methoddesc}[Context]{get_cert_store}{}
-Retrieve the certificate store (a X509Store object) that the context uses.
-This can be used to add "trusted" certificates without using the.
-\method{load_verify_locations()} method.
-\end{methoddesc}
-
-\begin{methoddesc}[Context]{get_timeout}{}
-Retrieve session timeout, as set by \method{set_timeout}. The default is 300
-seconds.
-\end{methoddesc}
-
-\begin{methoddesc}[Context]{get_verify_depth}{}
-Retrieve the Context object's verify depth, as set by
-\method{set_verify_depth}.
-\end{methoddesc}
-
-\begin{methoddesc}[Context]{get_verify_mode}{}
-Retrieve the Context object's verify mode, as set by \method{set_verify}.
-\end{methoddesc}
-
-\begin{methoddesc}[Context]{load_client_ca}{pemfile}
-Read a file with PEM-formatted certificates that will be sent to the client
-when requesting a client certificate.
-\end{methoddesc}
-
-\begin{methoddesc}[Context]{set_client_ca_list}{certificate_authorities}
-Replace the current list of preferred certificate signers that would be
-sent to the client when requesting a client certificate with the
-\var{certificate_authorities} sequence of \class{OpenSSL.crypto.X509Name}s.
-
-\versionadded{0.10}
-\end{methoddesc}
-
-\begin{methoddesc}[Context]{add_client_ca}{certificate_authority}
-Extract a \class{OpenSSL.crypto.X509Name} from the \var{certificate_authority}
-\class{OpenSSL.crypto.X509} certificate and add it to the list of preferred
-certificate signers sent to the client when requesting a client certificate.
-
-\versionadded{0.10}
-\end{methoddesc}
-
-\begin{methoddesc}[Context]{load_verify_locations}{pemfile, capath}
-Specify where CA certificates for verification purposes are located. These
-are trusted certificates. Note that the certificates have to be in PEM
-format.  If capath is passed, it must be a directory prepared using the
-\code{c_rehash} tool included with OpenSSL.  Either, but not both, of
-\var{pemfile} or \var{capath} may be \code{None}.
-\end{methoddesc}
-
-\begin{methoddesc}[Context]{set_default_verify_paths}{}
-Specify that the platform provided CA certificates are to be used for
-verification purposes.  This method may not work properly on OS X.
-\end{methoddesc}
-
-\begin{methoddesc}[Context]{load_tmp_dh}{dhfile}
-Load parameters for Ephemeral Diffie-Hellman from \var{dhfile}.
-\end{methoddesc}
-
-\begin{methoddesc}[Context]{set_app_data}{data}
-Associate \var{data} with this Context object. \var{data} can be retrieved
-later using the \method{get_app_data} method.
-\end{methoddesc}
-
-\begin{methoddesc}[Context]{set_cipher_list}{ciphers}
-Set the list of ciphers to be used in this context. See the OpenSSL manual for
-more information (e.g. ciphers(1))
-\end{methoddesc}
-
-\begin{methoddesc}[Context]{set_info_callback}{callback}
-Set the information callback to \var{callback}. This function will be called
-from time to time during SSL handshakes.
-\var{callback} should take three arguments: a Connection object and two
-integers. The first integer specifies where in the SSL handshake the function
-was called, and the other the return code from a (possibly failed) internal
-function call.
-\end{methoddesc}
-
-\begin{methoddesc}[Context]{set_options}{options}
-Add SSL options. Options you have set before are not cleared!
-This method should be used with the \constant{OP_*} constants.
-\end{methoddesc}
-
-\begin{methoddesc}[Context]{set_passwd_cb}{callback\optional{, userdata}}
-Set the passphrase callback to \var{callback}. This function will be called
-when a private key with a passphrase is loaded. \var{callback} must accept
-three positional arguments.  First, an integer giving the maximum length of
-the passphrase it may return.  If the returned passphrase is longer than
-this, it will be truncated.  Second, a boolean value which will be true if
-the user should be prompted for the passphrase twice and the callback should
-verify that the two values supplied are equal. Third, the value given as the
-\var{userdata} parameter to \method{set_passwd_cb}.  If an error occurs,
-\var{callback} should return a false value (e.g. an empty string).
-\end{methoddesc}
-
-\begin{methoddesc}[Context]{set_session_id}{name}
-Set the context \var{name} within which a session can be reused for this
-Context object. This is needed when doing session resumption, because there is
-no way for a stored session to know which Context object it is associated with.
-\var{name} may be any binary data.
-\end{methoddesc}
-
-\begin{methoddesc}[Context]{set_timeout}{timeout}
-Set the timeout for newly created sessions for this Context object to
-\var{timeout}. \var{timeout} must be given in (whole) seconds. The default
-value is 300 seconds. See the OpenSSL manual for more information (e.g.
-SSL_CTX_set_timeout(3)).
-\end{methoddesc}
-
-\begin{methoddesc}[Context]{set_verify}{mode, callback}
-Set the verification flags for this Context object to \var{mode} and specify
-that \var{callback} should be used for verification callbacks. \var{mode}
-should be one of \constant{VERIFY_NONE} and \constant{VERIFY_PEER}. If
-\constant{VERIFY_PEER} is used, \var{mode} can be OR:ed with
-\constant{VERIFY_FAIL_IF_NO_PEER_CERT} and \constant{VERIFY_CLIENT_ONCE} to
-further control the behaviour.
-\var{callback} should take five arguments: A Connection object, an X509 object,
-and three integer variables, which are in turn potential error number, error
-depth and return code. \var{callback} should return true if verification passes
-and false otherwise.
-\end{methoddesc}
-
-\begin{methoddesc}[Context]{set_verify_depth}{depth}
-Set the maximum depth for the certificate chain verification that shall be
-allowed for this Context object.
-\end{methoddesc}
-
-\begin{methoddesc}[Context]{use_certificate}{cert}
-Use the certificate \var{cert} which has to be a X509 object.
-\end{methoddesc}
-
-\begin{methoddesc}[Context]{add_extra_chain_cert}{cert}
-Adds the certificate \var{cert}, which has to be a X509 object, to the
-certificate chain presented together with the certificate.
-\end{methoddesc}
-
-\begin{methoddesc}[Context]{use_certificate_chain_file}{file}
-Load a certificate chain from \var{file} which must be PEM encoded.
-\end{methoddesc}
-
-\begin{methoddesc}[Context]{use_privatekey}{pkey}
-Use the private key \var{pkey} which has to be a PKey object.
-\end{methoddesc}
-
-\begin{methoddesc}[Context]{use_certificate_file}{file\optional{, format}}
-Load the first certificate found in \var{file}. The certificate must be in the
-format specified by \var{format}, which is either \constant{FILETYPE_PEM} or
-\constant{FILETYPE_ASN1}. The default is \constant{FILETYPE_PEM}.
-\end{methoddesc}
-
-\begin{methoddesc}[Context]{use_privatekey_file}{file\optional{, format}}
-Load the first private key found in \var{file}. The private key must be in the
-format specified by \var{format}, which is either \constant{FILETYPE_PEM} or
-\constant{FILETYPE_ASN1}. The default is \constant{FILETYPE_PEM}.
-\end{methoddesc}
-
-\begin{methoddesc}[Context]{set_tlsext_servername_callback}{callback}
-Specify a one-argument callable to use as the TLS extension server name
-callback.  When a connection using the server name extension is made using this
-context, the callback will be invoked with the \code{Connection} instance.
-\versionadded{0.13}
-\end{methoddesc}
-
-\subsubsection{Connection objects \label{openssl-connection}}
-
-Connection objects have the following methods:
-
-\begin{methoddesc}[Connection]{accept}{}
-Call the \method{accept} method of the underlying socket and set up SSL on the
-returned socket, using the Context object supplied to this Connection object at
-creation. Returns a pair \code{(\var{conn}, \var{address})}. where \var{conn}
-is the new Connection object created, and \var{address} is as returned by the
-socket's \method{accept}.
-\end{methoddesc}
-
-\begin{methoddesc}[Connection]{bind}{address}
-Call the \method{bind} method of the underlying socket.
-\end{methoddesc}
-
-\begin{methoddesc}[Connection]{close}{}
-Call the \method{close} method of the underlying socket. Note: If you want
-correct SSL closure, you need to call the \method{shutdown} method first.
-\end{methoddesc}
-
-\begin{methoddesc}[Connection]{connect}{address}
-Call the \method{connect} method of the underlying socket and set up SSL on the
-socket, using the Context object supplied to this Connection object at
-creation.
-\end{methoddesc}
-
-\begin{methoddesc}[Connection]{connect_ex}{address}
-Call the \method{connect_ex} method of the underlying socket and set up SSL on
-the socket, using the Context object supplied to this Connection object at
-creation. Note that if the \method{connect_ex} method of the socket doesn't
-return 0, SSL won't be initialized.
-\end{methoddesc}
-
-\begin{methoddesc}[Connection]{do_handshake}{}
-Perform an SSL handshake (usually called after \method{renegotiate} or one of
-\method{set_accept_state} or \method{set_accept_state}). This can raise the
-same exceptions as \method{send} and \method{recv}.
-\end{methoddesc}
-
-\begin{methoddesc}[Connection]{fileno}{}
-Retrieve the file descriptor number for the underlying socket.
-\end{methoddesc}
-
-\begin{methoddesc}[Connection]{listen}{backlog}
-Call the \method{listen} method of the underlying socket.
-\end{methoddesc}
-
-\begin{methoddesc}[Connection]{get_app_data}{}
-Retrieve application data as set by \method{set_app_data}.
-\end{methoddesc}
-
-\begin{methoddesc}[Connection]{get_cipher_list}{}
-Retrieve the list of ciphers used by the Connection object. WARNING: This API
-has changed. It used to take an optional parameter and just return a string,
-but not it returns the entire list in one go.
-\end{methoddesc}
-
-\begin{methoddesc}[Connection]{get_client_ca_list}{}
-Retrieve the list of preferred client certificate issuers sent by the server
-as \class{OpenSSL.crypto.X509Name} objects.
-
-If this is a client \class{Connection}, the list will be empty until the
-connection with the server is established.
-
-If this is a server \class{Connection}, return the list of certificate
-authorities that will be sent or has been sent to the client, as controlled
-by this \class{Connection}'s \class{Context}.
-
-\versionadded{0.10}
-\end{methoddesc}
-
-\begin{methoddesc}[Connection]{get_context}{}
-Retrieve the Context object associated with this Connection.
-\end{methoddesc}
-
-\begin{methoddesc}[Connection]{set_context}{context}
-Specify a replacement Context object for this Connection.
-\end{methoddesc}
-
-\begin{methoddesc}[Connection]{get_peer_certificate}{}
-Retrieve the other side's certificate (if any)
-\end{methoddesc}
-
-\begin{methoddesc}[Connection]{get_peer_cert_chain}{}
-Retrieve the tuple of the other side's certificate chain (if any)
-\end{methoddesc}
-
-\begin{methoddesc}[Connection]{getpeername}{}
-Call the \method{getpeername} method of the underlying socket.
-\end{methoddesc}
-
-\begin{methoddesc}[Connection]{getsockname}{}
-Call the \method{getsockname} method of the underlying socket.
-\end{methoddesc}
-
-\begin{methoddesc}[Connection]{getsockopt}{level, optname\optional{, buflen}}
-Call the \method{getsockopt} method of the underlying socket.
-\end{methoddesc}
-
-\begin{methoddesc}[Connection]{pending}{}
-Retrieve the number of bytes that can be safely read from the SSL buffer
-(\emph{not} the underlying transport buffer).
-\end{methoddesc}
-
-\begin{methoddesc}[Connection]{recv}{bufsize}
-Receive data from the Connection. The return value is a string representing the
-data received. The maximum amount of data to be received at once, is specified
-by \var{bufsize}.
-\end{methoddesc}
-
-\begin{methoddesc}[Connection]{bio_write}{bytes}
-If the Connection was created with a memory BIO, this method can be used to add
-bytes to the read end of that memory BIO.  The Connection can then read the
-bytes (for example, in response to a call to \method{recv}).
-\end{methoddesc}
-
-\begin{methoddesc}[Connection]{renegotiate}{}
-Renegotiate the SSL session. Call this if you wish to change cipher suites or
-anything like that.
-\end{methoddesc}
-
-\begin{methoddesc}[Connection]{send}{string}
-Send the \var{string} data to the Connection.
-\end{methoddesc}
-
-\begin{methoddesc}[Connection]{bio_read}{bufsize}
-If the Connection was created with a memory BIO, this method can be used to
-read bytes from the write end of that memory BIO.  Many Connection methods will
-add bytes which must be read in this manner or the buffer will eventually fill
-up and the Connection will be able to take no further actions.
-\end{methoddesc}
-
-\begin{methoddesc}[Connection]{sendall}{string}
-Send all of the \var{string} data to the Connection. This calls \method{send}
-repeatedly until all data is sent. If an error occurs, it's impossible to tell
-how much data has been sent.
-\end{methoddesc}
-
-\begin{methoddesc}[Connection]{set_accept_state}{}
-Set the connection to work in server mode. The handshake will be handled
-automatically by read/write.
-\end{methoddesc}
-
-\begin{methoddesc}[Connection]{set_app_data}{data}
-Associate \var{data} with this Connection object. \var{data} can be retrieved
-later using the \method{get_app_data} method.
-\end{methoddesc}
-
-\begin{methoddesc}[Connection]{set_connect_state}{}
-Set the connection to work in client mode. The handshake will be handled
-automatically by read/write.
-\end{methoddesc}
-
-\begin{methoddesc}[Connection]{setblocking}{flag}
-Call the \method{setblocking} method of the underlying socket.
-\end{methoddesc}
-
-\begin{methoddesc}[Connection]{setsockopt}{level, optname, value}
-Call the \method{setsockopt} method of the underlying socket.
-\end{methoddesc}
-
-\begin{methoddesc}[Connection]{shutdown}{}
-Send the shutdown message to the Connection. Returns true if the shutdown
-message exchange is completed and false otherwise (in which case you call
-\method{recv()} or \method{send()} when the connection becomes
-readable/writeable.
-\end{methoddesc}
-
-\begin{methoddesc}[Connection]{get_shutdown}{}
-Get the shutdown state of the Connection.  Returns a bitvector of either or
-both of \var{SENT_SHUTDOWN} and \var{RECEIVED_SHUTDOWN}.
-\end{methoddesc}
-
-\begin{methoddesc}[Connection]{set_shutdown}{state}
-Set the shutdown state of the Connection.  \var{state} is a bitvector of
-either or both of \var{SENT_SHUTDOWN} and \var{RECEIVED_SHUTDOWN}.
-\end{methoddesc}
-
-\begin{methoddesc}[Connection]{sock_shutdown}{how}
-Call the \method{shutdown} method of the underlying socket.
-\end{methoddesc}
-
-\begin{methoddesc}[Connection]{bio_shutdown}{}
-If the Connection was created with a memory BIO, this method can be used to
-indicate that ``end of file'' has been reached on the read end of that memory
-BIO.
-\end{methoddesc}
-
-\begin{methoddesc}[Connection]{state_string}{}
-Retrieve a verbose string detailing the state of the Connection.
-\end{methoddesc}
-
-\begin{methoddesc}[Connection]{client_random}{}
-Retrieve the random value used with the client hello message.
-\end{methoddesc}
-
-\begin{methoddesc}[Connection]{server_random}{}
-Retrieve the random value used with the server hello message.
-\end{methoddesc}
-
-\begin{methoddesc}[Connection]{master_key}{}
-Retrieve the value of the master key for this session.
-\end{methoddesc}
-
-\begin{methoddesc}[Connection]{want_read}{}
-Checks if more data has to be read from the transport layer to complete an
-operation.
-\end{methoddesc}
-
-\begin{methoddesc}[Connection]{want_write}{}
-Checks if there is data to write to the transport layer to complete an
-operation.
-\end{methoddesc}
-
-\begin{methoddesc}[Connection]{set_tlsext_host_name}{name}
-Specify the byte string to send as the server name in the client hello message.
-\versionadded{0.13}
-\end{methoddesc}
-
-\begin{methoddesc}[Connection]{get_servername}{}
-Get the value of the server name received in the client hello message.
-\versionadded{0.13}
-\end{methoddesc}
-
-
-
-
-
-\end{document}