BoxLang 🚀 A New JVM Dynamic Language Learn More...

BCrypt

v3.1.0+4 Modules

BCrypt Module for the ColdBox Framework Build Status

BCrypt's primary usage would be for the secure hashing of passwords. The hashing method provides a high level of security, but also makes it too slow use as a simple digest. It is also not reversible, and therefore is not suitable for encrypting transmission data.

More information about BCrypt:

Installation

Install the module via Commandbox, which will ensure all dependencies are installed as well:

box install bcrypt

Requirements

  • ColdBox Framework 5.0+
  • cbjavaloader module ( automatically installed as a dependency by Forgebox )

BCrypt.jar

A compiled version (0.4) of jBCrypt is listed as a dependency for the test harness. You can update the version by following the steps below.

  1. Visit http://www.mindrot.org/projects/jBCrypt/.
  2. Copy the link to the latest version
  3. Update the test-harness/box.json dependency with the correct version information
  4. Run box install from within the test-harness directory
  5. Execute ant -f test-harness/resources/jBCrypt-[version number]/build.xml and move the generated jbcrypt.jar file to models/lib

Usage

BCrypt WireBox Mapping

This module registers a wirebox mapping to the Bcrypt singleton, BCrypt@BCrypt, which you may inject or instantiate in your componets:

// Long Format
property name="BCrypt" inject="BCrypt@BCrypt";

// Module Alias Shortcut
property name="BCrypt" inject="@BCrypt";

or via getInstance() ( a ColdBox framework supertype method ) inside your handlers, views, interceptors, etc.

getInstance( "BCrypt@BCrypt" )
getInstance( "@BCrypt" )

BCrypt Mixins

We have also created three mixin helpers that will be injected to all your handlers, interceptors, layouts and views: bcryptHash(), bcryptCheck(), bcryptSalt()

/**
 * Hashes an incoming input string according to work factor and salt
 *
 * @password The input password to encrypt
 * @workFactor Optional work factor
 *
 * @return The bcrypted password
 */
string function bcryptHash(
	required string password,
	workFactor,
	salt
)

/**
 * Check if the incoming candidate is the same as a bcrypthash, usually the best check for comparing them.
 *
 * @candidate The plain text string to compare against the encrypted hash
 * @bCryptHash The bCrypt hash to compare it to
 *
 * @return True - if the match, false if they dont!
 */
boolean function bcryptCheck( required string candidate, required string bCryptHash )

/**
 * Generates a salt for you.
 *
 * @workFactor The workfactor to use for the salt, by default we use the one in the settings
 */
string function bcryptSalt( workFactor )

Generating a password hash

The hashed password should be persisted so candidate passwords (submitted from login) can be checked against.

var hashedPassword = getInstance( "BCrypt" ).hashPassword( plaintextPassword );

Checking a password hash

The plaintextPasswordCandidate is the password the user submits for authentication. The hashed password is retrieved for the user being authenticated.

var isSamePassword = getInstance( "BCrypt" ).checkPassword( plaintextPasswordCandidate, hashedPassword );

Using a Custom Salt

Internally we generate a salt for you according to the default work factor. You can however, alter this and pass in your own salt:

var hashedPassword = getInstance( "BCrypt" ).hashPassword( 
	password : plaintextPassword,
	salt : mySalt
);

Configuring WorkFactor

WorkFactor is an input to BCrypt that controls how long (generally) it takes to hash a password. The module sets a default value of 12. You should experiment to find the optimal value for your environment. It should take as long as possible to hash a password without being burdensome to your users on login. Half a second to a full second is generally a good target to shoot for.

You can also set the workFactor on a per-call basis by passing it in as a second parameter to the hashPassword method like so:

var hashedPassword = getInstance( "@BCrypt" ).hashPassword( plaintextPassword, 7 );

BCrypt Settings

You may override the default work factor by creating a BCrypt settings struct in your ColdBox.cfc under the moduleSettings struct:

moduleSettings = {
	bcrypt = {
		workFactor = 15
	}
};

Copyright Since 2005 ColdBox Framework by Luis Majano and Ortus Solutions, Corp www.coldbox.org | www.luismajano.com | www.ortussolutions.com


HONOR GOES TO GOD ABOVE ALL

Because of His grace, this project exists. If you don't like this, then don't read it, its not for you.

"Therefore being justified by faith, we have peace with God through our Lord Jesus Christ: By whom also we have access by faith into this grace wherein we stand, and rejoice in hope of the glory of God. And not only so, but we glory in tribulations also: knowing that tribulation worketh patience; And patience, experience; and experience, hope: And hope maketh not ashamed; because the love of God is shed abroad in our hearts by the Holy Ghost which is given unto us. ." Romans 5:5

THE DAILY BREAD

"I am the way, and the truth, and the life; no one comes to the Father, but by me (JESUS)" Jn 14:1-12

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.


[3.1.0] => 2022-SEP-06

Added

  • Compatibility with ColdBox and CommandBox modules
  • New module template updates
  • Github actions build process

[3.0.1] => 2020-NOV-25

Fixed


[3.0.0] => 2020-NOV-1

Added

  • Added three new helper mixins for easy usage : bcryptHash(), bcryptCheck(), bcryptSalt()
  • New method to generate bcrypt salts: generateSalt( workFactor = default ): bcryptSalt()
  • Ability to pass in a custom salt argument via the hashPassword( input, workFactor, salt ) method
  • compatiblity : New moduleSettings configuration as per ColdBox 5+ instead of parsing parent settings
  • Updated to newest module layout
  • Lots of docs for methods
  • Upgraded tests to ColdBox 6+

Fixed

  • Upgraded to cbJavaloader 2.x due to security issues in 1.x

Removed

  • ACF11 Support
  • Lucee 4.5 Support

[2.5.0] => 2017-MAR-22

  • Updated BCrypt library to v0.4
  • Fixes a memory leak when performing over 10 concurrent hashes
  • Module test harness updates

[2.1.0] => 2016-MAY-04

  • Updated Docs
  • Fixed javacast issue when passing a work factor
  • Updated JavaLoader dependencies
  • Added Java source for references and future inline build compilation
  • Updated settings to match ColdBox module standards
  • Added full test suites
  • Added Travis integration
  • Added git ignores and attributes

$ box install BCrypt

No collaborators yet.
     
5.00 / 3
  • {{ getFullDate("2013-11-25T09:02:21Z") }}
  • {{ getFullDate("2022-09-06T18:56:46Z") }}
  • 13,314
  • 181,534