  RATIONALE

The reason this module exists at all is that the SSL support in the socket
module in the Python 2.1 distribution (which is what we used, of course I
cannot speak for later versions) is severely limited.

<FIXME> Update this list whenever needed! The communications module isn't
written yet, so we don't know exactly how this'll work! </FIXME>
This is a list of things we need from an OpenSSL module:
 + Context objects (in OpenSSL called SSL_CTX) that can be manipulated from
   Python modules.  They must support a number of operations:
     - Loading certificates from file and memory, both the client
       certificate and the certificates used for the verification chain.
     - Loading private keys from file and memory.
     - Setting the verification mode (basically VERIFY_NONE and
       VERIFY_PEER).
     - Callbacks mechanism for prompting for pass phrases and verifying
       certificates.  The callbacks have to work under a multi-threaded
       environment (see the comment in ssl/context.c).  Of course the
       callbacks will have to be written in Python!
 + The Connection objects (in OpenSSL called SSL) have to support a few
   things:
     - Renegotiation, this is really important, especially for connections
       that are up and running for a long time, since renegotiation
       generates new encryption keys.
     - Server-side SSL must work!  As far as I know this doesn't work in
       the SSL support of the socket module as of Python 2.1.
     - Wrapping the methods of the underlying transport object is nice, so
       you don't have to keep track of more than one object per connection.
       This could of course be done a lot better than the way it works now,
       so more transport layers than sockets are possible!
 + A well-organized error system that mimics OpenSSL's error system is
   desireable.  Specifically there has to be a way to find out wether the
   operation was successful, or if it failed, why it failed, so some sort
   of interface to OpenSSL's error queue mechanism is needed.
 + Certificate objects (X509) and certificate name objects (X509_NAME) are
   needed, especially for verification purposes.  Certificates will
   probably also be generated by the server which is another reason for
   them to exist. The same thing goes for key objects (EVP_PKEY)
 + Since this is an OpenSSL module, there has to be an interface to the
   OpenSSL PRNG, so it can be seeded in a good way.

When asking about SSL on the comp.lang.python newsgroup (or on
python-list@python.org) people usually pointed you to the M2Crypto package.
The M2Crypto.SSL module does implement a lot of OpenSSL's functionality but
unfortunately its error handling system does not seem to be finished,
especially for non-blocking I/O.  I think that much of the reason for this
is that M2Crypto is developed using SWIG.  This makes it awkward to create
functions that e.g. can return both an integer and NULL since (as far as I
know) you basically write C functions and SWIG makes wrapper functions that
parses the Python argument list and calls your C function, and finally
transforms your return value to a Python object.

Finally, a good book on the topic of SSL (that I read and learned a lot
from) is "SSL and TLS - Designing and Building Secure Systems" (ISBN
0201615983) by Eric Rescorla. A good mailinglist to subscribe to is the
openssl-users@openssl.org list.

This comment was written July 2001, discussing Python 2.1.  Feel free to
modify it as the SSL support in the socket module changes.