# 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:

async `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: Optional[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.

  async `starttls`(ssl_context: Optional[OpenSSL.SSL.Context] = None, post_handshake_callback: Optional[Callable[[aioopenssl.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