dovehash

Node.JS library for working with Dovecot password hashes

Written by Vladimir Neverov [e-mail] in 2015

Homepage: https://github.com/vne/dovehash/wiki

Synopsis

Dovecot mail server uses its own special data format to store hashed passwords in databases. This is covered in details in Dovecot wiki. This library is intended to support this kind of password encoding in Node.JS applications, because it is convenient to have one common password storage format.

As for now, Dovehash works only with a subset of hashing schemes supported by Dovecot: PLAIN, CLEARTEXT, SHA, SHA1, SHA256, SHA512, SMD5, SSHA, SSHA256 and SSHA512. Pull requests are welcomed. Support for more hashing schemes is planned.

Simple MD5 is NOT supported due to weird calculation scheme used in Dovecot (see password_generate_md5_crypt function in Dovecot sources at src/auth/password-scheme-md5crypt.c for more).

Both base64 and hex encodings are supported, base64 is the default (as it is in Dovecot).

Library makes use of Node.JS Buffer class and can not be used in browser without some helper library (e.g., this one). This behavior is not tested yet.

Usage

First, you should require the library

var Dovehash = require('dovehash');

Then, if you have some hashed and, probably, salted password in Dovecot style (e.g. "{SSHA}PTggDCOUPEVj5h7bZjhxfKWQBpey47nF") and a plain password, supplied by user, (e.g. "abcdef") you can easily check them for equivalence:

var passwordsMatch = Dovehash.equal(hashedPassword, userSuppliedPassword);

If you have a plain password and want to encode it using one of the supported schemes:

var encoded = Dovehash.encode('SSHA', yourPlainPassword, salt);

If salt is not supplied, it is generated automatically. Dovehash.encode returns Dovehash instance that can be stringified to Dovecot-style hash via .toString or .inspect call.

Finally, you can create a Dovehash instance for hashed password:

var dh = new Dovehash(hashedPassword);
console.log(dh.toJSON());

This will parse hashed password and give you access to hashing algorithm, encoding, password hash and salt.

API

You can create a Dovehash instance for hashed password (constructor may throw exceptions):

var dh = new Dovehash(hashedPassword);

This instance will have the following methods:

• equals(clearTextPassword) - calculate appropriate hash for clearTextPassword and compare with the hashed one. Returns either true or false.
• toJSON() - get hash properties as JSON (currently: input, scheme, encoding, salt, password, where input is the original string and password is hex-encoded hash)
• toString() - get Dovecot-style hash
• inspect() - save as toString()

Dovehash also has several static methods:

• Dovehash.equal(hashed, clearText) - compare clearText to hashed, catch exceptions and return false if anything is caught. Returns either true or false.
• encode(scheme, clearText, salt) - encode clearText to scheme with salt. Returns Dovehash instance.
• getSalt(hashed) - parse hashed password and return salt if there is any. Returns Buffer.

Errors

Dovehash constructor throws exceptions if something is wrong. Go catch them :)

Testing

Some examples of library usage can be found in test.js file. To run tests you will need Mocha, the tests themselves use built-in NodeJS assert module