Configuration

class siotls.configuration.TLSConfiguration

The TLSConfiguration class provides a comprehensive set of options to configure the security parameters for TLS connections, applicable to both clients and servers.

It allows control over the cryptographic elements involved in the TLS handshake, including the selection of ciphers, key exchange methods, and signature algorithms. It also allows control over various TLS extensions such as Server Name Indication (SNI), Application-Layer Protocol Negotiation (ALPN) and others.

Client On the client-side, the truststore parameter is recommended. It is used to authenticate the remote server. Leaving the parameter out makes the connection insecure. See the siotls.trust module for available trust backends.

>>> minimal_client_config = TLSConfiguration(
>>>     'client',
>>>     truststore=siotls.trust.get_truststore(),
>>> )

Server On the server-side, the private_key and certificate_chain parameters are mandatory.

>>> minimal_server_config = TLSConfiguration(
>>>     'server',
>>>     private_key=...,
>>>     certificate_chain=...,
>>> )

Mutual TLS Server authentication is mandatory by TLS. Client authentication (mutual TLS) is optional. Set the truststore server-side to request client authentication. Set the private_key and certificate_chain pair client-side to comply.

Raw Public Keys The truststore and certificate_chain parameters are used for certificate authentication. It is possible to authenticate using raw public keys in addition to / instead of certificates. Use public_key server-side and trusted_public_keys client-side. Set the other parameter on the other side for mutual TLS using raw public keys.

__init__(
side,
*,
cipher_suites=(<CipherSuites.TLS_CHACHA20_POLY1305_SHA256: 4867 (0x1303)>,
<CipherSuites.TLS_AES_256_GCM_SHA384: 4866 (0x1302)>,
<CipherSuites.TLS_AES_128_GCM_SHA256: 4865 (0x1301)>),
key_exchanges=(<NamedGroup.x25519: 29 (0x001d)>,
<NamedGroup.secp256r1: 23 (0x0017)>),
signature_algorithms=(<SignatureScheme.ed25519: 2055 (0x0807)>,
<SignatureScheme.ecdsa_secp256r1_sha256: 1027 (0x0403)>,
<SignatureScheme.ecdsa_secp384r1_sha384: 1283 (0x0503)>,
<SignatureScheme.ecdsa_secp521r1_sha512: 1539 (0x0603)>,
<SignatureScheme.rsa_pss_rsae_sha256: 2052 (0x0804)>,
<SignatureScheme.rsa_pss_rsae_sha384: 2053 (0x0805)>,
<SignatureScheme.rsa_pss_rsae_sha512: 2054 (0x0806)>),
truststore=None,
trusted_public_keys=(),
private_key=None,
private_key_signature_algorithms=(<SignatureScheme.ecdsa_secp256r1_sha256: 1027 (0x0403)>,
<SignatureScheme.ecdsa_secp384r1_sha384: 1283 (0x0503)>,
<SignatureScheme.ecdsa_secp521r1_sha512: 1539 (0x0603)>,
<SignatureScheme.ed25519: 2055 (0x0807)>,
<SignatureScheme.ed448: 2056 (0x0808)>,
<SignatureScheme.rsa_pss_pss_sha256: 2057 (0x0809)>,
<SignatureScheme.rsa_pss_pss_sha384: 2058 (0x080a)>,
<SignatureScheme.rsa_pss_pss_sha512: 2059 (0x080b)>,
<SignatureScheme.rsa_pss_rsae_sha256: 2052 (0x0804)>,
<SignatureScheme.rsa_pss_rsae_sha384: 2053 (0x0805)>,
<SignatureScheme.rsa_pss_rsae_sha512: 2054 (0x0806)>),
public_key=None,
certificate_chain=(),
max_fragment_length=MaxFragmentLengthOctets.MAX_16384,
alpn=(),
log_keys=False,
)
Parameters:
Return type:

None

alpn: Sequence[ALPNProtocol | bytes] = ()

Negociate RFC 7301# (Application-Layer Protocol Negociation/ALPN).

List the protocols that this application is willing to use once the connection is secured.

The list should be ordered server-side in decreasing preference order, i.e. the prefered protocol should be first in the list.

The negotiated protocol is available at TLSNegotiatedConfiguration.alpn.

