This module provides a socket-based Transport for asyncio which supports deferred TLS as used by the STARTTLS mechanism. In addition it uses OpenSSL instead of the built-in ssl module, to provide this and more sophisticated functionality.
The following function can be used to create a connection using the STARTTLSTransport, which itself is documented below:
This is roughly a copy of the asyncio implementation of asyncio.BaseEventLoop.create_connection(). It returns a pair (transport, protocol), where transport is a newly created STARTTLSTransport instance. The keyword arguments are forwarded to the constructor of STARTTLSTransport.
loop must be a asyncio.BaseEventLoop, with support for asyncio.BaseEventLoop.add_reader() and the corresponding writer and removal functions for sockets.
protocol_factory must be a callable which (without any arguments) returns a asyncio.Protocol which will be connected to the STARTTLS transport.
host and port must be a hostname and a port number, or both None. Both must be None, if and only if sock is not None. In that case, sock is used instead of a newly created socket. sock is put into non-blocking mode and must be a stream socket.
This coroutine returns when the stream is established. If use_starttls is False, this means that the full TLS handshake has to be finished for this coroutine to return. Otherwise, no TLS handshake takes place. It must be invoked using the STARTTLSTransport.starttls() coroutine.
The transport implementation is documented below:
Create a new asyncio.Transport which supports TLS and the deferred starting of TLS using the starttls() method.
loop must be a asyncio.BaseEventLoop with support for BaseEventLoop.add_reader() as well as removal and the writer complements.
rawsock must be a socket.socket which will be used as the socket for the transport. protocol must be a asyncio.Protocol which will be fed the data the transport receives.
ssl_context must be a OpenSSL.SSL.Context. It will be used to create the OpenSSL.SSL.Connection when TLS is enabled on the transport.
use_starttls must be a boolean value. If it is true, TLS is not enabled immediately. Instead, the user must call starttls() to enable TLS on the transport. Until that point, the transport is unencrypted. If it is false, the TLS handshake is started immediately. This is roughly equivalent to calling starttls() immediately.
peer_hostname must be either a str or None. It may be used by certificate validators and must be the host name this transport actually connected to. That might be (e.g. in the case of XMPP) different from the actual domain name the transport communicates with (and for which the service must have a valid certificate). This host name may be used by certificate validators implementing e.g. DANE.
server_hostname must be either a str or None. It may be used by certificate validators anrd must be the host name for which the peer must have a valid certificate (if host name based certificate validation is performed). server_hostname is also passed via the TLS Server Name Indication (SNI) extension if it is given.
If host names are to be converted to bytes by the transport, they are encoded using the ``utf-8` codec.
If waiter is not None, it must be a asyncio.Future. After the stream has been established, the futures result is set to a value of None. If any errors occur, the exception is set on the future.
If use_starttls is true, the future is fulfilled immediately after construction, as there is no blocking process which needs to take place. If use_starttls is false and thus TLS negotiation starts right away, the future is fulfilled when TLS negotiation is complete.
post_handshake_callback may be a coroutine or None. If it is not None, it is called asynchronously after the TLS handshake and blocks the completion of the TLS handshake until it returns.
It can be used to perform blocking post-handshake certificate verification, e.g. using DANE. The coroutine must not return a value. If it encounters an error, an appropriate exception should be raised, which will propagate out of starttls() and/or passed to the waiter future.
Immediately close the stream, without sending remaining buffers or performing a proper shutdown.
Return False.
Note
Writing of EOF (i.e. closing the sending direction of the stream) is theoretically possible. However, it was deemed by the author that the case is rare enough to neglect it for the sake of implementation simplicity.
Close the stream. This performs a proper stream shutdown, except if the stream is currently performing a TLS handshake. In that case, calling close() is equivalent to calling abort().
Otherwise, the transport waits until all buffers are transmitted.
The following extra information is available:
Start a TLS stream on top of the socket. This is an invalid operation if the stream is not in RAW_OPEN state.
If ssl_context is set, it overrides the ssl_context passed to the constructor. If post_handshake_callback is set, it overrides the post_handshake_callback passed to the constructor.