Crate passwors [−] [src]

Passwors is a simple password handling library that utilises Rust's type system to enfore better password handling. Use it as a basic building block for more complex authentication systems.

extern crate passwors;

use passwors::*;

fn main() {
    // ... some code...

    // Read a user's password into a clear text password
    // to generate and compare hashes.
    let pw      = ClearTextPassword::from_string(some_password_source).unwrap();
    let salt    = HashSalt::new().unwrap(); // You should grab this from your database.
    let a2hash  = Argon2PasswordHasher::default();
    let pw_hash = pw.hash(&a2hash, &salt);

    // Grab the password hash to compare from your database.
    // You should always calculate password hashes, even if
    // the user who wants to log in doesn't exist.
    assert_eq!(pw_hash, stored_hash, "Login failed!");

    // ... more code...
}

The Types

There are four types involved when it comes to handling passwords.

ClearTextPassword is what you get from a user's inputs. This is a secret token that only its creator should know.
HashedPassword is what you use to validate one's identity. It is there to be compared, stored, read, and what not.
HashSalt is a blob of random data, generated using strong CSPRNGs only. It should be uniquely generated for each of your users and is used to randomise the outcome of hashing a clear text password.
PasswordHasher is a trait for... well... password hashers. They are the only unsafe component here, as they are the only ones that are able to read a user's clear text password.

Clear Text Password

As this is a secret token, this type does not leak any kind of information to anyone but password hashers.

You cannot query the clear text password's length.
You cannot read the clear text password data.
You cannot modify the clear text password.
You cannot compare clear text passwords.
You cannot duplicate clear text passwords.
Additionally, on drop, the clear text password's memory will be zero-filled.

This is what you compare, store into databases, look at, or whatever else. A hashed password is created from a clear text password by giving it a hash salt and a password hasher. Ideally, it is impossible to guess a clear text password by looking at its hash.

Hash Salt

A hash salt should be unique for all users, which is why they are only created using a CSPRNG. You can safely move them around or store them into a data base. But as they should be unique, you cannot clone or copy them.

Of course, if you really wanted to have duplicate salts, you could just serialise the same salt for multiple user database entries.

Password Hasher

They are the only ones being able to read clear text passwords. Additionally, the whole security depends on how strong the hash function of choice is. You could, for example, hash the user's passwords using good ol' MD5, or you could use scrypt instead.

Don't forget to store a hasher's configuration next to the user's hashed password in your database, so you can always upgrade your server's hasher settings to fit today's increased computational password cracking power.

Structs

Argon2PasswordHasher	A wrapper around `Argon2` from `argon2rs` that ensures that the variant `Argon2i` is chosen.
Argon2Settings	A serialisable builder for Argon2 password hashers.
ClearTextPassword	A clear text password is a fixed-sized buffer of raw password bytes data.
HashSalt	A salt for password hashing.
HashedPassword	A hashed password.

Enums

ParamErr

Constants

CLEAR_TEXT_LEN	The maximum length of the clear text password buffer.
HASHED_PASSWORD_LEN	The length of a hashed password in bytes.
HASH_SALT_LEN	The length of a hash salt in bytes.
MIN_CLEAR_TEXT_LEN	All clear text passwords must have at least this size in bytes.

Traits

PasswordHasher

Any password hasher should implement this trait.