aucpace/lib.rs
1#![no_std]
2#![cfg_attr(docsrs, feature(doc_cfg))]
3#![doc = include_str!("../README.md")]
4#![doc(
5 html_logo_url = "https://raw.githubusercontent.com/RustCrypto/meta/master/logo.svg",
6 html_favicon_url = "https://raw.githubusercontent.com/RustCrypto/meta/master/logo.svg"
7)]
8#![forbid(unsafe_code)]
9#![warn(missing_docs, rust_2018_idioms, unused_qualifications)]
10#![allow(clippy::large_enum_variant)]
11
12//! # Usage
13//! Add `aucpace` to your `Cargo.toml`:
14//!
15//! ```toml
16//! [dependencies]
17//! aucpace = "0.1"
18//! ```
19//!
20//! Next read documentation for [`client`](client/index.html) and
21//! [`server`](server/index.html) modules.
22//!
23//! # Protocol description
24//! Here we briefly describe the AuCPace Protocol. For additional information
25//! refer to AuCPace literature[1]. All arithmetic is done on the (hyper-) elliptic curve `C`
26//! in group `J`, with co-factor `c_J` and Diffie-Hellman base point `B` in `J`.
27//! It's STRONGLY recommended to use AuCPace parameters provided by this crate
28//! in the [`Client`](Client) and [`Server`](Server) default instantiations.
29//!
30//! | Server | Data transfer | Client |
31//! |---------------------------------|-------------------|---------------------------------|
32//! | | Agree on ssid | |
33//! |`s = ${0,1}^k1` | <- `t`, `s` -> | `t = {0,1}^k1` |
34//! |`ssid = H0(s `\|\|` t)` | | `ssid = H0(s `\|\|` t)` |
35//! | |Augmentation layer | |
36//! |`x = ${1..m_J}` | | |
37//! |`X = B^(x * c_J)` | <- `username` | |
38//! |`W,salt = lookupW(user)` |`J,X,salt,sigma` ->| |
39//! | | |`w = PBKDF_sigma(pw, user, salt)`|
40//! |if lookup failed `PRS = {0,1}^k2`| |abort if `X` invalid |
41//! |else `PRS = W^(x * c_J)` | |`PRS = X^(w * c_J)` |
42//! | |CPace substep | |
43//! |`g' = H1(ssid`\|\|`PRS`\|\|`CI)` | |`g' = H1(ssid`\|\|`PRS`\|\|`CI)` |
44//! |`G = Map2Point(g')` | |`G = Map2Point(g')` |
45//! |`ya = ${1..m_J}` | | `yb = ${1..m_J}` |
46//! |`Ya = G^(ya * cj)` | <- `Yb` `Ya` -> | `Yb = G^(yb * cj)` |
47//! |`K = Yb^(ya * cj)` | | `K = Ya^(yb * cj)` |
48//! |abort if `Yb` invalid | |abort if `Ya` invalid |
49//! |`sk1 = H2(ssid `\|\|` K)` | |`sk1 = H2(ssid `\|\|` K)` |
50//! | |Explicit Mutual Authentication| |
51//! |`Ta = H3(ssid `\|\|` sk1)` | `Ta`-> |`Ta = H3(ssid `\|\|` sk1)` |
52//! |`Tb = H4(ssid `\|\|` sk1)` | <- `Tb` |`Tb = H4(ssid `\|\|` sk1)` |
53//! |verify `Tb` | |verify `Ta` |
54//! |`sk = H5(ssid `\|\|` sk1)` | |`sk = H5(ssid `\|\|` sk1)` |
55//!
56//! Variables and notations have the following meaning:
57//!
58//! - `k1` — length of nonce to use in SSID agreement step
59//! - `k2` — length of the wire representation of a curve point
60//! - `s`, `t` — nonces used in SSID agreement
61//! - `H` — one-way hash function
62//! - `H0..H5` — `H` where the index is prepended to the input as a little-endian four-byte word
63//! - `${a,b}^N` — pick randomly from `a` and `b`, `N` times
64//! - `${a..b}` — pick a number between `a` and `b`
65//! - `^` — Curve point multiplication
66//! - `*` — Scalar value multiplication
67//! - ‖ — concatenation
68//! - `m_J` — the order of `J`
69//! - `c_J` — co-factor of `J`
70//! - `PBKDF_sigma` — password based key derivation function, parameterised by `sigma`
71//! - `ssid` — subsession ID
72//! - `PRS` — Password Related String
73//! - `CI` — Channel Identifier
74//! - `lookupW` — the server lookup of the password verifier for the user
75//! - `Map2Point` — map a binary string to a random curve point such that its discrete logarithm is unknown
76//! - `G` — the ephemeral generator for the diffie hellman protocol
77//! - `ya`,`yb` — ephemeral secret group elements for diffie hellman protocol
78//! - `Ya`,`Yb` — public group elements for diffie hellman protocol
79//! - `K` — shared secret point from diffie hellman protocol
80//! - `sk1` — first session key derived from K
81//! - `sk` — the final session key refreshed from sk1
82//!
83//! [1]: https://eprint.iacr.org/2018/286.pdf
84
85mod database;
86mod errors;
87mod utils;
88
89/// Module containing the implementation of the client for the AuCPace protocol
90pub mod client;
91
92/// Module containing the implementation of the server for the AuCPace protocol
93pub mod server;
94
95/// Module contains constants used in the code
96pub mod constants;
97
98pub use self::{
99 client::{AuCPaceClient, ClientMessage},
100 database::Database,
101 errors::{Error, Result},
102 server::{AuCPaceServer, ServerMessage},
103};
104
105#[cfg(feature = "partial_augmentation")]
106pub use self::database::PartialAugDatabase;
107
108#[cfg(feature = "strong_aucpace")]
109pub use self::database::StrongDatabase;
110
111/// Default Server instantiation with SHA512, OsRng and a nonce size of 16 bytes
112#[cfg(all(feature = "sha2", feature = "getrandom"))]
113pub type Server = AuCPaceServer<sha2::Sha512, rand_core::OsRng, 16>;
114
115/// Default Client instantiation with SHA512, Scrypt, OsRng and a nonce size of 16 bytes
116#[cfg(all(feature = "scrypt", feature = "sha2", feature = "getrandom"))]
117pub type Client = AuCPaceClient<sha2::Sha512, scrypt::Scrypt, rand_core::OsRng, 16>;