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

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

This module handles things specific to SSL. There are two objects defined: Context, Connection.

SSLv2_METHOD
SSLv3_METHOD
SSLv23_METHOD
TLSv1_METHOD: These constants represent the different SSL methods to use when creating a context object.

VERIFY_NONE
VERIFY_PEER
VERIFY_FAIL_IF_NO_PEER_CERT: These constants represent the verification mode used by the Context object's set_verify method.

FILETYPE_PEM
FILETYPE_ASN1: File type constants used with the use_certificate_file and use_privatekey_file methods of Context objects.

OP_SINGLE_DH_USE
OP_EPHEMERAL_RSA
OP_NO_SSLv2
OP_NO_SSLv3
OP_NO_TLSv1: Constants used with set_options of Context objects. OP_SINGLE_DH_USE means to always create a new key when using ephemeral Diffie-Hellman. OP_EPHEMERAL_RSA means to always use ephemeral RSA keys when doing RSA operations. OP_NO_SSLv2, OP_NO_SSLv3 and OP_NO_TLSv1 means to disable those specific protocols. This is interesting if you're using e.g. SSLv23_METHOD to get an SSLv2-compatible handshake, but don't want to use SSLv2.

Context(method): Factory function that creates a new Context object given an SSL method. The method should be SSLv2_METHOD, SSLv3_METHOD, SSLv23_METHOD or TLSv1_METHOD.

ConnectionType: A Python type object representing the Connection object type.

Connection(context, socket): Factory fucnction that creates a new Connection object given an SSL context and a socket ³ object.

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 err(3) for more information.

exception ZeroReturnError: This exception matches the error return 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 SSL_ERROR code, and is very convenient.

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.

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.

exception SysCallError: The 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).

... 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!