snow

To use Snow, use the snow::Builder to create an initiator or responder. You must provide a handshake pattern string (e.g., "Noise_NN_25519_ChaChaPoly_BLAKE2s") which is parsed into a pattern. After performing the handshake exchange using write_message and read_message, you must call into_transport_mode() to transition the state machine from the handshake phase into the transport phase for encrypted data exchange.

let mut noise = snow::Builder::new("Noise_NN_25519_ChaChaPoly_BLAKE2s".parse()?)
                    .build_initiator()?;

let mut buf = [0u8; 65535];

// write first handshake message
noise.write_message(&[], &mut buf)?;

// receive response message
let incoming = receive_message_from_the_mysterious_ether();
noise.read_message(&incoming, &mut buf)?;

// complete handshake, and transition the state machine into transport mode
let mut noise = noise.into_transport_mode()?;

The TransportState struct manages the transport phase of a Noise session after a handshake has completed. It maintains two CipherStates (one for sending and one for receiving) to handle encrypted data exchange.

To transition from a handshake to the transport phase, you can convert a HandshakeState into a TransportState using TryFrom or TransportState::new(). This will fail with StateProblem::HandshakeNotFinished if the handshake is not yet complete.

Key capabilities include:

• Encrypting and decrypting messages with optional additional authenticated data (AAD).
• Managing symmetric key rekeying (automatic or manual).
• Accessing the remote party's static public key.
• Managing nonces for use on lossy transports.

use snow::TransportState;
use snow::handshakestate::HandshakeState;

// Assuming 'handshake' is a completed HandshakeState
let mut transport: TransportState = handshake.try_into().expect("Handshake must be finished");

The Builder struct is used to configure the parameters for a Noise handshake and construct a HandshakeState. You can specify cryptographic parameters, static keys, remote public keys, pre-shared keys (PSKs), and handshakes prologues.

Once configured, you call .build_initiator() to create a state for the side sending the first message, or .build_responder() for the side receiving the first message.

Note that many configuration methods can only be called once; attempting to overwrite a parameter (like local_private_key or prologue) will return an Error with InitStage::ParameterOverwrite.

# use snow::Builder;
# fn main() -> Result<(), Box<dyn std::error::Error>> {
let my_long_term_key = [0u8; 32];
let their_pub_key = [0u8; 32];
let noise = Builder::new("Noise_XX_25519_ChaChaPoly_BLAKE2s".parse()?)
    .local_private_key(&my_long_term_key)?
    .remote_public_key(&their_pub_key)?
    .prologue("noise is just swell".as_bytes())?
    .build_initiator()?;
# Ok(())
# }

The typical workflow in Snow involves using a Builder to create a HandshakeState for both an initiator and a responder. Once the handshake messages are exchanged and the handshake is complete, you transition the state into either TransportState (for reliable transports like TCP where internal counters are managed) or StatelessTransportState (for unreliable transports like UDP where you manage the message counter).

use snow::Error;

// Define a Noise pattern (e.g., Noise_NN_25519_ChaChaPoly_BLAKE2s)
static PATTERN: &'static str = "Noise_NN_25519_ChaChaPoly_BLAKE2s";

// 1. Initialize initiator and responder
let mut initiator = snow::Builder::new(PATTERN.parse()?)
    .build_initiator()?;
let mut responder = snow::Builder::new(PATTERN.parse()?)
    .build_responder()?;

let (mut read_buf, mut first_msg, mut second_msg) = ([0u8; 1024], [0u8; 1024], [0u8; 1024]);

// 2. Handshake: Initiator sends first message
let len = initiator.write_message(&[], &mut first_msg)?;

// 3. Handshake: Responder processes first message and sends second
responder.read_message(&first_msg[..len], &mut read_buf)?;
let len = responder.write_message(&[], &mut second_msg)?;

// 4. Handshake: Initiator processes second message
initiator.read_message(&second_msg[..len], &mut read_buf)?;

// 5. Transition to transport mode
let initiator = initiator.into_transport_mode();
let responder = responder.into_transport_mode();