Noise.CipherState (Noise Protocol v0.3.0)

View Source

A CipherState (spec §5.1): a 32-byte key k and a 64-bit nonce n.

Produced in pairs by Noise.split/1 once a handshake completes; used for transport messages through Noise.encrypt/3 and Noise.decrypt/3.

Spec rules enforced here:

  • n is never incremented on a failed decryption.
  • Once n reaches 2^64-1 (reserved for rekey/1) every further encrypt/decrypt returns {:error, :nonce_exhausted}.

The key is redacted from inspect/1 output.

Summary

Types

error()
t()

Functions

decrypt_with_ad(state, ad, cipher_text)

DECRYPT(k, n, ad, ciphertext) then n++; n is unchanged on failure (spec §5.1).

encrypt_with_ad(state, ad, plain_text)

ENCRYPT(k, n, ad, plaintext) then n++ (spec §5.1).

has_key?(cipher_state)
initialize(protocol)

A CipherState without a key; encrypt/decrypt pass data through unchanged (spec §5.1).

initialize_key(state, key)

Sets a 32-byte key and resets the nonce to 0.

nonce(cipher_state)
rekey(state)

REKEY(k) (spec §4.2 / §11.3). The nonce is not reset.

set_nonce(state, n)

Sets the nonce explicitly (spec §11.4, out-of-order transport messages).

Types

error()

@type error() :: :decrypt_failed | :nonce_exhausted

t()

@opaque t()

Functions

decrypt_with_ad(state, ad, cipher_text)

@spec decrypt_with_ad(t(), binary(), binary()) ::
  {:ok, binary(), t()} | {:error, error()}

DECRYPT(k, n, ad, ciphertext) then n++; n is unchanged on failure (spec §5.1).

encrypt_with_ad(state, ad, plain_text)

@spec encrypt_with_ad(t(), binary(), binary()) ::
  {:ok, binary(), t()} | {:error, :nonce_exhausted}

ENCRYPT(k, n, ad, plaintext) then n++ (spec §5.1).

has_key?(cipher_state)

@spec has_key?(t()) :: boolean()

initialize(protocol)

@spec initialize(Noise.Protocol.t()) :: t()

A CipherState without a key; encrypt/decrypt pass data through unchanged (spec §5.1).

initialize_key(state, key)

@spec initialize_key(t(), Noise.Crypto.Cipher.key()) :: t()

Sets a 32-byte key and resets the nonce to 0.

nonce(cipher_state)

@spec nonce(t()) :: non_neg_integer()

rekey(state)

@spec rekey(t()) :: t()

REKEY(k) (spec §4.2 / §11.3). The nonce is not reset.

set_nonce(state, n)

@spec set_nonce(t(), non_neg_integer()) :: t()

Sets the nonce explicitly (spec §11.4, out-of-order transport messages).

Raises ArgumentError for values outside 0..2^64-2.