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:
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
instance; see its documentation for an explanation of the available
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
contextFactory) is both difficult and dangerous; the
Twisted team has worked hard to make
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
connection creator and
connection creator interfaces.
Developers using Twisted, please ignore the
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||ContextFactory||A factory for SSL context objects, for server SSL connections.|
|Class||ClientContextFactory||A context factory for SSL clients.|
|Class||Client||I am an SSL client.|
|Class||Server||I am an SSL server.|
|Class||Port||I am an SSL port.|
|Class||KeyPair||No class docstring; 0/2 class methods, 3/10 methods documented|
|Class||DistinguishedName||Identify and describe an entity.|
|Class||Certificate||An x509 certificate.|
|Class||CertificateRequest||An x509 certificate request.|
|Class||PrivateCertificate||An x509 certificate and private key.|
|Class||AcceptableCiphers||A representation of ciphers that are acceptable for TLS connections.|
|Class||DiffieHellmanParameters||A representation of key generation parameters that are required for Diffie-Hellman key exchange.|
|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.|
|Class||OpenSSLDefaultPaths||Trust the set of default verify paths that OpenSSL was built with, as specified by SSL_CTX_set_default_verify_paths.|
|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
|Class||TLSVersion||TLS versions that we can negotiate with the client/server.|
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
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||an appropriate trust settings object for your platform. (type: |
|Raises||NotImplementedError||if this platform is not yet supported by Twisted. At present, only OpenSSL is supported.|
Nevertheless, this ought to work as desired by default on:
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, Mac OS X, and a fallback for other platforms which do not have native trust management tools.
|Parameters||hostname||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. (type: |
|trustRoot||Specification of trust requirements of peers. This may be a |
|clientCertificate||The certificate and private key that the client will use to authenticate to
the server. If unspecified, the client will not authenticate. (type: |
|acceptableProtocols||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. (type: |
|extraCertificateOptions||keyword-only argument; this is a dictionary of additional keyword arguments
to be presented to |
|kw||(Backwards compatibility hack to allow keyword-only arguments on Python 2.
Please ignore; arbitrary keyword arguments will be errors.) (type: |
|Returns||A client connection creator. (type: |
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||A combination of flags from |
Builds an object that trusts multiple root
When passed to
connections using those options will reject any server certificate not
signed by at least one of the certificates in the `certificates` list.
|Parameters||certificates||All certificates which will be trusted. (type: |
|Returns||an object suitable for use as the trustRoot= keyword argument to |