Secure Password Storage
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
logos
repository/de/qaware/heimdall
src
.gitignore
.travis.yml
CHANGES.md
CONTRIBUTORS.md
LICENSE.txt
README.md
pom.xml

README.md

Heimdall Logo

Heimdall - Secure Password Hashing

Build Status License Download

This library implements a secure and upgradeable password hashing mechanism. See this blog post for details.

Why not just use PBKDF2, scrypt, bcrypt, etc.?

Actually, this library uses (some of) these algorithms. But it makes it easier for you: no need to worry about iterations, salt generation and the same. And if a flaw is discovered in one of the algorithms, the library makes sure that the hashes in your database are automatically updated to a secure format (provided you use the pattern as shown in the usage block down below).

Usage

Dependencies

The JARs are available via JCenter and Maven Central. If you are using Maven to build your project, add the following to the pom.xml file:

<dependencies>
    <dependency>
        <groupId>de.qaware.heimdall</groupId>
        <artifactId>heimdall</artifactId>
        <version>1.5.1</version>
    </dependency>
</dependencies>

In case you are using Gradle to build your project, add the following to the build.gradle file:

repositories {
    jcenter()    
    mavenCentral()
}

dependencies {
	compile 'de.qaware:heimdall:1.5.1'
}

Create a hash

    Password password = PasswordFactory.create();

    try(SecureCharArray cleartext = new SecureCharArray(...)) { // Read cleartext password from user
        String hash = password.hash(cleartext);
        // Persist the hash in a database etc...
    }

Verify the hash

    Password password = PasswordFactory.create();

    String hash = ... // Load hash from persistent storage
    try(SecureCharArray cleartext = new SecureCharArray(...)) { // Read cleartext password from user
        if (password.verify(cleartext, hash)) {
            if (password.needsRehash(hash)) { // Check if the hash uses an old hash algorithm, insecure parameters, etc.
                String newHash = password.hash(cleartext);
                // Persist the new hash in a database etc...
            }

            // Password is correct, proceed...
        } else {
            // Password is incorrect
        }
    }

Technical details

By default this library uses the PBKDF2 SHA-1 HMAC (PBKDF2WithHmacSHA1) with 20000 iterations and 192 bit (24 byte) of salt.

Useful resources

Maintainer

Moritz Kammerer (@phxql), moritz.kammerer@qaware.de

Contributors

See the list of contributors.

License

This software is provided under the MIT open source license, read the LICENSE.txt file for details.