Cipher Suites¶

class siotls.crypto.cipher_suites.TLSCipherSuite¶

Abstract base class and registry for siotls.iana.CipherSuites.

classmethod install(*, duplicate='raise')¶

Install this cipher suite in the registry.

Called by siotls.crypto.install() which is the preferred way of installing cipher suites.

iana_id: CipherSuites¶: The unique numeric identifier of the cipher suite.

property state: CipherState¶: The current state of the cipher.

digestmod: Callable[[...], HASH]¶: The hash algorithm associated to this cipher, from hashlib, e.g. hashlib.sha256.

block_size: int¶: The block size (in bytes) of the underlying AEAD algorithm.

key_length: int¶: The secret key size (in bytes) of the underlying AEAD algorithm.

tag_length: int¶: The length (in bytes) of the authenticated tag produced in addition to the cipher text.

nonce_length: int¶: The length (in bytes) of the nonce, as required by the underlying AEAD algorithm.

hashempty: bytes¶

>>> digestmod(b"").digest()

hashzeros: bytes¶

>>> b"" * digestmod().digest_size

__init__(side, client_unique, *, log_keys)¶

Parameters:

side ('client' | 'server') – This side of the connection.
client_unique (bytes) – The unique client identifier, coming from random. Ignored unless log_keys is True.
log_keys (bool) – Whether to log the TLS secrets on the siotls.keylog logger. For network analysing tools such as wireshark.

property must_decrypt: bool¶: Whether it is necessary to decrypt the next received TLS record.

property must_encrypt: bool¶: Whether it is necessary to encryt the next TLS record.

property should_rekey: bool¶: Whether it would be wise to exchange new keying materials with the peer.

decrypt(data, associated_data)¶

Decrypt the cipher data and tag concatenated, verify the cipher and return the plaintext.

Parameters:

nonce – nonce_length bytes, generated by TLS.
data (bytes) – The encrypted TLS content to decrypt.
associated_data (bytes) – The 5 bytes of the TLS record header.

Returns:

The plaintext of len(data) - self.tag_length bytes.

Return type:

bytes

encrypt(data, associated_data)¶

Encrypt the plain data, return the ciphertext and tag concatenated.

Parameters:

data – The plain TLS content to encrypt.
associated_data – The 5 bytes of the TLS record header.

Returns:

The ciphertext of len(data) size and tag of tag_length concatenated.

sign_finish(transcript_hash)¶

Compute a HMAC over the the transcript digest, for the Finished handshake.

Parameters:: transcript_hash (bytes)
Return type:: bytes

verify_finish(transcript_hash, other_verify_data)¶

Compute a HMAC over the transcript digest, and compare it against the Finished handshake sent by the peer.

Raises:

ValueError – When the HMACs don’t match.

Parameters:

transcript_hash (bytes)
other_verify_data (bytes)

Return type:

None

skip_early_secrets()¶

Advance from state CipherState.INIT to a transitional state CipherState.EARLY.

This state is transitional and serves no other purpose than preparing the underlying cipher to move to state CipherState.HANDSHAKE.

A call to derive_handshake_secrets() MUST follow immediately.

derive_early_secrets(psk, psk_mode, client_hello_th)¶: Advance from state CipherState.INIT to state state CipherState.EARLY.

derive_handshake_secrets(shared_key, server_hello_th)¶: Advance from state CipherState.EARLY to state state CipherState.HANDSHAKE.

derive_master_secrets(server_finished_th, client_finished_th)¶: Advance from state CipherState.HANDSHAKE to state state CipherState.APPLICATION.

class siotls.crypto.cipher_suites.CipherState¶

The state of the cipher.

INIT = 0¶

No encryption.

Used during the initial ClientHello and ServerHello exchange.

EARLY = 1¶

Encryption using the early secret, a PSK shared by both the client and server (obtained either externally or via a previous handshake).

Allows the client to send encrypted data on the same flight as its (plain) ClientHello.

HANDSHAKE = 2¶

Encryption using the handshake secret, a new secret that is unique to this connection and that was shared via TLSKeyExchange during the initial ClientHello/ServerHello exchange.

Used by all other handshakes, except KeyUpdate and NewSessionTicket which are sent in the APPLICATION state.

APPLICATION = 3¶

Encryption using the main secret, a new secret unique to this connection that is derived from the handshake secret.

Used for all messages, including handshakes, exchanged once the secure connection is established.

__new__(value)¶

Backend¶

class siotls.crypto.cipher_suites.ICipher¶

Interface that must be implemented by every concrete cipher suite.

abstractmethod _ciphermod(key)¶

Instantiate a new cipher, with a new secret key.

Parameters:: key (bytes) – A secret key of key_length bytes.
Return type:: None

abstractmethod _decrypt(nonce, data, associated_data)¶

Decrypt the data and verify that the tag match the associated data.

Parameters:

nonce (bytes) – A unique value of nonce_length bytes.
data (bytes) – The encrypted TLS content to decrypt.
associated_data (bytes) – The 5 bytes of the TLS record header.

Returns:

The plaintext of len(data) - tag_length bytes.

Return type:

bytes

abstractmethod _encrypt(nonce, data, associated_data)¶

Encrypt the data and compute a tag over the associated data.

Parameters:

nonce (bytes) – A unique value of nonce_length bytes.
data (bytes) – The plain TLS content to encrypt.
associated_data (bytes) – The 5 bytes of the TLS record header.

Returns:

The ciphertext of len(data) bytes and the tag of tag_length bytes, concatenated.

Return type:

bytes

class siotls.crypto.cipher_suites.Aes128GcmMixin¶

Mixin for AES-GCM and a 128 bits keys.

This mixin can be inherited by crypto backends to feed all the attributes required by TLSCipherSuite that are specific to TLS_AES_128_GCM_SHA256.

Specifically, this mixin has values for: iana_id, digestmod, block_size, key_length, tag_length, nonce_length, hashempty, and hashzeros.

class siotls.crypto.cipher_suites.Aes256GcmMixin¶

Mixin for AES-GCM and a 256 bits keys.

This mixin can be inherited by crypto backends to feed all the attributes required by TLSCipherSuite that are specific to TLS_AES_256_GCM_SHA384.

Specifically, this mixin has values for: iana_id, digestmod, block_size, key_length, tag_length, nonce_length, hashempty, and hashzeros.

class siotls.crypto.cipher_suites.ChaPolyMixin¶

Mixin for Chacha-Poly1305.

This mixin can be inherited by crypto backends to feed all the attributes required by TLSCipherSuite that are specific to TLS_CHACHA20_POLY1305_SHA256.

Specifically, this mixin has values for: iana_id, digestmod, block_size, key_length, tag_length, nonce_length, hashempty, and hashzeros.

class siotls.crypto.cipher_suites.Aes128CcmMixin¶

Mixin for AES-CCM and a 128 bits tag.

This mixin can be inherited by crypto backends to feed all the attributes required by TLSCipherSuite that are specific to TLS_AES_128_CCM_SHA256.

Specifically, this mixin has values for: iana_id, digestmod, block_size, key_length, tag_length, nonce_length, hashempty, and hashzeros.

class siotls.crypto.cipher_suites.Aes128Ccm8Mixin¶

Mixin for AES-CCM and a 64 bits tag.

This mixin can be inherited by crypto backends to feed all the attributes required by TLSCipherSuite that are specific to TLS_AES_128_CCM_8_SHA256.

Specifically, this mixin has values for: iana_id, digestmod, block_size, key_length, tag_length, nonce_length, hashempty, and hashzeros.