Go to the latest version of this document.
search in docstrings

Search bar offers the following options:

- Term presence. The below example searches for documents that must contain “foo”, might contain “bar” and must not contain “baz”: `+foo bar -baz`
- Wildcards. The below example searches for documents with words beginning with “foo”: `foo*`
- Search in specific fields. The following search matches all objects in "twisted.mail" that matches “search”: `+qname:twisted.mail.* +search`

  Possible fields: 'name', 'qname' (fully qualified name), 'docstring', and 'kind'. Last two fields are only applicable if "search in docstrings" is enabled.

- Fuzzy matches. The following search matches all documents that have a word within 1 edit distance of “foo”: `foo~1`

Results provided by Lunr.js

# ``twisted`.`internet`.`ssl``

module documentation
(source)

This module implements Transport Layer Security (TLS) support for Twisted. It requires PyOpenSSL.

If you wish to establish a TLS connection, please use one of the following APIs:

- SSL endpoints for `servers` and `clients`
- `startTLS`
- `connectSSL`
- `listenSSL`

These APIs all require a `contextFactory` argument that specifies their security properties, such as certificate, private key, certificate authorities to verify the peer, allowed TLS protocol versions, cipher suites, and so on. The recommended value for this argument is a `CertificateOptions` instance; see its documentation for an explanation of the available options.

The `contextFactory` name is a bit of an anachronism now, as context factories have been replaced with "connection creators", but these objects serve the same role.

Be warned that implementing your own connection creator (i.e.: value for the `contextFactory`) is both difficult and dangerous; the Twisted team has worked hard to make `CertificateOptions`' API comprehensible and unsurprising, and the Twisted team is actively maintaining it to ensure that it becomes more secure over time.

If you are really absolutely sure that you want to take on the risk of implementing your own connection creator based on the pyOpenSSL API, see the `server connection creator` and `client connection creator` interfaces.

Developers using Twisted, please ignore the `Port`, `Connector`, and `Client` classes defined here, as these are details of certain reactors' TLS implementations, exposed by accident (and remaining here only for compatibility reasons). If you wish to establish a TLS connection, please use one of the APIs listed above.

Note
"SSL" (Secure Sockets Layer) is an antiquated synonym for "TLS" (Transport Layer Security). You may see these terms used interchangeably throughout the documentation.

Class | `AcceptableCiphers` | A representation of ciphers that are acceptable for TLS connections.
Class | `Certificate` | An x509 certificate.
Class | `CertificateOptions` | A `CertificateOptions` specifies the security properties for a client or server TLS connection used with OpenSSL.
Class | `CertificateRequest` | An x509 certificate request.
Class | `Client` | I am an SSL client.
Class | `ClientContextFactory` | A context factory for SSL clients.
Class | `Connector` | Undocumented
Class | `ContextFactory` | A factory for SSL context objects, for server SSL connections.
Class | `DefaultOpenSSLContextFactory` | `DefaultOpenSSLContextFactory` is a factory for server-side SSL context objects. These objects define certain parameters related to SSL handshakes and the subsequent connection.
Class | `DiffieHellmanParameters` | A representation of key generation parameters that are required for Diffie-Hellman key exchange.
Class | `DistinguishedName` | Identify and describe an entity.
Class | `KeyPair` | No class docstring; 3/10 methods, 0/2 class method documented
Class | `OpenSSLDefaultPaths` | Trust the set of default verify paths that OpenSSL was built with, as specified by SSL_CTX_set_default_verify_paths.
Class | `Port` | I am an SSL port.
Class | `PrivateCertificate` | An x509 certificate and private key.
Class | `ProtocolNegotiationSupport` | `ProtocolNegotiationSupport` defines flags which are used to indicate the level of NPN/ALPN support provided by the TLS backend.
Class | `Server` | I am an SSL server.
Class | `TLSVersion` | TLS versions that we can negotiate with the client/server.
Function | `optionsForClientTLS` | Create a `client connection creator` for use with APIs such as `SSL4ClientEndpoint`, `connectSSL`, and `startTLS`.
Function | `platformTrust` | Attempt to discover a set of trusted certificate authority certificates (or, in other words: trust roots, or root certificates) whose trust is managed and updated by tools outside of Twisted.
Function | `protocolNegotiationMechanisms` | Checks whether your versions of PyOpenSSL and OpenSSL are recent enough to support protocol negotiation, and if they are, what kind of protocol negotiation is supported.
Function | `trustRootFromCertificates` | Builds an object that trusts multiple root `Certificate`s.
Variable | `supported` | Undocumented
Variable | `VerificationError` | Undocumented

def optionsForClientTLS(hostname, trustRoot=None, clientCertificate=None, acceptableProtocols=None, *, extraCertificateOptions=None): (source)

