Sorcerer's Isle cfPassphrase Documentation

PassphraseInfo

Description

Examines the hash provided and returns the information which is encoded within it, including the algorithm, version and iterations.

These details can be used to determine whether a passphrase might need to be re-hashed using a newer algorithm or increased number of iterations.

In addition to the supported algorithms, this function will also identify hashes from common crypt implementations.

Returns

A struct containing information about the hash provided.

Different algorithms provide different keys. All algorithms provide at least the key "Algorithm" containing its name, and "Status" providing a guide to whether this algorithm can/should be used:

(Note that this value does not consider algorithm parameters.)

Function syntax

PassphraseInfo( Hash [, Algorithm ])

Arguments

Name Type Default Description
Hash String Required A hash in the format of a supported algorithm.
Algorithm String Optional If unspecified, the algorithm is auto-detected from the hash.

Example

The PassphraseInfo function might be used inside a scheduled task that runs occasionally to check for accounts that need to be refreshed:

<cfquery name="OldUsers" datasource="UserAuth">
    SELECT Id , Hash
    FROM User
    WHERE LastModified < <cfqueryparam value=#Now()-60# cfsqltype="cf_sql_date" />
    AND   IsStale = 0
</cfquery>

<cfset StaleHashes = [] />

<cfloop query="OldUsers">
    <cfset HashInfo = PassphraseInfo ( OldUsers.Hash ) />

    <cfif HashInfo.Algorithm NEQ CurrentAlgorithm
        OR HashInfo.Iterations < MinCurrentIterations
        >
        <cfset ArrayAppend( StaleHashes , OldUsers.Id ) />
    </cfif>
</cfloop>

<cfif ArrayLen(StaleHashes)>
    <cfquery datasource="UserAuth">
        UPDATE User
        SET IsStale = 1
        WHERE Id IN (<cfqueryparam list value=#ArrayToList(StaleHashes)# cfsqltype="cf_sql_integer />)
    </cfquery>
</cfif>

It is not possible to calculate a newer hash without the passphrase, thus you cannot simply update a hash to increase the iterations, and instead need to set a flag to indicate the action must be performed at the next login.