dovehash/README.html

Library for working with Dovecot password hashes

<h1>dovehash</h1>

<p>Node.JS library for working with Dovecot password hashes</p>

<p>Written by Vladimir Neverov <a href="m&#97;&#105;&#108;&#x74;&#111;:&#115;&#97;&#x6E;&#x67;&#x75;&#x69;&#x6E;&#x69;&#64;&#x67;&#109;&#x61;&#105;l&#46;&#x63;&#111;&#109;">&#115;&#97;&#x6E;&#x67;&#x75;&#x69;&#x6E;&#x69;&#64;&#x67;&#109;&#x61;&#105;l&#46;&#x63;&#111;&#109;</a> in 2015</p>

<p>Homepage: <a href="https://github.com/vne/dovehash/wiki">https://github.com/vne/dovehash/wiki</a></p>

<h2>Synopsis</h2>

<p>Dovecot mail server uses its own special data format to store hashed passwords in databases. This is covered in details
in <a href="http://wiki2.dovecot.org/Authentication/PasswordSchemes">Dovecot wiki</a>. 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.</p>

<p>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.</p>

<p>Simple MD5 is <strong>NOT</strong> supported due to weird calculation scheme used in Dovecot (see password_generate_md5_crypt function in Dovecot sources at <a href="http://hg.dovecot.org/dovecot-2.2/file/3d612ade5d75/src/auth/password-scheme-md5crypt.c">src/auth/password-scheme-md5crypt.c</a> for more).</p>

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

<p>Library makes use of Node.JS Buffer class and can not be used in browser without some helper library (e.g., <a href="https://github.com/feross/buffer">this one</a>).
This behavior is not tested yet.</p>

<h2>Usage</h2>

<p>First, you should require the library</p>

<pre><code>var Dovehash = require('dovehash');
</code></pre>

<p>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:</p>

<pre><code>var passwordsMatch = Dovehash.equals(hashedPassword, userSuppliedPassword);
</code></pre>

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

<pre><code>var encoded = Dovehash.encode('SSHA', yourPlainPassword, salt);
</code></pre>

<p>Note that currently salt is not generated automatically if nothing is supplied.</p>

<p>Finally, you can create a Dovehash instance for hashed password:</p>

<pre><code>var dh = new Dovehash(hashedPassword);
console.log(dh.toJSON());
</code></pre>

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

<h2>Testing</h2>

<p>Some examples of library usage can be found in <strong>test.js</strong> file. To run tests you will
need <a href="http://visionmedia.github.io/mocha/">Mocha</a>, the tests themselves use built-in
NodeJS <a href="http://nodejs.org/api/assert.html">assert</a> module</p>