# `security_layer` — Implementations to negotiate stream security

This module provides different implementations of the security layer (TLS+SASL).

These are coupled, as different SASL features might need different TLS features (such as channel binding or client cert authentication). The preferred method to construct a `SecurityLayer` is using the `make()` function. `SecurityLayer` objects are needed to establish an XMPP connection, for example using `aioxmpp.Client`.

`aioxmpp.security_layer.``make`(password_provider, *, pin_store=None, pin_type=<PinType.PUBLIC_KEY: 0>, post_handshake_deferred_failure=None, anonymous=False, no_verify=False)

  Construct a `SecurityLayer`. Depending on the arguments passed, different features are enabled or disabled.

  Parameters:

  - password_provider (`str` or coroutine) – Source for the password to authenticate with.
  - pin_store (`dict` (compatible to `import_from_json()`) or `AbstractPinStore`) – Enable use of certificate pin store: if it is a `dict`, a new pin store is created (see pin_type argument) and filled with the data from the dict. Otherwise, the given pin store is used.
  - pin_type (`PinType`) – Type of pin store to use with a dict passed to pin_store (ignored if no dict is passed to pin_store).
  - post_handshake_deferred_failure (coroutine) – Coroutine to call when using pin store and the certificate is not in the pin store and fails PKI verification.
  - anonymous (`str` or `False`) – trace token for SASL ANONYMOUS (RFC 4505), enables ANONYMOUS authentication
  - no_verify (`bool`) – Disable all certificate verification. Usage is strongly discouraged outside controlled test environments. See below for alternatives.

  Raises: | RuntimeError – if anonymous is a `str` and the version of `aiosasl` in use does not provide `aiosasl.ANONYMOUS`
  Returns: | A new `SecurityLayer` instance configured as per the arguments.

  password_provider must either be a coroutine or a `str`. As a coroutine, it is called during authentication with the JID we are trying to authenticate against as the first, and the sequence number of the authentication attempt as second argument. The sequence number starts at 0. The coroutine is expected to return `None` or a password. See `PasswordSASLProvider` for details. If it is a `str`, a coroutine which returns the string on the first and `None` on subsequent attempts is created and used.

  If pin_store is not `None`, `PinningPKIXCertificateVerifier` is used instead of the default `PKIXCertificateVerifier`. The pin_store argument determines the pinned certificates: if it is a dictionary, a `AbstractPinStore` according to the `PinType` passed as pin_type argument is created and initialised with the data from the dictionary using its `import_from_json()` method. Otherwise, pin_store must be a `AbstractPinStore` instance which is passed to the verifier.

  post_handshake_deferred_callback is used only if pin_store is not `None`. It is passed to the equally-named argument of `PinningPKIXCertificateVerifier`, see the documentation there for details on the semantics. If post_handshake_deferred_callback is `None` while pin_store is not, a coroutine which returns `False` is substituted.

  If no_verify is true, none of the above regarding certificate verifiers matters. The internal null verifier is used, which disables certificate verification completely.

  Warning

  Disabling certificate verification makes your application vulnerable to trivial Man-in-the-Middle attacks. Do not use this outside controlled test environments.

  If you need to handle certificates which cannot be verified using the public key infrastructure, consider making use of the pin_store argument instead.

  anonymous may be a string or `False`. If it is not `False`, `AnonymousSASLProvider` is used before password based authentication is attempted. In addition, it is allowed to set password_provider to `None`. anonymous is the trace token to use, and SHOULD be the empty string (as specified by XEP-0175). This requires `aiosasl` 0.3 or newer.

  Note

  `False` and `""` are treated differently for the anonymous argument, despite both being false-y values!

  Warning

  Take the security and privacy considerations from RFC 4505 (which specifies the ANONYMOUS SASL mechanism) and XEP-0175 (which discusses the ANONYMOUS SASL mechanism in the XMPP context) into account before using anonymous.

  The versaility and simplicity of use of this function make (pun intended) it the preferred way to construct `SecurityLayer` instances.

  New in version 0.8: Support for SASL ANONYMOUS was added.

