# `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.