tlslite.handshakesettings module

Class for setting handshake parameters.

class tlslite.handshakesettings.HandshakeSettings

Bases: object

This class encapsulates various parameters that can be used with a TLS handshake.

Variables:

• minKeySize (int) –

  The minimum bit length for asymmetric keys.

  If the other party tries to use SRP, RSA, DSA, or Diffie-Hellman parameters smaller than this length, an alert will be signalled. The default is 1023.

• maxKeySize (int) –

  The maximum bit length for asymmetric keys.

  If the other party tries to use SRP, RSA, DSA, or Diffie-Hellman parameters larger than this length, an alert will be signalled. The default is 8193.

• cipherNames (list(str)) –

  The allowed ciphers.

  The allowed values in this list are ‘chacha20-poly1305’, ‘aes256gcm’, ‘aes128gcm’, ‘aes256’, ‘aes128’, ‘3des’, ‘chacha20-poly1305_draft00’, ‘null’ and ‘rc4’. If these settings are used with a client handshake, they determine the order of the ciphersuites offered in the ClientHello message.

  If these settings are used with a server handshake, the server will choose whichever ciphersuite matches the earliest entry in this list.

  The default value is list that excludes ‘rc4’, ‘null’ and ‘chacha20-poly1305_draft00’.

• macNames (list(str)) –

  The allowed MAC algorithms.

  The allowed values in this list are ‘sha384’, ‘sha256’, ‘aead’, ‘sha’ and ‘md5’.

  The default value is list that excludes ‘md5’.

• certificateTypes (list(str)) –

  The allowed certificate types.

  The only allowed certificate type is ‘x509’. This list is only used with a client handshake. The client will advertise to the server which certificate types are supported, and will check that the server uses one of the appropriate types.

• minVersion (tuple) –

  The minimum allowed SSL/TLS version.

  This variable can be set to (3, 0) for SSL 3.0, (3, 1) for TLS 1.0, (3, 2) for TLS 1.1, or (3, 3) for TLS 1.2. If the other party wishes to use a lower version, a protocol_version alert will be signalled. The default is (3, 1).

• maxVersion (tuple) –

  The maximum allowed SSL/TLS version.

  This variable can be set to (3, 0) for SSL 3.0, (3, 1) for TLS 1.0, (3, 2) for TLS 1.1, or (3, 3) for TLS 1.2. If the other party wishes to use a higher version, a protocol_version alert will be signalled. The default is (3, 3).

  Warning

  Some servers may (improperly) reject clients which offer support for TLS 1.1 or higher. In this case, try lowering maxVersion to (3, 1).

• useExperimentalTackExtension (bool) –

  Whether to enabled TACK support.

  Note that TACK support is not standardized by IETF and uses a temporary TLS Extension number, so should NOT be used in production software.

• sendFallbackSCSV (bool) – Whether to, as a client, send FALLBACK_SCSV.

• rsaSigHashes (list(str)) –

  List of hashes supported (and advertised as such) for TLS 1.2 signatures over Server Key Exchange or Certificate Verify with RSA signature algorithm.

  The list is sorted from most wanted to least wanted algorithm.

  The allowed hashes are: “md5”, “sha1”, “sha224”, “sha256”, “sha384” and “sha512”. The default list does not include md5.

• dsaSigHashes (list(str)) –

  List of hashes supported (and advertised as such) for TLS 1.2 signatures over Server Key Exchange or Certificate Verify with DSA signature algorithm.

  The list is sorted from most wanted to least wanted algorithm.

  The allowed hashes are: “sha1”, “sha224”, “sha256”, “sha384” and “sha512”.

• ecdsaSigHashes (list(str)) –

  List of hashes supported (and advertised as such) for TLS 1.2 signatures over Server Key Exchange or Certificate Verify with ECDSA signature algorithm.

  The list is sorted from most wanted to least wanted algorithm.

  The allowed hashes are: “sha1”, “sha224”, “sha256”, “sha384” and “sha512”.