class `aioxmpp.security_layer.``PinType`

  Enumeration to control which pinning is used by `make()`.

  `PUBLIC_KEY`

    Public keys are stored in the pin store. `PublicKeyPinStore` is used.

  `CERTIFICATE`

    Whole certificates are stored in the pin store. `CertificatePinStore` is used.

`aioxmpp.security_layer.``tls_with_password_based_authentication`(password_provider[, ssl_context_factory][, max_auth_attempts=3])

  Produce a commonly used `SecurityLayer`, which uses TLS and password-based SASL authentication. If ssl_context_factory is not provided, an SSL context with TLSv1+ is used.

  password_provider must be a coroutine which is called with the jid as first and the number of attempt as second argument. It must return the password to us, or `None` to abort.

  Return a `SecurityLayer` instance.

  Deprecated since version 0.7: Use `make()` instead.

class `aioxmpp.security_layer.``SecurityLayer`(ssl_context_factory, certificate_verifier_factory, tls_required, sasl_providers)

  A security layer defines the security properties used for an XML stream. This includes TLS settings and SASL providers. The arguments are used to initialise the attributes of the same name.

  `SecurityLayer` instances are required to construct a `aioxmpp.Client`.

  New in version 0.6.

  See also

  `make()`
    A powerful function which can be used to create a configured `SecurityLayer` instance.
  `ssl_context_factory`

    This is a callable returning a `OpenSSL.SSL.Context` instance which is to be used for any SSL operations for the connection.

    The `OpenSSL.SSL.Context` instances should not be resued between connection attempts, as the certificate verifiers may set options which cannot be disabled anymore.

  `certificate_verifier_factory`

    This is a callable which returns a fresh `CertificateVerifier` on each call (it must be a fresh instance since `CertificateVerifier` objects are allowed to keep state and `SecurityLayer` objects are reusable between connection attempts).

  `tls_required`

    A boolean which indicates whether TLS is required. If it is set to true, connectors (see `aioxmpp.connector`) will abort the connection if TLS (or something equivalent) is not available on the transport.

    Note

    Disabling this makes your application vulnerable to STARTTLS stripping attacks.

  `sasl_providers`

    A sequence of `SASLProvider` instances. As SASL providers are stateless, it is not necessary to create new providers for each connection.

coroutine `aioxmpp.security_layer.``negotiate_sasl`(transport, xmlstream, sasl_providers, negotiation_timeout, jid, features)

  Perform SASL authentication on the given `protocol.XMLStream` stream. transport must be the `asyncio.Transport` over which the stream runs. It is used to detect whether TLS is used and may be required by some SASL mechanisms.

  sasl_providers must be an iterable of `SASLProvider` objects. They will be tried in iteration order to authenticate against the server. If one of the sasl_providers fails with a `aiosasl.AuthenticationFailure` exception, the other providers are still tried; only if all providers fail, the last `aiosasl.AuthenticationFailure` exception is re-raised.

  If no mechanism was able to authenticate but not due to authentication failures (other failures include no matching mechanism on the server side), `aiosasl.SASLUnavailable` is raised.

  Return the `nonza.StreamFeatures` obtained after resetting the stream after successful SASL authentication.

  New in version 0.6.

  Deprecated since version 0.10: The negotiation_timeout argument is ignored. The timeout is controlled using the `deadtime_hard_limit` timeout of the stream.

  The argument will be removed in version 1.0. To prepare for this, please pass jid and features as keyword arguments.

## Certificate verifiers

To verify the peer certificate provided by the server, different :class:`CertificateVerifier`s are available:

class `aioxmpp.security_layer.``PKIXCertificateVerifier`

  This verifier enables the default PKIX based verification of certificates as implemented by OpenSSL.

  The `verify_callback()` checks that the certificate subject matches the domain name of the JID of the connection.

To implement your own verifiers, see the documentation at the base class for certificate verifiers:

