easy-srp 0.1.0

easy-srp wraps the rust srp crate and provides an easy to use API.
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
82
83
84
85
86
87
88
89
90
91
92
93

# Wrapper crate for the `srp` for easy usage

## Overview

The [srp](https://crates.io/crates/srp) crate provides the means for using
SRP6a athentication.
This crate wraps the `srp` crate to make the authentication workflows
more obvious easy to use.

This is done via the following means:
  * provide `Workflow` structs for the 3 typical workflows:
    * generation of initial registration data
    * client authentication
    * server authentication
  * name methods `step#` with increasing number `#`, so it is obvious in
    which phase of the authentication the method needs to be called.
  * include automatic random value generation (for ephemeral keys and salt)

## Features
  
  * Support for the web via WebAssembly. Therefore, this crate can be used
    with WASM-based web-UI frameworks like [yew](https://crates.io/crates/yew).
  * Easy to use.

## Available rust/cargo `features`

  * `client`: Include client classes (`ClientAuthenticationWorkflow`,
    `ClientRegistrationWorkflow`, ...).
  * `server`: Include server classes (`ServerAuthenticationWorkflow`, etc.)
  * `base64`: Include the [base64](https://crates.io/crates/base64) crate
    and provide `base64` serialization for various byte array parameters.
  * `serialization`: Include the [serde](https://crates.io/crates/serde) crate
    and add `Serialize` and `Deserialize` to various structs. This also
    enables the `base64` feature.
  * `js`: This crate uses the [getrandom](https://crates.io/crates/getrandom)
    crate for generating random numbers (salt, client/server ephemeral key).
    `getrandom` supports a variety of platforms, including web browsers (in
    WebAssembly). If `easy-srp` is used inside the browser, use the `js`
    feature to make `getrandom` use the `Crypto.getRandomValues()` JavaScript
    method for random number generation.

## Usage

### SRP6a protocol

#### User registration

  1) User enters `username` and `password`
  2) Client generates random `salt`
  3) Client computes `verifier` from the obove credentials
  4) Client sends `username`, `salt` and `verifier` to the server via 
     a secure channel.
  5) Server stores these three credentials.

#### User authentication

| Client               |      | Server                      |
| -------------------- | ---- | --------------------------- |
| `(username, pub_a)`  |  ->  |                             |
|                      |  <-  | `(salt, pub_b)`             |
| `(proof_a)`          |  ->  |                             |
|                      |  <-  | `(proof_b)`                 |

  1) client sends `(username, pub_a)` to server.
  2) server looks up `(salt, verifier)`
  3) server computes an ephemeral private key `b` and derives its public
     key `pub_b`.
  4) server sends `(salt, pub_b)` to the client.
  5) client calculates proof `proof_a` and sends `(proof_a)` to the server.
  6) server verifies `proof_a`
  7) server computes its own proof `proof_b` and sends it to the client
  8) client verifies `proof_b`
  9) both sides are now able to calculate a common secret key. the size of
     the key depends on the used digest, e.g. 256 bits (32 bytes) for `SHA256`

## Generate client registration data

## Client example

## Server example

## Dependencies

The following dependencies are included intentionally (aka directly):

 * [srp](https://crates.io/crates/srp)
 * [digest](https://crates.io/crates/digest) (also included transitively 
   via `srp`)
 * [getrandom](https://crates.io/crates/getrandom)
 * [base64](https://crates.io/crates/base64) (feature `base64`)
 * [serde](https://crates.io/crates/serde) (feature `serde`)

Additional dependencies may be included transitively.