Home

Awesome

Rust DjangoHashers

A Rust port of the password primitives used in Django Project.

Django's django.contrib.auth.models.User class has a few methods to deal with passwords, like set_password() and check_password(); DjangoHashers implements the primitive functions behind those methods. All Django's built-in hashers are supported.

This library was conceived for Django integration, but is not limited to it; you can use the password hash algorithm in any Rust project (or FFI integration), since its security model is already battle-tested.

TL;DR

Content of examples/tldr.rs:

extern crate djangohashers;
use djangohashers::*;

fn main() {
    let encoded = make_password("K2jitmJ3CBfo");
    println!("Hash: {:?}", encoded);
    let is_valid = check_password("K2jitmJ3CBfo", &encoded).unwrap();
    println!("Is valid: {:?}", is_valid);
}

Output:

$ cargo run --quiet --example tldr
Hash: "pbkdf2_sha256$390000$7HRd1YJBZvYj$Rc3BW6f7ss3CShWkULiXI9Rxj7CDdstBeoyCgFFQaK0="
Is valid: true

Installation

Add the dependency to your Cargo.toml:

[dependencies]
djangohashers = "^1.7"

Reference and import:

extern crate djangohashers;

// Everything (it's not much):
use djangohashers::*;

// Or, just what you need:
use djangohashers::{check_password, make_password, Algorithm};

Compiling Features

By default all the hashers are enabled, but you can pick only the hashers that you need to avoid unneeded dependencies.

Fast PBKDF2 Version

Depending on your platform, OS and version of libraries, it is possible that DjangoHashers can be slower than Python/Django's reference implementation. If performance is critical for your case, there is an alternatice implementation: the package fastpbkdf2 uses a C-binding of a library that requires OpenSSL. If ring's implementation of PBKDF2 reaches this level of optiomization, the fastpbkdf2 version will be deprecated.

Installation

Add the dependency to your Cargo.toml declaring the feature:

[dependencies.djangohashers]
version = "^1.7"
features = ["fpbkdf2"]

You need to install OpenSSL and set the environment variable to make it visible to the compiler; this changes depending on the operation system and package manager, for example, in macOS you may need to do something like this:

$ brew install openssl
$ export LIBRARY_PATH="$(brew --prefix openssl)/lib"
$ export CFLAGS="-I$(brew --prefix openssl)/include"
$ cargo ...

For other OSs and package managers, follow the guide of how to install Python’s Cryptography dependencies, that also links against OpenSSL.

Performance

On a Quad-Core Intel Core i7:

MethodEncode or CheckPerformance
Django 4.1.5 on Python 3.11.1189ms100% (baseline)
djangohashers with ring::pbkdf2 (default)145ms76.7% 🐇
djangohashers with fastpbkdf2119ms62.9 🐇

On a Apple M1:

MethodEncode or CheckPerformance
Django 4.1.5 on Python 3.11.165ms100% (baseline)
djangohashers with ring::pbkdf2 (default)38ms58.5% 🐇
djangohashers with fastpbkdf226ms40.0% 🐇

Replicate test above with Docker:

$ docker build -t rs-dj-hashers-profile .
...

$ docker run -t rs-dj-hashers-profile
Hashing time: 65ms (Python 3.11.1, Django 4.1.5).
Hashing time: 38ms (Vanilla PBKDF2).
Hashing time: 26ms (Fast PBKDF2).

Compatibility

DjangoHashers passes all relevant unit tests from Django 1.4 to 5.0 (and beta of 5.1), there is even a line-by-line translation of tests/auth_tests/test_hashers.py.

What is not covered:

Usage

API Documentation, thanks to docs.rs project!

Verifying a Hashed Password

Function signatures:

pub fn check_password(password: &str, encoded: &str) -> Result<bool, HasherError> {}
pub fn check_password_tolerant(password: &str, encoded: &str) -> bool {}

Complete version:

let password = "KRONOS"; // Sent by the user.
let encoded = "pbkdf2_sha256$24000$..."; // Fetched from DB.

match check_password(password, encoded) {
    Ok(valid) => {
        if valid {
            // Log the user in.
        } else {
            // Ask the user to try again.
        }
    }
    Err(error) => {
        // Deal with the error.
    }
}

Possible Errors:

If you want to automatically assume all errors as "invalid password", there is a shortcut for that:

if check_password_tolerant(password, encoded) {
	// Log the user in.
} else {
	// Ask the user to try again.
}

Generating a Hashed Password

Function signatures:

pub fn make_password(password: &str) -> String {}
pub fn make_password_with_algorithm(password: &str, algorithm: Algorithm) -> String {}
pub fn make_password_with_settings(password: &str, salt: &str, algorithm: Algorithm) -> String {}

Available algorithms:

The algorithms follow the same Django naming model, minus the PasswordHasher suffix.

Using default settings (PBKDF2 algorithm, random salt):

let encoded = make_password("KRONOS");
// Returns something like:
// pbkdf2_sha256$24000$go9s3b1y1BTe$Pksk4EptJ84KDnI7ciocmhzFAb5lFoFwd6qlPOwwW4Q=

Using a defined algorithm (random salt):

let encoded = make_password_with_algorithm("KRONOS", Algorithm::BCryptSHA256);
// Returns something like:
// bcrypt_sha256$$2b$12$e5C3zfswn.CowOBbbb7ngeYbxKzJePCDHwo8AMr/SZeZCoGrk7oue

Using a defined algorithm and salt (not recommended, use it only for debug):

let encoded = make_password_with_settings("KRONOS", "seasalt", Algorithm::PBKDF2SHA1);
// Returns exactly this (remember, the salt is fixed!):
// pbkdf2_sha1$24000$seasalt$F+kiWNHXbMBcwgxsvSKFCWHnZZ0=

Warning: make_password_with_settings and make_password_core will both panic if salt is not only letters and numbers (^[A-Za-z0-9]*$).

Generating a Hashed Password based on a Django version

Django versions can have different number of iterations for hashers based on PBKDF2 and BCrypt algorithms; this abstraction makes possible to generate a password with the same number of iterations used in that versions.

use djangohashers::{Django, DjangoVersion};

let django = Django {version: DjangoVersion::V1_8};  // Django 1.8.
let encoded = django.make_password("KRONOS");
// Returns something like:
// pbkdf2_sha256$20000$u0C1E8jrnAYx$7KIo/fAuBJpswQyL7pTxO06ccrSjGdIe7iSqzdVub1w=
//               |||||
// ...notice the 20000 iterations, used in Django 1.8.

Available versions:

Verifying a Hash Format (pre-crypto)

Function signature:

pub fn is_password_usable(encoded: &str) -> bool {}

You can check if the password hash is properly formatted before running the expensive cryto stuff:

let encoded = "pbkdf2_sha256$24000$..."; // Fetched from DB.

if is_password_usable(encoded) {
    // Go ahead.
} else {
    // Check your database or report an issue.
}

Contributing

License

Rust DjangoHashers is released under the 3-Clause BSD License.

tl;dr: "free to use as long as you credit me".