Usage

(Before using cfPassphrase, please make sure you have installed it on each server that it will be used.)

The easiest way to use cfPassphrase is via its functions.

Creating a hash is done like so:

<cfset UserHash = PassphraseHash( PassphraseToHash ) />

This should be stored as appropriate and when the time comes to check it, retrieve the previously calculated hash and do:

<cfif PassphraseCheck( PassphraseToCheck , UserHash ) >

This is the simplest way to use cfPassphrase, and is suitable for most cases. It uses the default algorithm (BCrypt) with the default 16 rounds (65536 iterations).

Whilst this is likely good enough, for optimal usage you can specify algorithm params based on where it will be used. For details on why and how to do this, see Tuning Algorithm Params.

Using Another Algorithm

cfPassphrase comes with two alternatives to BCrypt, the NIST-approved PBKDF2 and the more modern SCrypt.

There are arguments in favour of all three of these algorithms. To find out more about them and determine which might be right for you, read the Algorithms page.

To use a different algorithm, specify it as the second argument to PassphraseHash:

<cfset UserHash = PassphraseHash( PassphraseToHash , 'pbkdf2' ) />

<cfif PassphraseCheck( PassphraseToCheck , UserHash ) >

Note the algorithm does not need to be specified for PassphraseCheck since all the algorithms produce mutually exclusive hash signatures.

To discover the algorithm used, as well as parameter values (iterations, etc), use PassphraseInfo:

<cfdump var=#PassphraseInfo( UserHash )# />

Further details on all the functions are provided in the documentation pages for PassphraseHash, PassphraseCheck and PassphraseInfo.

Using cfPassphrase as a tag.

There is a cfpassphrase tag for compatibility reasons: Adobe does not provide an API for adding functions, so it is the simplest option to work the same way on all CFML engines. (Applications using Coldbox framework can use the Coldbox Plugin.)

To create a hash with the tag:

<cfpassphrase variable="UserHash" action="hash" passphrase=#PassphraseToHash# />

To check against a stored hash:

<cfpassphrase variable="ValidHash" action="check" passphrase=#PassphraseToCheck# hash=#UserHash# />

<cfif ValidHash >
...

To get information about a hash:

<cfpassphrase variable="HashInfo" action="info" hash=#UserHash# />

<cfdump var=#hashInfo# />

All functions have a respective tag action, and the arguments available to the functions are also available as attributes to the tag.

Using cfPassphrase on ColdFusion - CFC method

Since ColdFusion does not have a way to provide custom built-in functions, the next best thing is a component with equivalent methods, allowing cfPassphrase to work in script syntax on CF9 and above.

Once installed, this is used as follows:

UserHash = new Passphrase().hash( PassphraseToHash )

And similarly to check:

if ( new Passphrase().check( PassphraseToCheck , UserHash ) )

Whilst this global CFC method can also work on Lucee, Railo and OpenBD, it is unnecessary and not setup with the standard install.

If you are writing code to work across multiple CFML engines, you can do:

if ( Server.ColdFusion.ProductName EQ 'ColdFusion Server' )
{
    PassphraseHash  = new Passphrase().hash;
    PassphraseCheck = new Passphrase().check;
    PassphraseInfo  = new Passphrase().info;
}

This is basically creating UDFs with the same name as the built-in functions the plugin provides.

A downside of this is that it must be done as part of the template/cfc you will be using the functions in - putting the above code in Application.cfc wont work, (unless using a framework that includes templates as part of onRequest).