NAME
Noise::SymmetricState - Cryptographic transcript and chaining key management
SYNOPSIS
use Noise::SymmetricState;
my $state = Noise::SymmetricState->new(
hash => 'SHA256',
cipher => 'ChaChaPoly'
);
$state->initialize_symmetric( 'Noise_XX_25519_ChaChaPoly_SHA256' );
$state->mix_hash( $some_data );
$state->mix_key( $shared_secret );
my $ct = $state->encrypt_and_hash( $plaintext );DESCRIPTION
Noise::SymmetricState manages the two primary variables of a Noise handshake: the handshake hash (h) and the chaining key (ck).
It ensures that all messages sent or received are incorporated into the transcript and that encryption keys are derived correctly according to the Noise specification.
METHODS
new( %params )
Constructor.
Expected parameters:
initialize_symmetric( $protocol_name )
Sets the initial values for h and ck based on the full protocol name.
mix_key( $ikm )
Updates the chaining key and derives a new symmetric encryption key using HKDF with the provided Input Keying Material.
mix_hash( $data )
Updates the handshake hash h by hashing it with $data.
mix_key_and_hash( $ikm )
A specialized version of key and hash mixing used primarily for pre-shared keys (PSKs).
encrypt_and_hash( $plaintext )
Encrypts $plaintext using the internal Noise::CipherState and then incorporates the resulting ciphertext into the handshake hash.
decrypt_and_hash( $ciphertext )
Decrypts $ciphertext and incorporates it into the handshake hash.
split( )
Finalizes the handshake phase. Returns two Noise::CipherState objects, one for each direction of communication.
h( )
Returns the current handshake hash. This is a running hash of everything that has been sent or received so far in the handshake. It is used as associated data for all encryption/decryption within the handshake to ensure the integrity of the entire transcript.
ck( )
Returns the current chaining key. The chaining key is used to derive new keys (via HKDF) whenever a Diffie-Hellman exchange occurs. It ensures that future keys are cryptographically linked to all previous secrets.
cipher_state( )
Returns the underlying Noise::CipherState object. This object manages the encryption key derived from the chaining key and handles the actual symmetric cryptographic operations.
SEE ALSO
Noise::CipherState, Noise::HandshakeState
AUTHOR
Sanko Robinson <sanko@cpan.org>
COPYRIGHT
Copyright (C) 2026 by Sanko Robinson.
This library is free software; you can redistribute it and/or modify it under the terms of the Artistic License 2.0.