srp/src/lib.rs

   1 //! [Secure Remote Password][1] (SRP) protocol implementation.
   2 //!
   3 //! This implementation is generic over hash functions using
   4 //! [`Digest`](https://docs.rs/digest) trait, so you will need to choose a hash
   5 //! function, e.g. `Sha256` from [`sha2`](https://crates.io/crates/sha2) crate.
   6 //! Additionally this crate allows to use a specialized password hashing
   7 //! algorithm for private key computation instead of method described in the
   8 //! SRP literature.
   9 //!
  10 //! Compatibility with over implementations was not yet tested.
  11 //!
  12 //! # Usage
  13 //! Add `srp` dependecy to your `Cargo.toml`:
  14 //!
  15 //! ```toml
  16 //! [dependencies]
  17 //! srp = "0.4"
  18 //! ```
  19 //!
  20 //! and this to your crate root:
  21 //!
  22 //! ```rust
  23 //! extern crate srp;
  24 //! ```
  25 //!
  26 //! Next read documentation for [`client`](client/index.html) and
  27 //! [`server`](server/index.html) modules.
  28 //!
  29 //! # Algorithm description
  30 //! Here we briefly describe implemented algroithm. For additionall information
  31 //! refer to SRP literature. All arithmetic is done modulo `N`, where `N` is a
  32 //! large safe prime (`N = 2q+1`, where `q` is prime). Additionally `g` MUST be
  33 //! a generator modulo `N`. It's STRONGLY recommended to use SRP parameters
  34 //! provided by this crate in the [`groups`](groups/index.html) module.
  35 //!
  36 //! |       Client           |   Data transfer   |      Server                     |
  37 //! |------------------------|-------------------|---------------------------------|
  38 //! |`a_pub = g^a`           | — `a_pub`, `I` —> | (lookup `s`, `v` for given `I`) |
  39 //! |`x = PH(P, s)`          | <— `b_pub`, `s` — | `b_pub = k*v + g^b`             |
  40 //! |`u = H(a_pub ‖ b_pub)`  |                   | `u = H(a_pub ‖ b_pub)`          |
  41 //! |`s = (b_pub - k*g^x)^(a+u*x)` |             | `S = (b_pub - k*g^x)^(a+u*x)`   |
  42 //! |`K = H(s)`              |                   | `K = H(s)`                      |
  43 //! |`M1 = H(A ‖ B ‖ K)`     |     — `M1` —>     | (verify `M1`)                   |
  44 //! |(verify `M2`)           |    <— `M2` —      | `M2 = H(A ‖ M1 ‖ K)`            |
  45 //!
  46 //! Variables and notations have the following
  47 //! meaning:
  48 //!
  49 //! - `I` — user identity (username)
  50 //! - `P` — user password
  51 //! - `H` — one-way hash function
  52 //! - `PH` — password hashing algroithm, in the RFC 5054 described as
  53 //! `H(s ‖ H(I ‖ ":" ‖ P))`
  54 //! - `^` — (modular) exponentiation
  55 //! - `‖` — concatenation
  56 //! - `x` — user private key
  57 //! - `s` — salt generated by user and stored on the server
  58 //! - `v` — password verifier equal to `g^x` and stored on the server
  59 //! - `a`, `b` — secret ephemeral values (at least 256 bits in length)
  60 //! - `A`, `B` — Public ephemeral values
  61 //! - `u` — scrambling parameter
  62 //! - `k` — multiplier parameter (`k = H(N || g)` in SRP-6a)
  63 //!
  64 //! [1]: https://en.wikipedia.org/wiki/Secure_Remote_Password_protocol
  65 //! [2]: https://tools.ietf.org/html/rfc5054
  66 #![doc(html_logo_url = "https://raw.githubusercontent.com/RustCrypto/meta/master/logo_small.png")]
  67
  68 pub mod client;
  69 pub mod groups;
  70 pub mod server;
  71 mod tools;
  72 pub mod types;