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
 94
 95
 96
 97
 98
 99
100
101
102
103

//! # Passwords
//! This crate provides useful tools to generate multiple readable passwords, as well as analyze and score them.
//!
//! ## Generating Passwords
//!
//! `PasswordGenerator` can be used for generating passwords which consist optional numbers, lowercase letters, uppercase letters and symbols.
//!
//! ```
//! extern crate passwords;
//!
//! use passwords::PasswordGenerator;
//!
//! let pg = PasswordGenerator {
//!        length: 8,
//!        numbers: true,
//!        lowercase_letters: true,
//!        uppercase_letters: true,
//!        symbols: true,
//!        strict: true,
//!    };
//!
//! println!("{}", pg.generate_one().unwrap());
//! println!("{:?}", pg.generate(5).unwrap());
//! ```
//!
//! ## Hashing
//!
//! To enable hashing functions, you need to enable the **crypto** feature.
//!
//! ```toml
//! [dependencies.passwords]
//! version = "*"
//! features = ["crypto"]
//! ```
//!
//! Then, `bcrypt`, `identify_bcrypt` and `gen_salt` functions are available.
//!
//! ```rust,ignore
//! extern crate passwords;
//!
//! let salt = passwords::gen_salt();
//! let hashed = passwords::bcrypt(10, &salt, "password").unwrap();
//! assert!(passwords::identify_bcrypt(10, &salt, "password", &hashed).unwrap());
//! ```
//!
//! ## Analyzer
//!
//! The `analyze` function is `analyzer` module can be used to create a `AnalyzedPassword` instance which contains some information about the input password.
//!
//! Typically, we don't want our readable password to contain control characters like BS, LF, CR, etc.
//! Before the analyzer analyzes a password, it filters the password in order to remove its control characters. And after analyzing, the analyzer will return the filtered password.
//! Therefore, you can use this analyzer as a password guard before you store the input password (or generally hash it first and then store) to your database.
//!
//! ```
//! extern crate passwords;
//!
//! use passwords::analyzer;
//!
//! let password = "ZYX[$BCkQB中文}%A_3456]  H(\rg";
//!
//! let analyzed = analyzer::analyze(password);
//!
//! assert_eq!("ZYX[$BCkQB中文}%A_3456]  H(g", analyzed.password()); // "\r" was filtered
//! assert_eq!(26, analyzed.length()); // Characters' length, instead of that of UTF-8 bytes
//! assert_eq!(2, analyzed.spaces_count()); // Two spaces between "]" and "H"
//! assert_eq!(4, analyzed.numbers_count()); // Numbers are "3456"
//! assert_eq!(2, analyzed.lowercase_letters_count()); // Lowercase letters are "k" and "g"
//! assert_eq!(9, analyzed.uppercase_letters_count()); // Uppercase letters are "ZYX", "BC", "QB", "A" and "H"
//! assert_eq!(7, analyzed.symbols_count()); // Symbols are "[$", "}%", "_", "]" and "("
//! assert_eq!(2, analyzed.other_characters_count()); // Other characters are "中文". These characters are usually not included on the rainbow table.
//! assert_eq!(2, analyzed.consecutive_count()); // Consecutive repeated characters are "  " (two spaces)
//! assert_eq!(2, analyzed.non_consecutive_count()); // Non-consecutive repeated characters are "B" (appears twice)
//! assert_eq!(7, analyzed.progressive_count()); // Progressive characters are "ZYX" and "3456". "BC" is not counted, because its length is only 2, not three or more.
//! ```
//!
//! You can also check whether a password is too simple and dangerous to use, by looking up a *common passwords table*.
//! If you want to do that you need to enable the **common-password** feature.
//!
//! ```toml
//! [dependencies.passwords]
//! version = "*"
//! features = ["common-password"]
//! ```
//! Then, the `is_common_password` function in `analyzer` module and the `is_common` method of a `AnalyzedPassword` instance are available.
//!
//! You should notice that after you enable the **common-password** feature, the time for compiling increases dramatically, because the *common passwords table* will be compiled into the executable binary file.

#[macro_use]
extern crate lazy_static;

mod generator;
/// Analyze passwords.
pub mod analyzer;
mod hash;

pub use generator::PasswordGenerator;
pub use analyzer::AnalyzedPassword;
#[cfg(feature = "crypto")]
pub use hash::bcrypt;
#[cfg(feature = "crypto")]
pub use hash::identify_bcrypt;
#[cfg(feature = "crypto")]
pub use hash::gen_salt;