Go to the latest version of this document.

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

class documentation

`class CertificateOptions: (source)`

Constructor: `CertificateOptions(privateKey, certificate, method, verify, ...)`

Implements interfaces: `twisted.internet.interfaces.IOpenSSLClientConnectionCreator`, `twisted.internet.interfaces.IOpenSSLContextFactory`, `twisted.internet.interfaces.IOpenSSLServerConnectionCreator`

View In Hierarchy

A `CertificateOptions` specifies the security properties for a client or server TLS connection used with OpenSSL.

Method | `__getstate__` | Undocumented
Method | `__init__` | Create an OpenSSL context SSL connection context factory.
Method | `__setstate__` | Undocumented
Method | `clientConnectionForTLS` | Construct a TLS connection for the client.
Method | `getContext` | Create and cache an `SSL.Context` based on the parameters in this `twisted.internet.ssl.CertificateOptions`.
Method | `serverConnectionForTLS` | Construct a TLS connection for the server.
Instance Variable | `__dict__` | Undocumented
Instance Variable | `caCerts` | Undocumented
Instance Variable | `certificate` | Undocumented
Instance Variable | `dhParameters` | Undocumented
Instance Variable | `enableSessions` | Undocumented
Instance Variable | `enableSessionTickets` | Undocumented
Instance Variable | `enableSingleUseKeys` | Undocumented
Instance Variable | `extraCertChain` | Undocumented
Instance Variable | `fixBrokenPeers` | Undocumented
Instance Variable | `method` | Undocumented
Instance Variable | `privateKey` | Undocumented
Instance Variable | `requireCertificate` | Undocumented
Instance Variable | `trustRoot` | Undocumented
Instance Variable | `verify` | Undocumented
Instance Variable | `verifyDepth` | Undocumented
Instance Variable | `verifyOnce` | Undocumented
Method | `_makeContext` | Make a new context (with no caching) based on the settings of this Options.
Method | `_makeTLSConnection` | Construct an OpenSSL Connection for either client or server.
Class Variable | `_OP_NO_TLSv1_3` | Undocumented
Instance Variable | `_acceptableProtocols` | Undocumented
Instance Variable | `_cipherString` | An OpenSSL-specific cipher string.
Instance Variable | `_context` | Undocumented
Instance Variable | `_contextForServerName` | Undocumented
Instance Variable | `_defaultMinimumTLSVersion` | The default TLS version that will be negotiated. This should be a "safe default", with wide client and server support, vs an optimally secure one that excludes a large number of users. As of May 2022, TLSv1...
Instance Variable | `_ecChooser` | Undocumented
Instance Variable | `_mode` | Undocumented
Instance Variable | `_options` | Any option flags to set on the `OpenSSL.SSL.Context` object that will be created.

def __getstate__(self): (source)

Undocumented

@_mutuallyExclusiveArguments([('trustRoot', 'requireCertificate'), ('trustRoot', 'verify'), ('trustRoot', 'caCerts'), ('method', 'insecurelyLowerMinimumTo'), ('method', 'raiseMinimumTo'), ('raiseMinimumTo', 'insecurelyLowerMinimumTo'), ('method', 'lowerMaximumSecurityTo')])
def __init__(self, privateKey: `PKey | None` = None, certificate: `X509 | None` = None, method: `int | None` = None, verify: `bool` = False, caCerts: `list[X509] | None` = None, verifyDepth: `int` = 9, requireCertificate: `bool` = True, verifyOnce: `bool` = True, enableSingleUseKeys: `bool` = True, enableSessions: `bool` = False, fixBrokenPeers: `bool` = False, enableSessionTickets: `bool` = False, extraCertChain: `list[X509] | None` = None, acceptableCiphers: `IAcceptableCiphers | None` = None, dhParameters: `OpenSSLDiffieHellmanParameters | None` = None, trustRoot: `IOpenSSLTrustRoot | None` = None, acceptableProtocols: `list[bytes] | None` = None, raiseMinimumTo: `NamedConstant | None` = None, insecurelyLowerMinimumTo: `NamedConstant | None` = None, lowerMaximumSecurityTo: `NamedConstant | None` = None, contextForServerName: `Callable[[(bytes | None)], SSL.Context | None] | None` = None): (source)

