add module documentation about new feature flags

src/lib.rs

@@ -52,6 +52,71 @@
 //! ```
 //!
 //! 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](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 `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<sup>🏁</sup>  | ✔️               |                    |
+//! |     AESGCM               | ✔️               | ✔️                 |
+//! | ChaChaPoly               | ✔️               | ✔️                 |
+//! | XChaChaPoly<sup>🏁</sup> | ✔️               |                    |
+//! |     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<sup>:🏁:</sup>       | `use-p256`             |
+//! | **Ciphers** | AES-GCM                    | `use-aes-gcm`          |
+//! |             | ChaChaPoly                 | `use-chacha20poly1305` |
+//! |             | XChaChaPoly<sup>:🏁:</sup> | `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.
 
 #![warn(missing_docs)]
 #![cfg_attr(not(feature = "std"), no_std)]