passwd 0.3.1

passwd

A D library for UNIX-style (crypt(3)) password hashing.

Features

• Standards-compatible crypt(3) password hashing
• Constant time password checking
• @safe

Supported hashing algorithms:

• MD5-based crypt (algorithm "1")
• Bcrypt (algorithm "2a" and "2b") --- recommended
• SHA256-based crypt (algorithm "5")
• SHA512-based crypt (algorithm "6")

The bcrypt algorithm version 2a is a buggy historical version that was on OpenBSD. It's only different from 2b for passwords that are much longer than practically anyone uses, but OpenBSD bumped the version number with its fix. This implementation has been regression tested against OpenBSD's 2a and 2b.

Usage

import passwd;
import passwd.bcrypt;

// Create salt for bcrypt
auto salt = Bcrypt.genSalt();

// Create a hashed password
auto crypted = "hunter2".crypt(salt);

// Save hashed password to database or password file
// ...

// Test a password at login
auto password_guess = "hunter2";
assert (password_guess.canCryptTo(crypted));

Which algorithm should I use?

If you're asking, just use bcrypt. The other algorithms are for interoperating with existing software.

Bcrypt is the default for user passwords on most BSD systems. Most modern GNU/Linux systems use the SHA algorithms as the default for user passwords.

MD5 crypt(3) is supported by a lot of software, but it's not recommended for new code. Although MD5 is completely broken for things like certificate signing, brute force guessing is still the best known way to reverse an MD5-hashed password. However, brute forcing MD5 is relatively cheap and easy today, so it's not good enough for the weak passwords humans typically use. Just use another algorithm if you can.

Notes on error handling

The library throws the exceptions in passwd.exception.

To help you meet any compliance requirements you might have, error messages don't display any part of the hashed password. If you're using hashes generated by this library, you should only get errors if your password database is corrupted, or something. However, for your own debugging sanity, it's a good idea to catch errors and log some kind of ID (e.g., user ID) you can use to track down the problem.

Installation

passwd can be added to a dub project with dub add passwd.

passwd requires libbsd for portable entropy generation. It's available on many systems. For example, you can install it on Debian with sudo apt-get install libbsd0. If you're not using dub, you'll need to add -L-lbsd to your D compiler command line.

Documentation

You can view the online documentation, or build the docs yourself using dub build --build=docs.

Contributing

New algorithms are welcome as long as they're well standardised for use in crypt(3) implementations (and preferrably already in popular libcs). Please provide thorough test suites, and add links to algorithm specifications.

This library is licensed under the Mozilla Public License version 2.0. Parts of the library might be relicensed for inclusion in D's standard libraries in future. Don't contribute patches if you're not okay with them being relicensed that way.