connector — Ways to establish XML streams

This module provides classes to establish XML streams. Currently, there are two different ways to establish XML streams: normal TCP connection which is then upgraded using STARTTLS, and directly using TLS.

New in version 0.6: The whole module was added in version 0.6.

Abstract base class

The connectors share a common abstract base class, BaseConnector:

class aioxmpp.connector.BaseConnector

This is the base class for connectors. It defines the public interface of all connectors.

tls_supported

Boolean which indicates whether TLS is supported by this connector.

coroutine connect(loop, metadata, domain, host, port, negotiation_timeout, base_logger=None)

Establish a protocol.XMLStream for domain with the given host at the given TCP port.

metadata must be a security_layer.SecurityLayer instance to use for the connection. loop must be a asyncio.BaseEventLoop to use.

negotiation_timeout must be the maximum time in seconds to wait for the server to reply in each negotiation step. The negotiation_timeout is used as value for deadtime_hard_limit in the returned stream.

Return a triple consisting of the asyncio.Transport, the protocol.XMLStream and the aioxmpp.nonza.StreamFeatures of the stream.

To detect the use of TLS on the stream, check whether asyncio.Transport.get_extra_info() returns a non-None value for "ssl_object".

base_logger is passed to aioxmpp.protocol.XMLStream.

Changed in version 0.10: Assignment of deadtime_hard_limit was added.

Existing connectors:

STARTTLSConnector	Establish an XML stream using STARTTLS.
XMPPOverTLSConnector	Establish an XML stream using XMPP-over-TLS, as per XEP-0368.

Specific connectors

class aioxmpp.connector.STARTTLSConnector

Establish an XML stream using STARTTLS.

coroutine connect(loop, metadata, domain: str, host, port, negotiation_timeout, base_logger=None)

See also

BaseConnector.connect()

For general information on the connect() method.

Connect to host at TCP port number port. The aioxmpp.security_layer.SecurityLayer object metadata is used to determine the parameters of the TLS connection.

First, a normal TCP connection is opened and the stream header is sent. The stream features are waited for, and then STARTTLS is negotiated if possible.

tls_required is honoured: if it is true and TLS negotiation fails, TLSUnavailable is raised. TLS negotiation is always attempted if tls_required is true, even if the server does not advertise a STARTTLS stream feature. This might help to prevent trivial downgrade attacks, and we don’t have anything to lose at this point anymore anyways.

ssl_context_factory and certificate_verifier_factory are used to configure the TLS connection.

Changed in version 0.10: The negotiation_timeout is set as deadtime_hard_limit on the returned XML stream.

class aioxmpp.connector.XMPPOverTLSConnector

Establish an XML stream using XMPP-over-TLS, as per XEP-0368.

coroutine connect(loop, metadata, domain, host, port, negotiation_timeout, base_logger=None)

See also

BaseConnector.connect()

For general information on the connect() method.

Connect to host at TCP port number port. The aioxmpp.security_layer.SecurityLayer object metadata is used to determine the parameters of the TLS connection.

The connector connects to the server by directly establishing TLS; no XML stream is started before TLS negotiation, in accordance to XEP-0368 and how legacy SSL was handled in the past.

ssl_context_factory and certificate_verifier_factory are used to configure the TLS connection.

Changed in version 0.10: The negotiation_timeout is set as deadtime_hard_limit on the returned XML stream.