property asn1_certificate_chain: Sequence[Certificate]

The certificate_chain loaded as a list of asn1crypto objects, the list is empty when there are no certificates.

property asn1_private_key: PrivateKeyInfo

The private_key loaded as a asn1crypto object, or None if there is not private key.

property asn1_public_key: PublicKeyInfo

The public key loaded from public_key or certificate_chain as a asn1crypto object, or None if neither attribute is set.

property asn1_trusted_public_keys: Collection[PublicKeyInfo]

The trusted_public_keys loaded as a list of asn1crypto objects, the list is empty when there are no trusted public keys.

certificate_chain: Sequence[DerCertificate] = ()

The list of certificates that together form a chain of trust between the host certificate and a trusted root certificate. Make this side authenticate using x509 certificates.

The first certificate in the list must be the certificate of the current host. The following certificates each should sign the one preceding. The last certificate should be signed by a trusted root certificate, or be a trusted root certificate directly.

property certificate_types: Sequence[CertificateType]

The certificate types this side of the connection can offer:

cipher_suites: Sequence[CipherSuites] = (<CipherSuites.TLS_CHACHA20_POLY1305_SHA256: 4867 (0x1303)>, <CipherSuites.TLS_AES_256_GCM_SHA384: 4866 (0x1302)>, <CipherSuites.TLS_AES_128_GCM_SHA256: 4865 (0x1301)>)

List the cipher suites that can be used to encrypt data transmitted on the wire.

If the peers cannot agree on a same cipher suite, the connection fails with a siotls.alerts.HandshakeFailure fatal alert.

The list should be ordered server-side in decreasing preference order, i.e. the prefered cipher should be first in the list. The order doesn’t matter client-side.

The default list follows the recommendations of Cryptographic Right Answers (Latacora 2018). It is further stripped down to only include the algorithms supported by the crypto backend.

The negotiated cipher is available at TLSNegotiatedConfiguration.cipher_suite.

key_exchanges: Sequence[NamedGroup] = (<NamedGroup.x25519: 29 (0x001d)>, <NamedGroup.secp256r1: 23 (0x0017)>)

List the allowed key exchange algorithms that can be used to share a secret and bootstrap encryption.

If the peers cannot agree on a same key exchange algorithm, the connection fails with a siotls.alerts.HandshakeFailure fatal alert.

The list should be ordered server-side in decreasing preference order, i.e. the prefered algorithm should be first in the list. The order doesn’t matter client-side.

The default list follows the recommendations of Cryptographic Right Answers (Latacora 2018), with the addition of P-256 because of its widespread usage. The default list is further stripped down to only include the algorithms supported by the crypto backend.

The negotiated algorithm is available at TLSConnection.nconfig.key_exchange.

log_keys: bool = False

Enable key logging for netword analysis tools such as wireshark.

Setting this value True is not enough to enable key logging, the siotls.keylog logger must be configured too.

max_fragment_length: MaxFragmentLengthOctets = 16384

Negociate RFC 6066 Section 4 (Maximum Fragment Length)

Limit the length of data encapsuled by TLS, fragmenting the data over multiple records when necessary. The limit only accounts for the fragment length and does not account for the additional 5 bytes record header.

This doesn’t limit the size of the internal buffers used by siotls which can grow up to 24 MiB during handshake after defragmentation.

The negotiated length is available at TLSNegotiatedConfiguration.max_fragment_length.

property other_side: 'client' | 'server'

The side of the peer.

property peer_certificate_types: Sequence[CertificateType]

The certificate types this side of the connection can process if offered by the peer:

private_key: DerPrivateKey | None = None

The private key counter part of public_key and the public key found inside the first certificate_chain. Mandatory server side, optional client-side (but a server might require for mutual TLS).