Create an OpenSSL context SSL connection context factory.

Parameters
privateKey:`PKey | None` | A PKey object holding the private key.
certificate:`X509 | None` | An X509 object holding the certificate.

method:`int | None`

Deprecated, use a combination of `insecurelyLowerMinimumTo`, `raiseMinimumTo`, or `lowerMaximumSecurityTo` instead. The SSL protocol to use, one of `TLS_METHOD`, `TLSv1_2_METHOD`, or `TLSv1_2_METHOD` (or any future method constants provided by pyOpenSSL). By default, a setting will be used which allows TLSv1.2 and TLSv1.3. Can not be used with `insecurelyLowerMinimumTo`, `raiseMinimumTo`, or `lowerMaximumSecurityTo`.

verify:`bool` | Please use a `trustRoot` keyword argument instead, since it provides the same functionality in a less error-prone way. By default this is `False`. If `True`, verify certificates received from the peer and fail the handshake if verification fails. Otherwise, allow anonymous sessions and sessions with certificates which fail validation.
caCerts:`list` of `OpenSSL.crypto.X509` | Please use a `trustRoot` keyword argument instead, since it provides the same functionality in a less error-prone way. List of certificate authority certificate objects to use to verify the peer's certificate. Only used if verify is `True` and will be ignored otherwise. Since verify is `False` by default, this is `None` by default.
verifyDepth:`int` | Depth in certificate chain down to which to verify. If unspecified, use the underlying default (9).
requireCertificate:`bool` | Please use a `trustRoot` keyword argument instead, since it provides the same functionality in a less error-prone way. If `True`, do not allow anonymous sessions; defaults to `True`.
verifyOnce:`bool` | If True, do not re-verify the certificate on session resumption.
enableSingleUseKeys:`bool` | If `True`, generate a new key whenever ephemeral DH and ECDH parameters are used to prevent small subgroup attacks and to ensure perfect forward secrecy.
enableSessions:`bool` | This allows a shortened handshake to be used when a known client reconnects to the same process. If True, enable OpenSSL's session caching. Note that session caching only works on a single Twisted node at once. Also, it is currently somewhat risky due to a crashing bug when using OpenSSL 1.1.1.
fixBrokenPeers:`bool` | If True, enable various non-spec protocol fixes for broken SSL implementations. This should be entirely safe, according to the OpenSSL documentation, but YMMV. This option is now off by default, because it causes problems with connections between peers using OpenSSL 0.9.8a.
enableSessionTickets:`bool` | If `True`, enable session ticket extension for session resumption per RFC 5077. Note there is no support for controlling session tickets. This option is off by default, as some server implementations don't correctly process incoming empty session ticket extensions in the hello.
extraCertChain:`list[X509] | None` | List of certificates that complete your verification chain if the certificate authority that signed your `certificate` isn't widely supported. Do not add `certificate` to it.
acceptableCiphers:`IAcceptableCiphers` | Ciphers that are acceptable for connections. Uses a secure default if left `None`.
dhParameters:`OpenSSLDiffieHellmanParameters | None` | Key generation parameters that are required for Diffie-Hellman key exchange. If this argument is left `None`, `EDH` ciphers are disabled regardless of `acceptableCiphers`.

trustRoot:`IOpenSSLTrustRoot | None`

Specification of trust requirements of peers. If this argument is specified, the peer is verified. It requires a certificate, and that certificate must be signed by one of the certificate authorities specified by this object.

Note that since this option specifies the same information as `caCerts`, `verify`, and `requireCertificate`, specifying any of those options in combination with this one will raise a `TypeError`.

acceptableProtocols:`list` of `bytes`

The protocols this peer is willing to speak after the TLS negotiation has completed, advertised over ALPN. 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 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.

