TransportSecurity

class c104.TransportSecurity

This class is responsible for configuring transport layer security (TLS) for both servers and clients. Once an instance is assigned to a client or server, it becomes read-only and cannot be modified further.

__init__(self: c104.TransportSecurity, validate: bool = True, only_known: bool = True) → None

Create a new transport layer configuration

Parameters:

  • validate (bool) – validate certificates of communication partners (chain and time)

  • only_known (bool) – accept communication only from partners with certificate added to the list of allowed remote certificates

Example

>>> tls = c104.TransportSecurity(validate=True, only_known=False)
add_allowed_remote_certificate(self: c104.TransportSecurity, cert: str) → None

add a trusted communication partners x509 certificate from file

Parameters:

cert (str) – path to trusted communication partners certificate file

Return type:

None

Raises:

  • ValueError – config is readonly and cannot be modified further

  • ValueError – failed to load the certificate file

Example

>>> tls = c104.TransportSecurity(validate=True, only_known=False)
>>> tls.add_allowed_remote_certificate(cert="certs/client2.crt")
set_ca_certificate(self: c104.TransportSecurity, cert: str) → None

load x509 certificate of trusted authority from file

Parameters:

cert (str) – path to certificate authorities certificate file

Return type:

None

Raises:

  • ValueError – config is readonly and cannot be modified further

  • ValueError – failed to load the certificate file

Example

>>> tls = c104.TransportSecurity(validate=True, only_known=False)
>>> tls.set_ca_certificate(cert="certs/ca.crt")
set_certificate(self: c104.TransportSecurity, cert: str, key: str, passphrase: str = '') → None

load x509 certificate from file with (optional encrypted) key from file used to encrypt the connection

Parameters:

  • cert (str) – path to certificate file

  • key (bool) – path to certificates private key file

  • passphrase (str) – password required to decrypt the certificates private key file

Return type:

None

Raises:

  • ValueError – config is readonly and cannot be modified further

  • ValueError – failed to load the certificate file, the private key file or failed decrypting the private key

Example

>>> tls = c104.TransportSecurity(validate=True, only_known=False)
>>> tls.set_certificate(cert="certs/server.crt", key="certs/server.key")
set_ciphers(self: c104.TransportSecurity, ciphers: list[c104.TlsCipher]) → None

set the list of accepted TLS cipher suites

When configuring minimum and maximum TLS versions together with cipher suites, it’s crucial to ensure that the selected cipher suites are compatible with the specified TLS versions.

Parameters:

ciphers (list[c104.TlsCipher]) – accepted TLS cipher suites

Return type:

None

Raises:

  • ValueError – config is readonly and cannot be modified further

  • ValueError – list is empty or contains invalid cipher suites

Example

>>> tls = c104.TransportSecurity(validate=True, only_known=False)
>>> tls.set_ciphers(ciphers=[
>>>   c104.TlsCipher.ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,
>>>   c104.TlsCipher.ECDHE_RSA_WITH_AES_128_GCM_SHA256,
>>>   c104.TlsCipher.ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,
>>>   c104.TlsCipher.ECDHE_RSA_WITH_AES_256_GCM_SHA384,
>>>   c104.TlsCipher.ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256,
>>>   c104.TlsCipher.ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256,
>>>   c104.TlsCipher.DHE_RSA_WITH_AES_128_GCM_SHA256,
>>>   c104.TlsCipher.DHE_RSA_WITH_AES_256_GCM_SHA384,
>>>   c104.TlsCipher.DHE_RSA_WITH_CHACHA20_POLY1305_SHA256,
>>>   c104.TlsCipher.TLS1_3_AES_128_GCM_SHA256,
>>>   c104.TlsCipher.TLS1_3_AES_256_GCM_SHA384,
>>>   c104.TlsCipher.TLS1_3_CHACHA20_POLY1305_SHA256
>>> ])
set_hostname_verification(self: c104.TransportSecurity, hostname: str | None = None) → None

set up hostname verification

Configure a hostname to verify the peers certificate by validating the CN or SAN records (with wildcard support).

Parameters:

hostname (str, optional) – The hostname that belongs to the peers certificate. If None, verification is disabled.

Return type:

None

Raises:

  • ValueError – config is readonly and cannot be modified further

  • ValueError – empty string provided, use None to disable hostname validation

Example

>>> tls = c104.TransportSecurity(validate=True, only_known=False)
>>> tls.set_hostname_verification(hostname="example.com")
set_renegotiation_time(self: c104.TransportSecurity, interval: datetime.timedelta | None = None) → None

sets the renegotiation interval

This defines how often the TLS connection should renegotiate. If no interval is specified (None), it disables automatic renegotiation. Per default renegotiation is disabled.

Parameters:

interval (datetime.timedelta, optional) – The interval as a datetime.timedelta object. If None, renegotiation is disabled.

Return type:

None

Raises:

  • ValueError – config is readonly and cannot be modified further

  • ValueError – value too small or too large

Example

>>> tls = c104.TransportSecurity(validate=True, only_known=False)
>>> tls.set_renegotiation_time(interval=datetime.timedelta(minutes=30))
set_resumption_interval(self: c104.TransportSecurity, interval: datetime.timedelta | None = None) → None

sets the session resumption interval for the TLS configuration.

This interval determines the frequency at which session resumption can occur, allowing faster reconnections. If no interval is specified (None), session resumption will be disabled. Per default session resumption is set to 6 hours.

Parameters:

interval (datetime.timedelta, optional) – The interval as a datetime.timedelta object. If None, session resumption is disabled.

Return type:

None

Raises:

  • ValueError – config is readonly and cannot be modified further

  • ValueError – value too small or too large

Example

>>> tls = c104.TransportSecurity(validate=True, only_known=False)
>>> tls.set_resumption_interval(interval=datetime.timedelta(hours=6))
set_version(self: c104.TransportSecurity, min: c104.TlsVersion = c104.TlsVersion.NOT_SELECTED, max: c104.TlsVersion = c104.TlsVersion.NOT_SELECTED) → None

sets the supported min and/or max TLS version

When configuring minimum and maximum TLS versions together with cipher suites, it’s crucial to ensure that the selected cipher suites are compatible with the specified TLS versions.

Parameters:
Return type:

None

Raises:

ValueError – config is readonly and cannot be modified further

Example

>>> tls = c104.TransportSecurity(validate=True, only_known=False)
>>> tls.set_version(min=c104.TLSVersion.TLS_1_2, max=c104.TLSVersion.TLS_1_2)