Crate snow

Expand description

The snow crate aims to be a straightforward Noise Protocol implementation. See the Noise Protocol Framework Spec for more information.

The typical usage flow is to use Builder to construct a HandshakeState, where you will complete the handshake phase and convert into either a TransportState (typically when done over a reliable transport where the internal message counter can be used) or StatelessTransportState (when you control the message counter for unreliable transports like UDP).

§Example

static PATTERN: &'static str = "Noise_NN_25519_ChaChaPoly_BLAKE2s";

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]);

// -> e
let len = initiator.write_message(&[], &mut first_msg)?;

// responder processes the first message...
responder.read_message(&first_msg[..len], &mut read_buf)?;

// <- e, ee
let len = responder.write_message(&[], &mut second_msg)?;

// initiator processes the response...
initiator.read_message(&second_msg[..len], &mut read_buf)?;

// NN handshake complete, transition into transport mode.
let initiator = initiator.into_transport_mode();
let responder = responder.into_transport_mode();

See examples/simple.rs for a more complete TCP client/server example with static keys.

§Crypto

Cryptographic providers are swappable through Builder::with_resolver(), but by default it chooses select, artisanal pure-Rust implementations (see Cargo.toml for a quick overview).

§Other Providers

§ring

ring is a crypto library based off of BoringSSL and is significantly faster than most of the pure-Rust implementations.

If you enable the ring-resolver feature, Snow will include a resolvers::ring module as well as a RingAcceleratedResolver available to be used with Builder::with_resolver().

If you enable the ring-accelerated feature, Snow will default to choosing ring’s crypto implementations when available.

§Resolver primitives supported

	default	ring
CSPRNG	✔️	✔️
25519	✔️	✔️
448
P-256^🏁	✔️
AESGCM	✔️	✔️
ChaChaPoly	✔️	✔️
XChaChaPoly^🏁	✔️
SHA256	✔️	✔️
SHA512	✔️	✔️
BLAKE2s	✔️
BLAKE2b	✔️

🏁 P-256 and XChaChaPoly are not in the official specification of Noise, and thus need to be enabled via the feature flags use-p256 and use-xchacha20poly1305, respectively.

§`no_std` support and feature selection

Snow can be used in no_std environments if alloc is provided.

By default, Snow uses the standard library, default crypto resolver and a selected collection of crypto primitives. To use Snow in no_std environments or make other kinds of customized setups, use Snow with default-features = false. This way you will individually select the components you wish to use. default-resolver is the only built-in resolver that currently supports no_std.

To use a custom setup with default-resolver, enable your desired selection of cryptographic primitives:

	Primitive	Feature flag
DHs	Curve25519	`use-curve25519`
	P-256^:🏁:	`use-p256`
Ciphers	AES-GCM	`use-aes-gcm`
	ChaChaPoly	`use-chacha20poly1305`
	XChaChaPoly^:🏁:	`use-xchacha20poly1305`
Hashes	SHA-256	`use-sha2`
	SHA-512	`use-sha2`
	BLAKE2s	`use-blake2`
	BLAKE2b	`use-blake2`

🏁 XChaChaPoly and P-256 are not in the official specification of Noise, but they are supported by Snow.

Re-exports§

pub use crate::error::Error;

Modules§

error: All error types used by Snow operations.
params: All structures related to Noise parameter definitions (cryptographic primitive choices, protocol patterns/names)
resolvers: The wrappers around the default collection of cryptography and entropy providers.
types: The traits for cryptographic implementations that can be used by Noise.

Structs§

Builder: Generates a HandshakeState and also validates that all the prerequisites for the given parameters are satisfied.
HandshakeState: A state machine encompassing the handshake phase of a Noise session.
Keypair: A keypair object returned by Builder::generate_keypair()
StatelessTransportState: A state machine encompassing the transport phase of a Noise session, using the two CipherStates (for sending and receiving) that were spawned from the SymmetricState’s Split() method, called after a handshake has been finished.
TransportState: A state machine encompassing the transport phase of a Noise session, using the two CipherStates (for sending and receiving) that were spawned from the SymmetricState’s Split() method, called after a handshake has been finished.

Crate snowCopy item path