Opened 14 months ago

Last modified 14 months ago

#6800 enhancement new

Expand `CertificateOptions` to include a simple API for specifying what protocols to support

Reported by: exarkun Owned by:
Priority: normal Milestone:
Component: core Keywords: ssl
Cc: hs@… Branch:
Author: Launchpad Bug:

Description (last modified by exarkun)

twisted.internet.ssl.CertificateOptions is used to define the connection parameters for a family of protocols. SSL versions 21 and 3 and TLS versions 1.0, 1.1, and 1.2.

The current API for choosing between these protocols is quite baroque. It's also not very expressive.

  • CertificateOptions(method=SSLv2_METHOD) - this negotiates SSLv2
  • CertificateOptions(method=SSLv3_METHOD) - this negotiates SSLv3
  • CertificateOptions(method=TLSv1_METHOD) - this negotiates TLS v1.0.
  • CertificateOptions(method=SSLv23_METHOD) - this negotiates SSLv2, SSLv3, TLSv1.0, TLSv1.1, or TLSv1.2.
  • CertificateOptions(method=None) (or CertificateOptions()) - this negotiates TLSv1.0, TLSv1.1, or TLSv1.22

Given a sufficiently new version of pyOpenSSL, these are also possible:

  • CertificateOptions(method=TLSv1_1_METHOD) - this negotiates TLSv1.1
  • CertificateOptions(method=TLSv1_2_METHOD) - this negotiates TLSv1.2

Notice that out of 5 protocols there are only 7 possible protocol combinations supported (rather than the complete set of 31 combinations3).

I suggest that CertificateOptions(protocols=[...]) is a better API. The list can specify exactly which protocols to support in any combination. This avoids the need for more symbols than there are protocols (eg SSLv23_METHOD) and makes it extremely obvious what protocols are being selected.

It also steps away from the OpenSSL specific terminology of "methods" and it will force us to step away from the pyOpenSSL supplied method constants since will not longer be useful and not all of them (SSLv23_METHOD) will make sense with this API. These are good things since CertificateOptions is not supposed to be OpenSSL-specific.

1: Of course, SSLv2 is disabled in most real-world OpenSSL builds now so all mentions of SSLv2 in this description are for the sake of completeness. It's most likely not possible to ever negotiate this protocol anymore - nor should it be.

2: Prior to the merge of #6772 it actually negotiates only TLSv1.0.

3: Or 15 if we disregard SSLv2

Change History (4)

comment:1 Changed 14 months ago by exarkun

  • Description modified (diff)

comment:2 Changed 14 months ago by exarkun

  • Description modified (diff)

comment:3 Changed 14 months ago by exarkun

  • Description modified (diff)

comment:4 Changed 14 months ago by hynek

  • Cc hs@… added
Note: See TracTickets for help on using tickets.