raiseMinimumTo:`TLSVersion` constant | The minimum TLS version that you want to use, or Twisted's default if it is higher. Use this if you want to make your client/server more secure than Twisted's default, but will accept Twisted's default instead if it moves higher than this value. You probably want to use this over `insecurelyLowerMinimumTo`.
insecurelyLowerMinimumTo:`TLSVersion` constant | The minimum TLS version to use, possibly lower than Twisted's default. If not specified, it is a generally considered safe default (TLSv1.0). If you want to raise your minimum TLS version to above that of this default, use `raiseMinimumTo`. DO NOT use this argument unless you are absolutely sure this is what you want.
lowerMaximumSecurityTo:`TLSVersion` constant | The maximum TLS version to use. If not specified, it is the most recent your OpenSSL supports. You only want to set this if the peer that you are communicating with has problems with more recent TLS versions, it lowers your security when communicating with newer peers. DO NOT use this argument unless you are absolutely sure this is what you want.
contextForServerName:`Callable[[(bytes | None)], SSL.Context | None] | None` | A callback to invoke with the server-name indication field in the client handshake, which returns the other context to switch to.

Raises
`ValueError` | when `privateKey` or `certificate` are set without setting the respective other.
`ValueError` | when `verify` is `True` but `caCerts` doesn't specify any CA certificates.
`ValueError` | when `extraCertChain` is passed without specifying `privateKey` or `certificate`.
`ValueError` | when `acceptableCiphers` doesn't yield any usable ciphers for the current platform.
`TypeError` | if `trustRoot` is passed in combination with `caCert`, `verify`, or `requireCertificate`. Please prefer `trustRoot` in new code, as its semantics are less tricky.
`TypeError` | if `method` is passed in combination with `tlsProtocols`. Please prefer the more explicit `tlsProtocols` in new code.
`NotImplementedError` | If acceptableProtocols were provided but no negotiation mechanism is available.

def __setstate__(self, state): (source)

Undocumented

def clientConnectionForTLS(self, protocol: `TLSMemoryBIOProtocol`) -> `SSL.Connection`: (source)
from `twisted.internet.interfaces.IOpenSSLClientConnectionCreator`

Construct a TLS connection for the client.

def getContext(self) -> `SSL.Context`: (source)
from `twisted.internet.interfaces.IOpenSSLContextFactory`

Create and cache an `SSL.Context` based on the parameters in this `twisted.internet.ssl.CertificateOptions`.

This is deprecated because it returns a cached, shared context which cannot safely be shared, because the acceptable protocols may be mutated.

def serverConnectionForTLS(self, protocol: `TLSMemoryBIOProtocol`) -> `SSL.Connection`: (source)
from `twisted.internet.interfaces.IOpenSSLServerConnectionCreator`

Construct a TLS connection for the server.

__dict__ = (source)

Undocumented

caCerts = (source)

Undocumented

certificate = (source)

Undocumented

dhParameters = (source)

Undocumented

enableSessions = (source)

Undocumented

enableSessionTickets = (source)

Undocumented

enableSingleUseKeys = (source)

Undocumented

extraCertChain = (source)

Undocumented

fixBrokenPeers = (source)

Undocumented

method = (source)

Undocumented

privateKey = (source)

Undocumented

requireCertificate = (source)

Undocumented

trustRoot: `IOpenSSLTrustRoot | None` = (source)

Undocumented

verify = (source)

Undocumented

verifyDepth = (source)

Undocumented

verifyOnce = (source)

Undocumented

def _makeContext(self, skipCiphers: `bool` = False) -> `SSL.Context`: (source)

Make a new context (with no caching) based on the settings of this Options.

Parameters
skipCiphers:`bool` | Don't set the cipher list, so as to avoid creating a Connection and preventing further mutation. Just for a few small tests, per the behavior described here.

Returns
`SSL.Context` | Undocumented

def _makeTLSConnection(self, protocol: `TLSMemoryBIOProtocol`) -> `SSL.Connection`: (source)

Construct an OpenSSL Connection for either client or server.

_OP_NO_TLSv1_3 = (source)

Undocumented

_acceptableProtocols = (source)

Undocumented

_cipherString: `unicode` = (source)

An OpenSSL-specific cipher string.

_context: `SSL.Context | None` = (source)

Undocumented

_contextForServerName = (source)

Undocumented

_defaultMinimumTLSVersion: `TLSVersion` constant = (source)

The default TLS version that will be negotiated. This should be a "safe default", with wide client and server support, vs an optimally secure one that excludes a large number of users. As of May 2022, TLSv1.2 is that safe default.

_ecChooser = (source)

Undocumented

_mode = (source)

Undocumented

_options: `int` = (source)

Any option flags to set on the `OpenSSL.SSL.Context` object that will be created.