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

# use snow::Error;
#
# #[cfg(any(feature = "default-resolver-crypto", feature = "ring-accelerated"))]
# fn try_main() -> Result<(), Error> {
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();
#     Ok(())
# }
#
# #[cfg(not(any(feature = "default-resolver-crypto", feature = "ring-accelerated")))]
# fn try_main() -> Result<(), ()> { Ok(()) }
#
# fn main() {
#     try_main().unwrap();
# }

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

🏁 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:

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