NAME

Noise::HandshakeState - Pattern-based handshake execution

SYNOPSIS

use Noise::HandshakeState;

my $state = Noise::HandshakeState->new(
    initiator => 1,
    pattern   => 'XX',
    s         => $local_static_key
);

# Msg 1
my $msg1 = $state->write_message( 'Hello' );

# Msg 2
my $payload = $state->read_message( $incoming );

DESCRIPTION

Noise::HandshakeState implements the high-level handshake logic of the Noise Protocol. It parses pattern names, processes pre-messages, and executes the sequence of tokens (e, s, ee, es, etc.) required to establish a secure channel.

METHODS

new( %params )

Constructor.

Expected parameters:

initiator: Boolean, true if this node starts the handshake.

pattern: String name (e.g., 'XX', 'IK', 'Noise_NN_25519_AESGCM_SHA512').

s/e: Local static/ephemeral Crypt::PK::X25519 keys.

rs/re: Remote static/ephemeral public keys.

psks: Array reference of 32-byte pre-shared keys.

prologue: Optional initial data.

write_message( $payload )

Processes the next message in the pattern sequence and returns the raw bytes to be sent to the remote peer.

read_message( $bytes )

Parses an incoming message, updates the internal state, and returns the decrypted payload.

split( )

Finalizes the handshake and returns a pair of Noise::CipherState objects for transport.

symmetric_state( )

Returns the underlying Noise::SymmetricState object. This is useful for advanced use cases where manual mixing of additional data into the handshake transcript is required.

rs( )

Returns the remote static public key (as a Crypt::PK::X25519 object) discovered during the handshake. If the pattern does not involve static key exchange, or the key has not been received yet, this returns undef.

re( )

Returns the remote ephemeral public key (as a Crypt::PK::X25519 object) received from the peer. This is typically available after the first message from the remote party.

SEE ALSO

Noise::Pattern, Noise::SymmetricState

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.