JarCastingBCrypt based Key Derivation Function (BKDF)
The aim of this project is to improve on the cryptographic primitive BCrypt with providing well defined modes of operation which includes:
- Improved password hashing function
- Protocol to upgrade password hashes offline
- Fully functional key derivation function
All this is achieved by only adding HKDF as additional building block.
The code is compiled with target Java 7 to be compatible with most Android versions as well as normal Java applications.
Note, that this project is ongoing research and may not be ready for prime-time yet as it requires more feedback from the cryptographic community.
Quickstart
Add dependency to your pom.xml (check latest release):
<dependency>
<groupId>at.favre.lib</groupId>
<artifactId>bkdf</artifactId>
<version>{latest-version}</version>
</dependency>
A very simple example using the password hasher:
PasswordHasher hasher = BKDF.createPasswordHasher();
char[] pw = "secret".toCharArray();
int costFactor = 6; // same as with bcrypt 4-31 doubling the iterations every increase
//returns base64 url-safe encoded string
String hash = hasher.hash(pw, costFactor);
PasswordHashVerifier verifier = BKDF.createPasswordHashVerifier();
boolean verified = verifier.verify(pw, hash);
Full Example
The BKDF protocol supports 3 use-cases:
- password hash with key stretching feature for storage
- upgrade of previously generated password hashes offline without the user password
- key derivation function with key strechting feature to generate high quality keying material (for e.g. secret keys)
Password Hash
A password hash is used to generate a hash from a user-password which can't easily be used to calculate the used password without brute-forcing. An important feature of password hashes are, that they are slow, so it makes it harder (or infeasible) for an attacker to brute force. This property is also called "key-stretching". Well known password hashes are PBKDF2, scrypt and Argon2.
// provide different version of hash config and provide own impl of secure random for salt gen
PasswordHasher hasher = BKDF.createPasswordHasher(Version.HKDF_HMAC512, new SecureRandom());
char[] pw = "secret".toCharArray();
HashData hashData = hasher.hashRaw("secret".toCharArray(), 4);
// get the raw, non-encoded hash message
byte[] hashMsgAsBlob = hashData.getAsBlobMessageFormat();
// get the base64 url-safe encoded string
String hashAsBase64 = hashData.getAsEncodedMessageFormat();
PasswordHashVerifier verifier = BKDF.createPasswordHashVerifier();
boolean verified = verifier.verify(pw, hashData);
Password Hash Upgrade
BCrypt does not support upgrading the strength of the password hash without the user password. Having legacy password hashes in a DB, the need may arise to improve them, because CPU performance increased of the last couple of years. With this feature a password can be upgraded offline by basically chaining multiple hashes together.
This mode will chain a specific new hash with given cost factor:
char[] pw = "secret".toCharArray();
// hash with cost factor 5
String hash = BKDF.createPasswordHasher().hash(pw, 5);
PasswordHashUpgrader upgrader = new PasswordHashUpgrader.Default(new SecureRandom());
// upgrade hash with an additional cost factor (ie. now needs to calculate 5 + 6 = 32 + 64 = 96 iterations
CompoundHashData compoundHashData = upgrader.upgradePasswordHashWith(6, hash);
// create base64 url-safe encoded msg and verify
boolean verified = BKDF.createPasswordHashVerifier().verify(pw, compoundHashData.getAsEncodedMessageFormat());
Another mode will take a target cost factor and calculate the required hashes to achieve it
char[] pw = "secret".toCharArray();
// hash with cost factor 5
String hash = BKDF.createPasswordHasher().hash(pw, 5);
PasswordHashUpgrader upgrader = new PasswordHashUpgrader.Default(new SecureRandom());
// upgrade to have exactly cost factor 8 (aka 2^8 = 256 iterations)
CompoundHashData compoundHashData = upgrader.upgradePasswordHashTo(8, hash);
// create base64 url-safe encoded msg and verify
boolean verified = BKDF.createPasswordHashVerifier().verify(pw, compoundHashData.getAsEncodedMessageFormat());
Key Derivation Function
It might be useful to have a primitive that generates high-quality key material for e.g. symmetric encryption and not password hashes.
This example creates an AES key from a user password:
char[] pw = "secret".toCharArray();
byte[] salt = Bytes.random(16).array();
int costFactor = 5;
KeyDerivationFunction kdf = new KeyDerivationFunction.Default(Version.HKDF_HMAC512);
byte[] aesKey = kdf.derive(salt, pw, costFactor, Bytes.from("aes-key").array(), 16);
SecretKey aesSecretKey = new SecretKeySpec(aesKey, "AES");
To generate multiple keys, use the following example, so you are not required to generate the internal bcrypt hash for every key:
// a entropy source used in your current protocol
byte[] ikm = Bytes.random(12).array();
byte[] salt = Bytes.random(16).array();
int costFactor = 5;
KeyDerivationFunction kdf = new KeyDerivationFunction.Default(Version.HKDF_HMAC512);
List<KeyDerivationFunction.KdfConfig> config = Arrays.asList(
new KeyDerivationFunction.KdfConfig(Bytes.from("aes-key").array(), 16),
new KeyDerivationFunction.KdfConfig(Bytes.from("mac-key").array(), 32)
);
List<byte[]> keys = kdf.deriveMulti(salt, ikm, costFactor, config);
SecretKey aesSecretKey = new SecretKeySpec(keys.get(0), "AES");
SecretKey macSecretKey = new SecretKeySpec(keys.get(1), "HmacSHA512");
Description
In the following the details of each of the protocols are discussed.
In the example the following functions are used:
bcrypt(cost_factor {4-31}, user_pw, [16-byte-salt])
hkdf_extract(salt, input_key_material)
hkdf_expand(output_key_material, info_param, out_length_byte)
The HMAC used by HKDF is defined by the used hash version, currently only HMAC-SHA512 is supported.
Password Hash Protocol
Step 1: Extract User Password
First create uniformly distributed entropy byte string with through HKDF "extract" from user password. Convert the user password to a byte array using UTF-8 encoding. Use an empty byte array as salt with the length of the underyling hash output length (aka HMAC-SHA512 == 64 byte)
utf8PwBytes = user_password.getUtf8Bytes()
extractedPw = hkdf_extract(empty_byte_array, utf8PwBytes)
Step 2: Stretch with BCrypt
tbd.
Password Upgrade Protocol
tbd.
KDF Protocol
tbd.
Download
The artifacts are deployed to jcenter and Maven Central.
Maven
Add dependency to your pom.xml:
<dependency>
<groupId>at.favre.lib</groupId>
<artifactId>bkdf</artifactId>
<version>{latest-version}</version>
</dependency>
Gradle
Add to your build.gradle module dependencies:
compile group: 'at.favre.lib', name: 'bkdf', version: '{latest-version}'
Local Jar
Security Relevant Information
OWASP Dependency Check
This project uses the OWASP Dependency-Check which is a utility that identifies project dependencies and checks if there are any known, publicly disclosed, vulnerabilities against a NIST database. The build will fail if any issue is found.
Digital Signatures
Signed Jar
The provided JARs in the Github release page are signed with my private key:
CN=Patrick Favre-Bulle, OU=Private, O=PF Github Open Source, L=Vienna, ST=Vienna, C=AT
Validity: Thu Sep 07 16:40:57 SGT 2017 to: Fri Feb 10 16:40:57 SGT 2034
SHA1: 06:DE:F2:C5:F7:BC:0C:11:ED:35:E2:0F:B1:9F:78:99:0F:BE:43:C4
SHA256: 2B:65:33:B0:1C:0D:2A:69:4E:2D:53:8F:29:D5:6C:D6:87:AF:06:42:1F:1A:EE:B3:3C:E0:6D:0B:65:A1:AA:88
Use the jarsigner tool (found in your $JAVA_HOME/bin folder) folder to verify.
Signed Commits
All tags and commits by me are signed with git with my private key:
GPG key ID: 4FDF85343912A3AB
Fingerprint: 2FB392FB05158589B767960C4FDF85343912A3AB
Build
Jar Sign
If you want to jar sign you need to provide a file keystore.jks in the root folder with the correct credentials set in environment variables ( OPENSOURCE_PROJECTS_KS_PW and OPENSOURCE_PROJECTS_KEY_PW); alias is set as pfopensource.
If you want to skip jar signing just change the skip configuration in the pom.xml jar sign plugin to true:
<skip>true</skip>
Build with Maven
Use the Maven wrapper to create a jar including all dependencies
mvnw clean install
Checkstyle Config File
This project uses my common-parent which centralized a lot of the plugin versions aswell as providing the checkstyle config rules. Specifically they are maintained in checkstyle-config. Locally the files will be copied after you mvnw install into your target folder and is called target/checkstyle-checker.xml. So if you use a plugin for your IDE, use this file as your local configuration.
Tech Stack
- Java 7 (+ errorprone static analyzer)
- Maven
Related Libraries
- BCyrpt Password Hash Function (Java)
- HKDF [RFC5869] Two-Step KDF (Java)
- Single Step KDF [NIST SP 800-56C] (Java)
License
Copyright 2018 Patrick Favre-Bulle
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.