snow 0.5.0-alpha2

A pure-rust implementation of the Noise Protocol Framework
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81

# Snow

[![Crates.io](https://img.shields.io/crates/v/snow.svg)](https://crates.io/crates/snow)
[![Docs.rs](https://docs.rs/snow/badge.svg)](https://docs.rs/snow)
[![Build Status](https://travis-ci.org/mcginty/snow.svg?branch=master)](https://travis-ci.org/mcginty/snow)
[![dependency status](https://deps.rs/repo/github/mcginty/snow/status.svg)](https://deps.rs/repo/github/mcginty/snow)

![totally official snow logo](https://i.imgur.com/gFgvo49.jpg?1)

An implementation of Trevor Perrin's [Noise Protocol](https://noiseprotocol.org/) that is designed to be
Hard To Fuck Upâ„¢.

🔥 **Warning** 🔥 This library has not received any formal audit, and its API is subject to change whenever it's
prudent to or if the winds blow at the right heading.

## What's it look like?
See `examples/simple.rs` for a more complete TCP client/server example.

```rust
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()?;
```

See the full documentation at [https://docs.rs/snow](https://docs.rs/snow).


## Implemented

Snow is currently tracking against [Noise spec revision 34](https://noiseprotocol.org/noise_rev34.html).

However, a not all features have been implemented yet (pull requests welcome):

- [ ] [The `fallback` modifier](https://noiseprotocol.org/noise_rev34.html#the-fallback-modifier)

## 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).

### Providers

#### ring

[ring](https://github.com/briansmith/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 `ring_wrapper` 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.

#### HACL*

[HACL*](https://github.com/mitls/hacl-star) is a formally verified cryptographic library, accessed via the [`rust-hacl-star`](https://github.com/quininer/rust-hacl-star) wrapper crate.

If you enable the `hacl-resolver` feature, Snow will include a `hacl_wrapper` module as well as a `HaclStarResolver` available to be used with `Builder::with_resolver()`.

Similar to ring, if you enable the `hacl-accelerated` feature, Snow will default to choosing HACL* implementations when available.

### Resolver primitives supported

|            | default | ring | hacl* |
|-----------:|:-------:|:----:|:-----:|
| CSPRNG     | ✔       |      |       |
| 25519      | ✔       | ✔    | ✔     |
| 448        |         |      |       |
| AESGCM     | ✔       | ✔    |       |
| ChaChaPoly | ✔       | ✔    | ✔     |
| SHA256     | ✔       | ✔    | ✔     |
| SHA512     | ✔       | ✔    | ✔     |
| BLAKE2s    | ✔       |      |       |
| BLAKE2b    | ✔       |      |       |