class `aioxmpp.security_layer.``CertificateVerifier`

  A certificate verifier hooks into the two mechanisms provided by `aioopenssl.STARTTLSTransport` for certificate verification.

  On the one hand, the verify callback provided by `OpenSSL.SSL.Context` is used and forwarded to `verify_callback()`. On the other hand, the post handshake coroutine is set to `post_handshake()`. See the documentation of `aioopenssl.STARTTLSTransport` for the semantics of that coroutine.

  In addition to these two hooks into the TLS handshake, a third coroutine which is called before STARTTLS is intiiated is provided.

  This baseclass provides a bit of boilerplate.

### Certificate and key pinning

Often in the XMPP world, we need certificate or public key pinning, as most XMPP servers do not have certificates trusted by the usual certificate stores. This module also provide certificate verifiers which can be used for that purpose, as well as stores for saving the pinned information.

class `aioxmpp.security_layer.``PinningPKIXCertificateVerifier`(query_pin, post_handshake_deferred_failure, post_handshake_success=None)

  The `PinningPKIXCertificateVerifier` is a subclass of the `HookablePKIXCertificateVerifier` which uses the hooks to implement certificate or public key pinning.

  It does not store the pins itself. Instead, the user must pass a callable to the query_pin argument. That callable will be called with two arguments: the servername and the x509. The x509 is a `OpenSSL.crypto.X509` instance, which is the leaf certificate which attempts to identify the host. The servername is the name of the server we try to connect to (the identifying name, like the domain part of the JID). The callable must return `True` (to accept the certificate), `False` (to reject the certificate) or `None` (to defer the decision to the post_handshake_deferred_failure callback). query_pin must not block; if it needs to do blocking operations, it should defer.

  The other two arguments are coroutines with semantics identical to those of the same-named arguments in `HookablePKIXCertificateVerifier`.

  See also

  `AbstractPinStore.query()` is a method which can be passed as query_pin callback.

class `aioxmpp.security_layer.``CertificatePinStore`

  This pin store stores the whole certificates which are passed to its `pin()` method.

class `aioxmpp.security_layer.``PublicKeyPinStore`

  This pin store stores the public keys of the X.509 objects which are passed to its `pin()` method.

#### Base classes

For future expansion or customization, the base classes of the above utilities can be subclassed and extended:

class `aioxmpp.security_layer.``HookablePKIXCertificateVerifier`(quick_check, post_handshake_deferred_failure, post_handshake_success)

  This PKIX-based verifier has several hooks which allow overriding of the checking process, for example to implement key or certificate pinning.

  It provides three callbacks:

  - quick_check is a synchronous callback (and must be a plain function) which is called from `verify_callback()`. It is only called if the certificate fails full PKIX verification, and only for certain cases. For example, expired certificates do not get a second chance and are rejected immediately.

    It is called with the leaf certificate as its only argument. It must return `True` if the certificate is known good and should pass the verification. If the certificate is known bad and should fail the verification immediately, it must return `False`.

    If the certificate is unknown and the check should be deferred to the post_handshake_deferred_failure callback, `None` must be returned.

    Passing `None` to quick_check is the same as if a callable passed to quick_check would return `None` always (i.e. the decision is deferred).

  - post_handshake_deferred_failure must be a coroutine. It is called after the handshake is done but before the STARTTLS negotiation has finished and allows the application to take more time to decide on a certificate and possibly request user input.

    The coroutine receives the verifier instance as its argument and can make use of all the verification attributes to present the user with a sensible choice.

    If post_handshake_deferred_failure is `None`, the result is identical to returning `False` from the callback.

  - post_handshake_success is only called if the certificate has passed the verification (either because it flawlessly passed by OpenSSL or the quick_check callback returned `True`).

    You may pass `None` to this argument to disable the callback without any further side effects.

  The following attributes are available when the post handshake callbacks are called:

  `recorded_errors`

    This is a `set` with tuples consisting of a `OpenSSL.crypto.X509` instance, an OpenSSL error number and the depth of the certificate in the verification chain (0 is the leaf certificate).

    It is a collection of all errors which were passed into `verify_callback()` by OpenSSL.

  `hostname_matches`

    This is `True` if the host name in the leaf certificate matches the domain part of the JID for which we are connecting (i.e. the usual server name check).

  `leaf_x509`

    The `OpenSSL.crypto.X509` object which represents the leaf certificate.