private_key_signature_algorithms: Collection[SignatureScheme] = (<SignatureScheme.ecdsa_secp256r1_sha256: 1027 (0x0403)>, <SignatureScheme.ecdsa_secp384r1_sha384: 1283 (0x0503)>, <SignatureScheme.ecdsa_secp521r1_sha512: 1539 (0x0603)>, <SignatureScheme.ed25519: 2055 (0x0807)>, <SignatureScheme.ed448: 2056 (0x0808)>, <SignatureScheme.rsa_pss_pss_sha256: 2057 (0x0809)>, <SignatureScheme.rsa_pss_pss_sha384: 2058 (0x080a)>, <SignatureScheme.rsa_pss_pss_sha512: 2059 (0x080b)>, <SignatureScheme.rsa_pss_rsae_sha256: 2052 (0x0804)>, <SignatureScheme.rsa_pss_rsae_sha384: 2053 (0x0805)>, <SignatureScheme.rsa_pss_rsae_sha512: 2054 (0x0806)>)

List the signature algorithms the private_key can be used with.

This list exists solely for RSA, so it is possible to configure what signature scheme to use with a “rsaEncryption” key: PKCS1 (legacy) and/or PSS (modern).

The default list allows for all algorithms supported by TLS 1.3 except for rsa_pkcs1_sha256, rsa_pkcs1_sha384 and rsa_pkcs1_sha512 which are rejected by OpenSSL.

public_key: DerPublicKey | None = None

Negotiate RFC 7250# (Raw Public Keys).

The public key counter part of private_key. Allow this side to authenticate using raw public keys.

When used in addition to certificate_chain, it will send either the certificate chain, either the public key, depending on the peer’s negotiated preference. When used instead of certificate_chain, it will either send the public key, either fail with an UnsupportedCertificate error, depending on the peer’s support for raw public keys.

property require_peer_authentication: bool

Whether to verify the peer’s authenticity, via a certificate and/or a raw public key. Determined on both truststore and trusted_public_keys.

Client-side this property dictates if we should process or ignore the certificate or raw public key sent by the server.

Server-side this property dictates if the server will request and process a client certificate or raw public key.

side: 'client' | 'server'

Tell whether this configuration will be used for client connections or server ones.

signature_algorithms: Collection[SignatureScheme] = (<SignatureScheme.ed25519: 2055 (0x0807)>, <SignatureScheme.ecdsa_secp256r1_sha256: 1027 (0x0403)>, <SignatureScheme.ecdsa_secp384r1_sha384: 1283 (0x0503)>, <SignatureScheme.ecdsa_secp521r1_sha512: 1539 (0x0603)>, <SignatureScheme.rsa_pss_rsae_sha256: 2052 (0x0804)>, <SignatureScheme.rsa_pss_rsae_sha384: 2053 (0x0805)>, <SignatureScheme.rsa_pss_rsae_sha512: 2054 (0x0806)>)

List the signature algorithms the peer is allowed to use to authenticate itself. Mandatory client side, as the server always authenticates itself. Optional server side, required only for mutual TLS.

The default list follows the recommendation of Cryptographic Right Answers (Latacora 2018), with the addition of the algorithms allowed by the TLS Baseline Requirements (CA/Browser Forum 2.1.5). The default list is further stripped down to only include the algorithms supported by the crypto backend.

The negotiated algorithm are available at TLSConnection.nconfig.peer_signature_algorithm and TLSConnection.nconfig.signature_algorithm.

trusted_public_keys: Collection[DerPublicKey] = ()

Negotiate RFC 7250# (Raw Public Keys).

Make peer authentication mandatory. Allow the peer to authenticate using raw public keys.

When used in addition to truststore, it allows the peer to authenticate with either x509 (preferred) or raw public keys. When used instead of truststore, it only allows raw public keys and will reject x509 certificates with an UnsupportedCertificate error.

truststore: TrustStore | None = None

Make peer authentication mandatory. Allow the peer to authenticate using x509 certificates.

The service used to verify a x509 certificate chain. See the siotls.trust module for more details.

class siotls.configuration.TLSNegotiatedConfiguration

The values agreed by both peers on a specific connection. Available at siotls.connection.TLSConnection.nconfig.

alpn: ALPNProtocol | None
can_echo_heartbeat: bool
can_send_heartbeat: bool
cipher_suite: CipherSuites
client_certificate_type: CertificateType
key_exchange: NamedGroup
max_fragment_length: MLFOctets
peer_certificate: Certificate
peer_public_key: PublicKeyTypes
peer_signature_algorithm: SignatureScheme | None
peer_want_ocsp_stapling: bool
server_certificate_type: CertificateType
signature_algorithm: SignatureScheme | None