“vartype more_sig_schemes: list(str) :ivar more_sig_schemes: List of additional signatures schemes (ones

that don’t use RSA-PKCS#1 v1.5, RSA-PSS, DSA, or ECDSA) to advertise as supported. Currently supported are: “Ed25519”, and “Ed448”.

Variables:

• eccCurves (list(str)) – List of named curves that are to be advertised as supported in supported_groups extension.

• useEncryptThenMAC (bool) – whether to support the encrypt then MAC extension from RFC 7366. True by default.

• useExtendedMasterSecret (bool) – whether to support the extended master secret calculation from RFC 7627. True by default.

• requireExtendedMasterSecret (bool) – whether to require negotiation of extended master secret calculation for successful connection. Requires useExtendedMasterSecret to be set to true. False by default.

• defaultCurve (str) – curve that will be used by server in case the client did not advertise support for any curves. It does not have to be the first curve for eccCurves and may be distinct from curves from that list.

• keyShares (list(str)) – list of TLS 1.3 key shares to include in Client Hello

• padding_cb (func) – Callback to function computing number of padding bytes for TLS 1.3. Signature is cb_func(msg_size, content_type, max_size).

• pskConfigs (list(tuple(bytearray, bytearray, bytearray))) – list of tuples, first element of the tuple is the human readable, UTF-8 encoded, “identity” of the associated secret (bytearray, can be empty for TLS 1.2 and earlier), second element is the binary secret (bytearray), third is an optional parameter specifying the PRF hash to be used in TLS 1.3 (sha256 or sha384, with sha256 being the default)

• ticketKeys (list(bytearray)) – keys to be used for encrypting and decrypting session tickets. First entry is the encryption key for new tickets and the default decryption key, subsequent entries are the fallback keys allowing for key rollover. The keys need to be of size appropriate for a selected cipher in ticketCipher, 32 bytes for ‘aes256gcm’ and ‘chacha20-poly1305’, 16 bytes for ‘aes128-gcm’. New keys should be generated regularly and replace old ones. Key use time should generally not be longer than 24h and key life-time should not be longer than 48h. Leave empty to disable session ticket support on server side.

• ticketCipher (str) – name of the cipher used for encrypting the session tickets. ‘aes256gcm’ by default, ‘aes128gcm’ or ‘chacha20-poly1305’ alternatively.

• ticketLifetime (int) – maximum allowed lifetime of ticket encryption key, in seconds. 1 day by default

• ticket_count (int) – number of tickets the server will send to the client after establishing the connection in TLS 1.3. If a positive integer, it enabled support for ticket based resumption in TLS 1.2 and earlier.

• psk_modes (list(str)) – acceptable modes for the PSK key exchange in TLS 1.3

• max_early_data (int) – maximum number of bytes acceptable for 0-RTT early_data processing. In other words, how many bytes will the server try to process, but ignore, in case the Client Hello includes early_data extension.

• use_heartbeat_extension (bool) – whether to support heartbeat extension from RFC 6520. True by default.

• heartbeat_response_callback (func) – Callback to function when Heartbeat response is received.

• ~.record_size_limit (int) – maximum size of records we are willing to process (value advertised to the other side). It must not be larger than 2**14+1 (the maximum for TLS 1.3) and will be reduced to 2**14 if TLS 1.2 or lower is the highest enabled version. Must not be set to values smaller than 64. Set to None to disable support for the extension. See also: RFC 8449.

• keyExchangeNames (list) – Enabled key exchange types for the connection, influences selected cipher suites.

__init__()

Initialise default values for settings.

getCertificateTypes()

Get list of certificate types as IDs

validate()

Validate the settings, filter out unsupported ciphersuites and return a copy of object. Does not modify the original object.

Return type:

HandshakeSettings

Returns:

a self-consistent copy of settings

Raises:

ValueError – when settings are invalid, insecure or unsupported.

class tlslite.handshakesettings.Keypair(key=None, certificates=())

Bases: object

Key, certificate and related data.

Stores also certificate associate data like OCSPs and transparency info. TODO: add the above

First certificate in certificates needs to match key, remaining should build a trust path to a root CA.

Variables:

• key (RSAKey or ECDSAKey) – private key

• certificates (list(X509)) – the certificates to send to peer if the key is selected for use. The first one MUST include the public key of the key

__init__(key=None, certificates=())

validate()

Sanity check the keypair.

class tlslite.handshakesettings.VirtualHost

Bases: object

Configuration of keys and certs for a single virual server.

This class encapsulates keys and certificates for hosts specified by server_name (SNI) and ALPN extensions.

TODO: support SRP as alternative to certificates TODO: support PSK as alternative to certificates

Variables:

• keys (list(Keypair)) – List of certificates and keys to be used in this virtual host. First keypair able to server ClientHello will be used.

• hostnames (set(bytes)) – all the hostnames that server supports please use matches_hostname() to verify if the VirtualHost can serve a request to a given hostname as that allows wildcard hosts that always reply True.

• trust_anchors (list(X509)) – list of CA certificates supported for client certificate authentication, sent in CertificateRequest

• app_protocols (list(bytes)) – all the application protocols that the server supports (for ALPN)

__init__()

Set up default configuration.

matches_hostname(hostname)

Checks if the virtual host can serve hostname

validate()

Sanity check the settings