spake2/README.md

   1 # [RustCrypto]: SPAKE2
   2
   3 [![crate][crate-image]][crate-link]
   4 [![Docs][docs-image]][docs-link]
   5 ![Apache2/MIT licensed][license-image]
   6 ![Rust Version][rustc-image]
   7 [![Project Chat][chat-image]][chat-link]
   8 [![Build Status][build-image]][build-link]
   9
  10 Pure Rust implementation of the [SPAKE2] password-authenticated key-exchange algorithm.
  11
  12 [Documentation][docs-link]
  13
  14 ## About
  15
  16 This library implements the SPAKE2 password-authenticated key exchange
  17 ("PAKE") algorithm. This allows two parties, who share a weak password, to
  18 safely derive a strong shared secret (and therefore build an
  19 encrypted+authenticated channel).
  20
  21 A passive attacker who eavesdrops on the connection learns no information
  22 about the password or the generated secret. An active attacker
  23 (man-in-the-middle) gets exactly one guess at the password, and unless they
  24 get it right, they learn no information about the password or the generated
  25 secret. Each execution of the protocol enables one guess. The use of a weak
  26 password is made safer by the rate-limiting of guesses: no off-line
  27 dictionary attack is available to the network-level attacker, and the
  28 protocol does not depend upon having previously-established confidentiality
  29 of the network (unlike e.g. sending a plaintext password over TLS).
  30
  31 The protocol requires the exchange of one pair of messages, so only one round
  32 trip is necessary to establish the session key. If key-confirmation is
  33 necessary, that will require a second round trip.
  34
  35 All messages are bytestrings. For the default security level (using the
  36 Ed25519 elliptic curve, roughly equivalent to an 128-bit symmetric key), the
  37 message is 33 bytes long.
  38
  39 This implementation is generic over a `Group`, which defines the cyclic
  40 group to use, the functions which convert group elements and scalars to
  41 and from bytestrings, and the three distinctive group elements used in
  42 the blinding process. Only one such Group is implemented, named
  43 `Ed25519Group`, which provides fast operations and high security, and is
  44 compatible with my [python implementation](https://github.com/warner/python-spake2).
  45
  46 # What Is It Good For?
  47
  48 PAKE can be used in a pairing protocol, like the initial version of Firefox
  49 Sync (the one with J-PAKE), to introduce one device to another and help them
  50 share secrets. In this mode, one device creates a random code, the user
  51 copies that code to the second device, then both devices use the code as a
  52 one-time password and run the PAKE protocol. Once both devices have a shared
  53 strong key, they can exchange other secrets safely.
  54
  55 PAKE can also be used (carefully) in a login protocol, where SRP is perhaps
  56 the best-known approach. Traditional non-PAKE login consists of sending a
  57 plaintext password through a TLS-encrypted channel, to a server which then
  58 checks it (by hashing/stretching and comparing against a stored verifier). In
  59 a PAKE login, both sides put the password into their PAKE protocol, and then
  60 confirm that their generated key is the same. This nominally does not require
  61 the initial TLS-protected channel. However note that it requires other,
  62 deeper design considerations (the PAKE protocol must be bound to whatever
  63 protected channel you end up using, else the attacker can wait for PAKE to
  64 complete normally and then steal the channel), and is not simply a drop-in
  65 replacement. In addition, the server cannot hash/stretch the password very
  66 much (see the note on "Augmented PAKE" below), so unless the client is
  67 willing to perform key-stretching before running PAKE, the server's stored
  68 verifier will be vulnerable to a low-cost dictionary attack.
  69
  70 ## ⚠️ Security Warning
  71
  72 This crate has never received an independent third party audit for security and
  73 correctness.
  74
  75 USE AT YOUR OWN RISK!
  76
  77 ## Minimum Supported Rust Version
  78
  79 Rust **1.56** or higher.
  80
  81 Minimum supported Rust version can be changed in the future, but it will be
  82 done with a minor version bump.
  83
  84 ## License
  85
  86 Licensed under either of:
  87
  88  * [Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0)
  89  * [MIT license](http://opensource.org/licenses/MIT)
  90
  91 at your option.
  92
  93 ### Contribution
  94
  95 Unless you explicitly state otherwise, any contribution intentionally submitted
  96 for inclusion in the work by you, as defined in the Apache-2.0 license, shall be
  97 dual licensed as above, without any additional terms or conditions.
  98
  99 [//]: # (badges)
 100
 101 [crate-image]: https://img.shields.io/crates/v/spake2.svg
 102 [crate-link]: https://crates.io/crates/spake2
 103 [docs-image]: https://docs.rs/spake2/badge.svg
 104 [docs-link]: https://docs.rs/spake2/
 105 [license-image]: https://img.shields.io/badge/license-Apache2.0/MIT-blue.svg
 106 [rustc-image]: https://img.shields.io/badge/rustc-1.56+-blue.svg
 107 [chat-image]: https://img.shields.io/badge/zulip-join_chat-blue.svg
 108 [chat-link]: https://rustcrypto.zulipchat.com/#narrow/stream/260045-PAKEs
 109 [build-image]: https://github.com/RustCrypto/PAKEs/actions/workflows/spake2.yml/badge.svg
 110 [build-link]: https://github.com/RustCrypto/PAKEs/actions/workflows/spake2.yml
 111
 112 [//]: # (general links)
 113
 114 [RustCrypto]: https://github.com/RustCrypto
 115 [SPAKE2]: https://tools.ietf.org/id/draft-irtf-cfrg-spake2-10.html