argon2/lib.rs
1// Copyright (c) 2017 Martijn Rijkeboer <mrr@sru-systems.com>
2//
3// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
4// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
5// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
6// option. This file may not be copied, modified, or distributed
7// except according to those terms.
8
9//! Library for hashing passwords using
10//! [Argon2](https://github.com/P-H-C/phc-winner-argon2), the password-hashing
11//! function that won the
12//! [Password Hashing Competition (PHC)](https://password-hashing.net).
13//!
14//! # Usage
15//!
16//! To use this crate, add the following to your Cargo.toml:
17//!
18//! ```toml
19//! [dependencies]
20//! rust-argon2 = "2.1"
21//! ```
22//!
23//! And the following to your crate root:
24//!
25//! ```rust
26//! extern crate argon2;
27//! ```
28//!
29//! # Examples
30//!
31//! Create a password hash using the defaults and verify it:
32//!
33//! ```rust
34//! use argon2::{self, Config};
35//!
36//! let password = b"password";
37//! let salt = b"randomsalt";
38//! let config = Config::default();
39//! let hash = argon2::hash_encoded(password, salt, &config).unwrap();
40//! let matches = argon2::verify_encoded(&hash, password).unwrap();
41//! assert!(matches);
42//! ```
43//!
44//! Create a password hash with custom settings and verify it:
45//!
46//! ```rust
47//! use argon2::{self, Config, Variant, Version};
48//!
49//! let password = b"password";
50//! let salt = b"othersalt";
51//! let config = Config {
52//! variant: Variant::Argon2i,
53//! version: Version::Version13,
54//! mem_cost: 65536,
55//! time_cost: 10,
56//! lanes: 4,
57//! secret: &[],
58//! ad: &[],
59//! hash_length: 32
60//! };
61//! let hash = argon2::hash_encoded(password, salt, &config).unwrap();
62//! let matches = argon2::verify_encoded(&hash, password).unwrap();
63//! assert!(matches);
64//! ```
65//!
66//! # Limitations
67//!
68//! This crate has the same limitation as the `blake2-rfc` crate that it uses.
69//! It does not attempt to clear potentially sensitive data from its work
70//! memory. To do so correctly without a heavy performance penalty would
71//! require help from the compiler. It's better to not attempt to do so than to
72//! present a false assurance.
73//!
74//! This version uses the standard implementation and does not yet implement
75//! optimizations. Therefore, it is not the fastest implementation available.
76
77mod argon2;
78mod block;
79mod common;
80mod config;
81mod context;
82mod core;
83mod decoded;
84mod encoding;
85mod error;
86mod memory;
87mod result;
88mod variant;
89mod version;
90
91pub use crate::argon2::*;
92pub use crate::config::Config;
93pub use crate::error::Error;
94pub use crate::result::Result;
95pub use crate::variant::Variant;
96pub use crate::version::Version;