class `aioxmpp.security_layer.``AbstractPinStore`

  This is the abstract base class for both `PublicKeyPinStore` and `CerificatePinStore`. The interface for both types of pinning is identical; the only difference is in which information is stored.

  `pin`(hostname, x509)

    Pin an `OpenSSL.crypto.X509` object x509 for use with the given hostname. Which information exactly is used to identify the certificate depends `_x509_key()`.

  `query`(hostname, x509)

    Return true if the given `OpenSSL.crypto.X509` object x509 has previously been pinned for use with the given hostname and `None` otherwise.

    Returning `None` allows this method to be used with `PinningPKIXCertificateVerifier`.

  `get_pinned_for_host`(hostname)

    Return the set of hashable values which are used to identify the X.509 certificates which are accepted for the given hostname.

    If no values have previously been pinned, this returns the empty set.

  `export_to_json`()

    Return a JSON dictionary which contains all the pins stored in this store.

  `import_from_json`(data, *, override=False)

    Import a JSON dictionary which must have the same format as exported by `export()`.

    If override is true, the existing data in the pin store will be overriden with the data from data. Otherwise, the data will be merged into the store.

  For subclasses:

  `_encode_key`(key)

    Encode the key (which has previously been obtained from `_x509_key()`) into a string which is both JSON compatible and can be used as XML text (which means that it must not contain control characters, for example).

    The method is called by `export_to_json()`. The default implementation returns key.

  `_decode_key`(obj)

    Decode the obj into a key which is compatible to the values returned by `_x509_key()`.

    The method is called by `import_from_json()`. The default implementation returns obj.

  `_x509_key`(key)

    Return a hashable value which identifies the given x509 certificate for the purposes of the key store. See the implementations `PublicKeyPinStore._x509_key()` and `CertificatePinStore._x509_key()` for details on what is stored for the respective subclasses.

    This method is abstract and must be implemented in subclasses.

## SASL providers

As elements of the sasl_providers argument to `SecurityLayer`, instances of the following classes can be used:

class `aioxmpp.security_layer.``PasswordSASLProvider`(password_provider, *, max_auth_attempts=3, **kwargs)

  Perform password-based SASL authentication.

  Parameters:

  - password_provider (coroutine function) – A coroutine function returning the password to authenticate with.
  - max_auth_attempts (positive `int`) – Maximum number of authentication attempts with a single mechansim.

  password_provider must be a coroutine taking two arguments, a JID and an integer number. The first argument is the JID which is trying to authenticate and the second argument is the number of the authentication attempt, starting at 0. On each attempt, the number is increased, up to max_auth_attempts-1. If the coroutine returns `None`, the authentication process is aborted. If the number of attempts are exceeded, the authentication process is also aborted. In both cases, an `aiosasl.AuthenticationFailure` error will be raised.

  The SASL mechanisms used depend on whether TLS has been negotiated successfully before. In any case, `aiosasl.SCRAM` is used. If TLS has been negotiated, `aiosasl.PLAIN` is also supported.

  See also

  `SASLProvider`
    for the public interface of this class.

class `aioxmpp.security_layer.``AnonymousSASLProvider`(token)

  Perform the `ANONYMOUS` SASL mechanism (RFC 4505).

  Parameters: | token (`str`) – The trace token for the `ANONYMOUS` mechanism

  token SHOULD be the empty string in the XMPP context (see XEP-0175).

  See also

  `SASLProvider`
    for the public interface of this class.

  Warning

  Take the security and privacy considerations from RFC 4505 (which specifies the ANONYMOUS SASL mechanism) and XEP-0175 (which discusses the ANONYMOUS SASL mechanism in the XMPP context) into account before using this provider.

  Note

  This class requires `aiosasl.ANONYMOUS`, which is available with `aiosasl` 0.3 or newer. If `aiosasl.ANONYMOUS` is not provided, this class is replaced with `None`.

  New in version 0.8.

Note

Patches welcome for additional `SASLProvider` implementations.

## Abstract base classes

For implementation of custom SASL providers, the following base class can be used:

