NAME

Noise::Stream - Encrypted transport stream using the Noise Protocol

SYNOPSIS

use Noise::Stream;

my $secure_stream = Noise::Stream->new(
    socket => $socket,
    c_send => $cipher_state_1,
    c_recv => $cipher_state_2
);

# Write an encrypted frame
$secure_stream->write_bin( 'Secret data' );

# Rekey for long-lived streams
$secure_stream->rekey_send( );

DESCRIPTION

Noise::Stream provides a wrapper around a raw socket or filehandle that handles the framing and encryption/decryption of data following a successful Noise handshake.

It uses a 2-byte big-endian length prefix for frames and increments nonces automatically via the underlying Noise::CipherState objects.

METHODS

new(%params)

Constructor.

Expected parameters:

socket: The underlying raw handle.

c_send: A Noise::CipherState object for encryption.

c_recv: A Noise::CipherState object for decryption.

initial_buffer: (Optional) Bytes already read from the handle.

write_bin( $data )

Encrypts $data and writes a Noise-framed message to the socket.

read_bin( $length )

Reads and decrypts data from the socket. If $length is provided, it returns exactly that many bytes (waiting if necessary). Otherwise, it returns all currently available decrypted data.

rekey_send( )

Rotates the encryption key used for outgoing messages. This calls the rekey() method on the internal c_send Noise::CipherState object. Rekeying is recommended for long-lived streams to limit the amount of data encrypted with a single key.

rekey_recv( )

Rotates the decryption key used for incoming messages. This calls the rekey() method on the internal c_recv Noise::CipherState object. This must be called in synchronization with the remote peer's rekey_send() to maintain successful communication.

close( )

Closes the underlying socket.

SEE ALSO

Noise

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.