t.i.s.platformTrust() : function documentation

Part of twisted.internet.ssl View 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.

Returnsan appropriate trust settings object for your platform. (type: IOpenSSLTrustRoot)
RaisesNotImplementedErrorif this platform is not yet supported by Twisted. At present, only OpenSSL is supported.
Present Since14.0
NoteCurrently, 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,
  • Mac OS X 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, Mac OS X, and a fallback for other platforms which do not have native trust management tools.

API Documentation for Twisted, generated by pydoctor at 2015-01-30 14:14:53.