class `aioxmpp.security_layer.``SASLProvider`

  Base class to implement a SASL provider.

  SASL providers are used in `SecurityLayer` to authenticate the local user with a service. The credentials required depend on the specific SASL provider, and it is recommended to acquire means to get these credentials via constructor parameters (see for example `PasswordSASLProvider`).

  The following methods must be implemented by subclasses:

  coroutine `execute`(client_jid, features, xmlstream, tls_transport)

    Perform SASL negotiation.

    Parameters:

    - client_jid (`aioxmpp.JID`) – The JID the client attempts to authenticate for
    - features (`StreamFeatures`) – Current stream features nonza
    - xmlstream (`XMLStream`) – The XML stream to authenticate over
    - tls_transport (`asyncio.Transport` or `None`) – The TLS transport or `None` if no TLS has been negotiated

    Raises:

    - aiosasl.AuthenticationFailure – if authentication failed due to bad credentials
    - aiosasl.SASLFailure – on other SASL-related errors

    Returns: | true if the negotiation was successful, false if no common mechanisms could be found or all mechanisms failed for reasons unrelated to the credentials themselves.
    Return type: | `bool`

    The implementation depends on the specific `SASLProvider` subclass in use.

    This coroutine returns `True` if the negotiation was successful. If no common mechanisms could be found, `False` is returned. This is useful to chain several SASL providers (e.g. a provider supporting `EXTERNAL` in front of password-based providers).

    Any other error case, such as no SASL support on the remote side or authentication failure results in an `aiosasl.SASLFailure` exception to be raised.

  The following methods are intended to be re-used by subclasses:

  coroutine `_execute`(intf, mechanism, token)

    Execute a SASL authentication process.

    Parameters:

    - intf (`SASLXMPPInterface`) – SASL interface to use
    - mechanism (`aiosasl.SASLMechanism`) – SASL mechanism to use
    - token (not `None`) – The opaque token argument for the mechanism

    Raises:

    - aiosasl.AuthenticationFailure – if authentication failed due to bad credentials
    - aiosasl.SASLFailure – on other SASL error conditions (such as protocol violations)

    Returns: | true if authentication succeeded, false if the mechanism has to be disabled
    Return type: | `bool`

    This executes the SASL authentication process. The more specific exceptions are generated by inspecting the `aiosasl.SASLFailure.opaque_error` on exceptinos raised from the `SASLXMPPInterface`. Other `aiosasl.SASLFailure` exceptions are re-raised without modification.

  `_find_supported`(features, mechanism_classes)

    Find the first mechansim class which supports a mechanism announced in the given stream features.

    Parameters:

    - features (`StreamFeatures`) – Current XMPP stream features
    - mechanism_classes (iterable of `SASLMechanism` subclasses) – SASL mechanism classes to use

    Raises: | aioxmpp.errors.SASLUnavailable – if the peer does not announce SASL support
    Returns: | the `SASLMechanism` subclass to use and a token
    Return type: | pair

    Return a supported SASL mechanism class, by looking the given stream features features.

    If no matching mechanism is found, `(None, None)` is returned. Otherwise, a pair consisting of the mechanism class and the value returned by the respective `any_supported()` method is returned. The latter is an opaque token which must be passed to the token argument of `_execute()` or `aiosasl.SASLMechanism.authenticate()`.

## Deprecated functionality

In pre-0.6 code, you might find use of the following things:

`aioxmpp.security_layer.``security_layer`(tls_provider, sasl_providers)

  Deprecated since version 0.6: Replaced by `SecurityLayer`.

  Return a configured `SecurityLayer`. tls_provider must be a `STARTTLSProvider`.

  The return value can be passed to the constructor of `Client`.

  Some very basic checking on the input is also performed.

class `aioxmpp.security_layer.``STARTTLSProvider`(ssl_context_factory, certificate_verifier_factory=<class 'aioxmpp.security_layer.PKIXCertificateVerifier'>, *, require_starttls=True)

  Deprecated since version 0.6: Do not use this. This is a shim class which provides backward-compatibility for versions older than 0.6.