Create a `client connection creator` for use with APIs such as `SSL4ClientEndpoint`, `connectSSL`, and `startTLS`.

Parameters
hostname:`unicode` | The expected name of the remote host. This serves two purposes: first, and most importantly, it verifies that the certificate received from the server correctly identifies the specified hostname. The second purpose is to use the Server Name Indication extension to indicate to the server which certificate should be used.
trustRoot:`IOpenSSLTrustRoot` | Specification of trust requirements of peers. This may be a `Certificate` or the result of `platformTrust`. By default it is `platformTrust` and you probably shouldn't adjust it unless you really know what you're doing. Be aware that clients using this interface must verify the server; you cannot explicitly pass `None` since that just means to use `platformTrust`.
clientCertificate:`PrivateCertificate` | The certificate and private key that the client will use to authenticate to the server. If unspecified, the client will not authenticate.

acceptableProtocols:`list` of `bytes`

The protocols this peer is willing to speak after the TLS negotiation has completed, advertised over both ALPN and NPN. If this argument is specified, and no overlap can be found with the other peer, the connection will fail to be established. If the remote peer does not offer NPN or ALPN, the connection will be established, but no protocol wil be negotiated. Protocols earlier in the list are preferred over those later in the list.

extraCertificateOptions:`dict` | A dictionary of additional keyword arguments to be presented to `CertificateOptions`. Please avoid using this unless you absolutely need to; any time you need to pass an option here that is a bug in this interface.
Returns
`IOpenSSLClientConnectionCreator` | A client connection creator.
Present Since
14.0

def platformTrust(): (source)

Attempt to discover a set of trusted certificate authority certificates (or, in other words: trust roots, or root certificates) whose trust is managed and updated by tools outside of Twisted.

If you are writing any client-side TLS code with Twisted, you should use this as the `trustRoot` argument to `CertificateOptions`.

The result of this function should be like the up-to-date list of certificates in a web browser. When developing code that uses `platformTrust`, you can think of it that way. However, the choice of which certificate authorities to trust is never Twisted's responsibility. Unless you're writing a very unusual application or library, it's not your code's responsibility either. The user may use platform-specific tools for defining which server certificates should be trusted by programs using TLS. The purpose of using this API is to respect that decision as much as possible.

This should be a set of trust settings most appropriate for client TLS connections; i.e. those which need to verify a server's authenticity. You should probably use this by default for any client TLS connection that you create. For servers, however, client certificates are typically not verified; or, if they are, their verification will depend on a custom, application-specific certificate authority.

Returns
`IOpenSSLTrustRoot` | an appropriate trust settings object for your platform.
Raises
`NotImplementedError` | if this platform is not yet supported by Twisted. At present, only OpenSSL is supported.
Present Since
14.0
Note

Currently, `platformTrust` depends entirely upon your OpenSSL build supporting a set of "`default verify paths`" which correspond to certificate authority trust roots. Unfortunately, whether this is true of your system is both outside of Twisted's control and difficult (if not impossible) for Twisted to detect automatically.

Nevertheless, this ought to work as desired by default on:

- Ubuntu Linux machines with the ca-certificates package installed,
- macOS when using the system-installed version of OpenSSL (i.e. not one installed via MacPorts or Homebrew),
- any build of OpenSSL which has had certificate authority certificates installed into its default verify paths (by default, `/usr/local/ssl/certs` if you've built your own OpenSSL), or
- any process where the `SSL_CERT_FILE` environment variable is set to the path of a file containing your desired CA certificates bundle.

Hopefully soon, this API will be updated to use more sophisticated trust-root discovery mechanisms. Until then, you can follow tickets in the Twisted tracker for progress on this implementation on Microsoft Windows, macOS, and a fallback for other platforms which do not have native trust management tools.

def protocolNegotiationMechanisms(): (source)

Checks whether your versions of PyOpenSSL and OpenSSL are recent enough to support protocol negotiation, and if they are, what kind of protocol negotiation is supported.

Returns
`constantly.FlagConstant` | A combination of flags from `ProtocolNegotiationSupport` that indicate which mechanisms for protocol negotiation are supported.

def trustRootFromCertificates(certificates): (source)

Builds an object that trusts multiple root `Certificate`s.

When passed to `optionsForClientTLS`, connections using those options will reject any server certificate not signed by at least one of the certificates in the `certificates` list.

Parameters
certificates:`iterable` of `CertBase` | All certificates which will be trusted.
Returns
`IOpenSSLTrustRoot` | an object suitable for use as the trustRoot= keyword argument to `optionsForClientTLS`
Present Since
16.0

supported: `bool` = (source)

Undocumented

VerificationError = (source)

Undocumented