Expand description
A collection of password hashing and verification routines.
For the summary of supported algorithms and recommendations, see Summary. Every algorithm has its own module; alphabetical list is in the Modules section.
§Getting Started
Add the following to the [dependencies]
section of your Cargo.toml
:
pwhash = "1"
§Examples
To verify a password hashed with a known algorithm:
use pwhash::bcrypt;
let h = "$2y$05$bvIG6Nmid91Mu9RcmmWZfO\
5HJIMCT8riNW0hEp8f6/FuA2/mHZFpe";
assert_eq!(bcrypt::verify("password", h), true);
To hash a password using default parameters:
use pwhash::bcrypt;
let h = bcrypt::hash("password").unwrap();
To verify a password known to be in one of Unix modular hash formats:
use pwhash::unix;
let h = "$2y$05$bvIG6Nmid91Mu9RcmmWZfO\
5HJIMCT8riNW0hEp8f6/FuA2/mHZFpe";
assert_eq!(unix::verify("password", h), true);
§Summary
Currently, there are implementations of seven algorithms, which should cover anything one might find as a system-wide hash on a free Unix-like OS: bcrypt, SHA-512, SHA-256, HMAC-SHA1, MD5, BSDi crypt, and DES crypt. The list is ordered roughly by security, with the most secure algorithms first. The first two are recommended for new passwords.
Each algorithm is implemented in its own module, and offers three ways of using it:
-
The
verify
function checks whether the provided hash corresponds to a password. -
The
hash
function hashes a password using the default parameters for the algorithm. -
The
hash_with
function allows the caller to customize the hashing parameters.
Customization can always be accomplished by passing a &str
with encoded
parameters (in the appropriate hash format) to hash_with
. All algorithms
except DES crypt accept a HashSetup
struct as a means of customization,
while bcrypt also has its own setup structure (see the module documenation.)
The unix module provides a crypt(3)-compatible function and a
verify
which uses it to automatically recognize the algorithm of the
provided hash.
Modules§
- Standard *BSD hash.
- Enhanced DES-based hash.
- Error values.
- MD5 based hash.
- HMAC-SHA1 based hash.
- SHA-256 based hash.
- SHA-512 based hash.
- Convenience functions for Unix modular hashes.
- Seventh Edition Unix DES-based hash.
Structs§
- Setup struct for basic hashing customization.
Traits§
- A trait for extracting a NUL-terminated subslice from a slice.
- A trait for converting a type into a
HashSetup
struct.
Type Aliases§
- Type alias for the Result type.