diff options
Diffstat (limited to 'spake2/README.md')
| -rw-r--r-- | spake2/README.md | 142 |
1 files changed, 114 insertions, 28 deletions
diff --git a/spake2/README.md b/spake2/README.md index 50fa5bf..e2cd59f 100644 --- a/spake2/README.md +++ b/spake2/README.md @@ -1,29 +1,115 @@ -# spake2.rs -The SPAKE2 password-authenticated key-exchange algorithm, in Rust. - -[![Build Status][build-status-image]][build-status-url] -[![Codecov][codecov-image]][codecov-url] -[![Is-It-Maintained-Resolution-Time][iim-resolution-image]][iim-resolution-url] -[![Is-It-Maintained-Open-Issues][iim-open-image]][iim-open-url] -[![Crates.io][crates-io-image]][crates-io-url] -[![Docs.rs][docs-image]][docs-url] -[![License][license-image]][license-url] - -This is still pretty early, but seems to do the job. It needs a proper security review before you should consider using it for anything serious. - -Note that the API has changed since 0.0.8 . I released 0.0.9 by mistake. - -[build-status-image]: https://travis-ci.org/RustCrypto/PAKEs.svg?branch=master -[build-status-url]: https://travis-ci.org/RustCrypto/PAKEs -[codecov-image]: https://codecov.io/gh/RustCrypto/PAKEs/branch/master/graph/badge.svg -[codecov-url]: https://codecov.io/gh/RustCrypto/PAKEs -[crates-io-image]: https://img.shields.io/crates/v/spake2.svg -[crates-io-url]: https://crates.io/crates/spake2 +# [RustCrypto]: SPAKE2 + +[![crate][crate-image]][crate-link] +[![Docs][docs-image]][docs-link] +![Apache2/MIT licensed][license-image] +![Rust Version][rustc-image] +[![Project Chat][chat-image]][chat-link] +[![Build Status][build-image]][build-link] + +Pure Rust implementation of the [SPAKE2] password-authenticated key-exchange algorithm. + +[Documentation][docs-link] + +## About + +This library implements the SPAKE2 password-authenticated key exchange +("PAKE") algorithm. This allows two parties, who share a weak password, to +safely derive a strong shared secret (and therefore build an +encrypted+authenticated channel). + +A passive attacker who eavesdrops on the connection learns no information +about the password or the generated secret. An active attacker +(man-in-the-middle) gets exactly one guess at the password, and unless they +get it right, they learn no information about the password or the generated +secret. Each execution of the protocol enables one guess. The use of a weak +password is made safer by the rate-limiting of guesses: no off-line +dictionary attack is available to the network-level attacker, and the +protocol does not depend upon having previously-established confidentiality +of the network (unlike e.g. sending a plaintext password over TLS). + +The protocol requires the exchange of one pair of messages, so only one round +trip is necessary to establish the session key. If key-confirmation is +necessary, that will require a second round trip. + +All messages are bytestrings. For the default security level (using the +Ed25519 elliptic curve, roughly equivalent to an 128-bit symmetric key), the +message is 33 bytes long. + +This implementation is generic over a `Group`, which defines the cyclic +group to use, the functions which convert group elements and scalars to +and from bytestrings, and the three distinctive group elements used in +the blinding process. Only one such Group is implemented, named +`Ed25519Group`, which provides fast operations and high security, and is +compatible with my [python implementation](https://github.com/warner/python-spake2). + +# What Is It Good For? + +PAKE can be used in a pairing protocol, like the initial version of Firefox +Sync (the one with J-PAKE), to introduce one device to another and help them +share secrets. In this mode, one device creates a random code, the user +copies that code to the second device, then both devices use the code as a +one-time password and run the PAKE protocol. Once both devices have a shared +strong key, they can exchange other secrets safely. + +PAKE can also be used (carefully) in a login protocol, where SRP is perhaps +the best-known approach. Traditional non-PAKE login consists of sending a +plaintext password through a TLS-encrypted channel, to a server which then +checks it (by hashing/stretching and comparing against a stored verifier). In +a PAKE login, both sides put the password into their PAKE protocol, and then +confirm that their generated key is the same. This nominally does not require +the initial TLS-protected channel. However note that it requires other, +deeper design considerations (the PAKE protocol must be bound to whatever +protected channel you end up using, else the attacker can wait for PAKE to +complete normally and then steal the channel), and is not simply a drop-in +replacement. In addition, the server cannot hash/stretch the password very +much (see the note on "Augmented PAKE" below), so unless the client is +willing to perform key-stretching before running PAKE, the server's stored +verifier will be vulnerable to a low-cost dictionary attack. + +## ⚠️ Security Warning + +This crate has never received an independent third party audit for security and +correctness. + +USE AT YOUR OWN RISK! + +## Minimum Supported Rust Version + +Rust **1.56** or higher. + +Minimum supported Rust version can be changed in the future, but it will be +done with a minor version bump. + +## License + +Licensed under either of: + + * [Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0) + * [MIT license](http://opensource.org/licenses/MIT) + +at your option. + +### Contribution + +Unless you explicitly state otherwise, any contribution intentionally submitted +for inclusion in the work by you, as defined in the Apache-2.0 license, shall be +dual licensed as above, without any additional terms or conditions. + +[//]: # (badges) + +[crate-image]: https://img.shields.io/crates/v/spake2.svg +[crate-link]: https://crates.io/crates/spake2 [docs-image]: https://docs.rs/spake2/badge.svg -[docs-url]: https://docs.rs/spake2 -[license-image]: https://img.shields.io/crates/l/spake2.svg -[license-url]: LICENSE-MIT -[iim-resolution-image]: http://isitmaintained.com/badge/resolution/RustCrypto/PAKEs.svg -[iim-resolution-url]: http://isitmaintained.com/project/RustCrypto/PAKEs -[iim-open-image]: http://isitmaintained.com/badge/open/RustCrypto/PAKEs.svg -[iim-open-url]: http://isitmaintained.com/project/RustCrypto/PAKEs +[docs-link]: https://docs.rs/spake2/ +[license-image]: https://img.shields.io/badge/license-Apache2.0/MIT-blue.svg +[rustc-image]: https://img.shields.io/badge/rustc-1.56+-blue.svg +[chat-image]: https://img.shields.io/badge/zulip-join_chat-blue.svg +[chat-link]: https://rustcrypto.zulipchat.com/#narrow/stream/260045-PAKEs +[build-image]: https://github.com/RustCrypto/PAKEs/actions/workflows/spake2.yml/badge.svg +[build-link]: https://github.com/RustCrypto/PAKEs/actions/workflows/spake2.yml + +[//]: # (general links) + +[RustCrypto]: https://github.com/RustCrypto +[SPAKE2]: https://tools.ietf.org/id/draft-irtf-cfrg-spake2-10.html |