ssl.SSLObject

class ssl.SSLObject

A reduced-scope variant of SSLSocket representing an SSL protocol instance that does not contain any network IO methods. This class is typically used by framework authors that want to implement asynchronous IO for SSL through memory buffers.

This class implements an interface on top of a low-level SSL object as implemented by OpenSSL. This object captures the state of an SSL connection but does not provide any network IO itself. IO needs to be performed through separate “BIO” objects which are OpenSSL’s IO abstraction layer.

An SSLObject instance can be created using the wrap_bio() method. This method will create the SSLObject instance and bind it to a pair of BIOs. The incoming BIO is used to pass data from Python to the SSL protocol instance, while the outgoing BIO is used to pass data the other way around.

The following methods are available:

• context
• server_side
• server_hostname
• read()
• write()
• getpeercert()
• selected_npn_protocol()
• cipher()
• shared_ciphers()
• compression()
• pending()
• do_handshake()
• unwrap()
• get_channel_binding()

When compared to SSLSocket, this object lacks the following features:

• Any form of network IO incluging methods such as recv() and send().
• There is no do_handshake_on_connect machinery. You must always manually call do_handshake() to start the handshake.
• There is no handling of suppress_ragged_eofs. All end-of-file conditions that are in violation of the protocol are reported via the SSLEOFError exception.
• The method unwrap() call does not return anything, unlike for an SSL socket where it returns the underlying socket.
• The server_name_callback callback passed to SSLContext.set_servername_callback() will get an SSLObject instance instead of a SSLSocket instance as its first parameter.

Some notes related to the use of SSLObject:

• All IO on an SSLObject is non-blocking. This means that for example read() will raise an SSLWantReadError if it needs more data than the incoming BIO has available.
• There is no module-level wrap_bio() call like there is for wrap_socket(). An SSLObject is always created via an SSLContext.