Crate pwhash

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

bcrypt	Standard *BSD hash.
bsdi_crypt	Enhanced DES-based hash.
error	Error values.
md5_crypt	MD5 based hash.
sha1_crypt	HMAC-SHA1 based hash.
sha256_crypt	SHA-256 based hash.
sha512_crypt	SHA-512 based hash.
unix	Convenience functions for Unix modular hashes.
unix_crypt	Seventh Edition Unix DES-based hash.

Structs

HashSetup

Setup struct for basic hashing customization.

Traits

FindNul	A trait for extracting a NUL-terminated subslice from a slice.
IntoHashSetup	A trait for converting a type into a HashSetup struct.

Type Definitions

Result

Type alias for the Result type.