dovehash

    0.0.5 • Public • Published

    dovehash

    Node.JS library for working with Dovecot password hashes

    Written by Vladimir Neverov sanguini@gmail.com 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

    Install

    npm i dovehash

    DownloadsWeekly Downloads

    6

    Version

    0.0.5

    License

    MIT

    Last publish

    Collaborators

    • vne