Crate pwhash

Source
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§

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.