# NOQA aioopenssl — A transport for asyncio using OpenSSL ##################################################################

This package provides a socket-based asyncio.Transport which uses OpenSSL to create a TLS connection. Optionally, the TLS handshake can be deferred and performed later using STARTTLSTransport.starttls().

Note

Use this module at your own risk. It has lower test coverage than I’d like it to have; it has been exported from aioxmpp on request, where it undergoes implicit testing. If you find bugs, please report them. If possible, add regression tests while you’re at it.

If you find security-critical bugs, please follow the procedure announced in the aioxmpp readme.

The following function can be used to create a connection using the STARTTLSTransport, which itself is documented below:

aioopenssl.create_starttls_connection(loop: asyncio.base_events.BaseEventLoop, protocol_factory: Callable[[], asyncio.protocols.Protocol], host: Optional[str] = None, port: Optional[int] = None, *, sock: Optional[socket.socket] = None, ssl_context_factory: Optional[Callable[[asyncio.transports.Transport], OpenSSL.SSL.Context]] = None, use_starttls: bool = False, local_addr: Any = None, **kwargs) → Tuple[asyncio.transports.Transport, asyncio.protocols.Protocol]

Create a connection which can later be upgraded to use TLS.

Changed in version 0.4: The local_addr argument was added.

Parameters:

• loop (asyncio.BaseEventLoop) – The event loop to use.
• protocol_factory – Factory for the protocol for the connection
• host (str or None) – The host name or address to connect to
• port (int or None) – The port to connect to
• sock (socket.socket) – A socket to wrap (conflicts with host and port)
• ssl_context_factory – Function which returns a OpenSSL.SSL.Context to use for TLS operations
• use_starttls (bool) – Flag to control whether TLS is negotiated right away or deferredly.
• local_addr – Address to bind to

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. Further 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. This is typically a selector type event loop.

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.

If use_starttls is True, no TLS handshake will be performed initially. Instead, the connection is established without any transport-layer security. It is expected that the STARTTLSTransport.starttls() method is used when the application protocol requires TLS. If use_starttls is False, the TLS handshake is initiated right away.

local_addr may be an address to bind this side of the socket to. If omitted or None, the local address is assigned by the operating system.

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:

class aioopenssl.STARTTLSTransport(loop, rawsock, protocol, ssl_context_factory[, waiter=None][, use_starttls=False][, post_handshake_callback=None][, peer_hostname=None][, server_hostname=None])

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_factory must be a callable accepting a single positional argument which returns a OpenSSL.SSL.Context. The transport will be passed as the argument to the factory. The returned context will be used to create the OpenSSL.SSL.Connection when TLS is enabled on the transport. If the callable is None, a ssl_context must be supplied to starttls() and use_starttls must be true.

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.

abort() → None

Immediately close the stream, without sending remaining buffers or performing a proper shutdown.

can_starttls() → bool

Return True.

can_write_eof() → bool

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() → None

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.

get_extra_info(name: str, default: Optional[Any] = None) → Any

The following extra information is available:

• socket: the underlying socket object
• sslcontext: the OpenSSL.SSL.Context object to use (this may be None until starttls() has been called)
• ssl_object: OpenSSL.SSL.Connection object (None if TLS is not enabled (yet))
• peername: return value of socket.Socket.getpeername()
• peer_hostname: The peer_hostname value passed to the constructor.
• server_hostname: The server_hostname value passed to the constructor.

is_closing() → bool

Return True if the transport is closing or closed.

starttls(ssl_context: Optional[OpenSSL.SSL.Context] = None, post_handshake_callback: Optional[Callable[[STARTTLSTransport], Coroutine[Any, Any, None]]] = None) → None

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.

Changed in version 0.4: This method is now a barrier with respect to reads and writes: before the handshake is completed (including the post handshake callback, if any), no data is received or sent.

write(data: Union[bytes, bytearray, memoryview]) → None

Write data to the transport. This is an invalid operation if the stream is not writable, that is, if it is closed. During TLS negotiation, the data is buffered.

write_eof() → None

Writing the EOF has not been implemented, for the sake of simplicity.

Indices and tables

• Index
• Module Index
• Search Page