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.
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/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:
+
+``crypto`` -- Generic cryptographic module
+==========================================
-.. automodule:: OpenSSL.crypto
- :members:
+.. py:data:: X509Type
-.. autoclass:: OpenSSL.crypto.X509
- :members:
-
-.. autoclass:: OpenSSL.crypto.X509Name
- :members:
-
-.. autoclass:: OpenSSL.crypto.X509Req
- :members:
-
-.. autoclass:: OpenSSL.crypto.X509StoreType
- :members:
-
-.. autoclass:: OpenSSL.crypto.PKey
- :members:
-
-.. autoclass:: OpenSSL.crypto.PKCS7Type
- :members:
-
-.. autoclass:: OpenSSL.crypto.PKCS12
- :members:
-
-.. autoclass:: OpenSSL.crypto.NetscapeSPKI
- :members:
-
-.. autoclass:: OpenSSL.crypto.CRL
- :members:
-
-.. autoclass:: OpenSSL.crypto.Revoked
- :members:
+ See :py:class:`X509`.
+.. py:class:: X509()
+
+ A class representing X.509 certificates.
+
+
+.. py:data:: X509NameType
+
+ See :py:class:`X509Name`.
+
+
+.. py:class:: X509Name(x509name)
+
+ A class representing X.509 Distinguished Names.
+
+ This constructor creates a copy of *x509name* which should be an
+ instance of :py:class:`X509Name`.
+
+
+.. py:data:: X509ReqType
+
+ See :py:class:`X509Req`.
+
+
+.. py:class:: X509Req()
+
+ A class representing X.509 certificate requests.
+
+
+.. py:data:: X509StoreType
+
+ A Python type object representing the X509Store object type.
+
+
+.. py:data:: PKeyType
+
+ See :py:class:`PKey`.
+
+
+.. py:class:: PKey()
+
+ A class representing DSA or RSA keys.
+
+
+.. py:data:: PKCS7Type
+
+ A Python type object representing the PKCS7 object type.
+
+
+.. py:data:: PKCS12Type
+
+ A Python type object representing the PKCS12 object type.
+
+
+.. py:data:: X509ExtensionType
+
+ See :py:class:`X509Extension`.
+
+
+.. py:class:: X509Extension(typename, critical, value[, subject][, issuer])
+
+ A class representing an X.509 v3 certificate extensions. See
+ http://openssl.org/docs/apps/x509v3_config.html#STANDARD_EXTENSIONS for
+ *typename* strings and their options. Optional parameters *subject* and
+ *issuer* must be X509 objects.
+
+
+.. py:data:: NetscapeSPKIType
+
+ See :py:class:`NetscapeSPKI`.
+
+
+.. py:class:: NetscapeSPKI([enc])
+
+ A class representing Netscape SPKI objects.
+
+ If the *enc* argument is present, it should be a base64-encoded string
+ representing a NetscapeSPKI object, as returned by the :py:meth:`b64_encode`
+ method.
+
+
+.. py:class:: CRL()
+
+ A class representing Certifcate Revocation List objects.
+
+
+.. py:class:: Revoked()
+
+ A class representing Revocation objects of CRL.
+
+
+.. py:data:: FILETYPE_PEM
+.. 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:
+
+``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`.
-.. automodule:: OpenSSL.rand
- :members:
+.. 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 @@
Contents:
.. toctree::
- :maxdepth: 2
+ :maxdepth: 3
introduction
install