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:

• Supported - implemented and no known issues.
• Obsolete - no longer recommended for use.
• Unsupported - not implemented, but not obsolete.

(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.