Credential Transformation Procedures

Credential transformation procedures are used by the Credential Managers when custom credential verification is needed. More accurately the procedure is responsible for transforming the password by applying the appropriate algorithm. Normally it would be enough to use the built in types on the credential managers such as SHA256, SHA512 or BCrypt, but when faced with an existing user store where the passwords already are hashed using a custom scheme, these procedures can be used to hash the password before comparison.

Function

A credential transformation procedure has the following format.

Listing 196 Dummy example of a credential transformation procedure that reverses the password
1
2
3
function result(context) {
    return context.getProvidedPassword().split("").reverse().join("");
}

The functions receives the user-provided password and, if present, the stored password from the data source. These can be used to perform the transformation operation.

Listing 197 Procedure implementing sha512Crypt hashing
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
function result(context) {
    var comparablePassword = context.getComparablePassword()
    var providedPassword = context.getProvidedPassword()

    var result
    if (context.sha512CryptCheckPassword(providedPassword, comparablePassword))
    {
        result = comparablePassword;
    }
    else
    {
        result = context.sha512CryptHashPassword(
            providedPassword, context.generateRandomSaltSha512(20000))
    }

    return result;
}

The comparablePassword is the already hashed password retrieved from the credential store. Some algorithms require the stored password to extract the salt and other parameters needed to hash the providedPassword for comparison.

Important

It is not the job of the transformation procedure to actually compare the passwords, but it is often needed in order to know if a new hash is needed or the existing hash should be reused.

API

The following functions and properties are available on the context provided to the result function.

providedPassword

The plain text password provided by the user

comparablePassword

null if this transformation is preparing to store the providedPassword for the first time. Otherwise containing the hashed password fetched from the credential data source.

sha1HexHash(password)

Convert the password to a sha1 hashed string in hex format

Arguments:
  • password – The password to hash
Returns:

The hex string of the hash

sha1Base64Hash(password)

Convert the password to a sha1 hashed string in base64 format

Arguments:
  • password – The password to hash
Returns:

A base64 encoded string of the sha1 hash

sha256CryptHashPassword(password, salt)

Generates a SHAcrypt compatible “$5$” SHA2 based hash value The returned format is $5[$<param>=<value>(,<param>=<value>)*][$<salt>[$<hash>]] Use generateRandomSaltSha256 to generate a compatible salt or use the comparablePassword if exists.

Arguments:
  • password – The providedPassword to hash
  • salt – The salt to use when hashing. This can be a SHAcrypt formatted string
Returns:

The hashed password as string

sha256CryptCheckPassword(password, comparablePassword)

Check if a provided password matches the stored password

Arguments:
  • password – The provided password
  • comparablePassword – A hashed password to compare with
Returns:

True if the passwords match. Always false if comparablePassword is null

sha512CryptHashPassword(password, salt)

Generates a SHAcrypt compatible “$6$” SHA2 based hash value The returned format is $6[$<param>=<value>(,<param>=<value>)*][$<salt>[$<hash>]] Use generateRandomSaltSha512 to generate a compatible salt or use the comparablePassword if exists.

Arguments:
  • password – The providedPassword to hash
  • salt – The salt to use when hashing. This can be a SHAcrypt formatted string
Returns:

The hashed password as string

sha512CryptCheckPassword(password, comparablePassword)

Check if a provided password matches the stored password

Arguments:
  • password – The provided password
  • comparablePassword – A hashed password to compare with
Returns:

True if the passwords match. Always false if comparablePassword is null

bcryptHashPassword(password, salt)

Hash a password using BCrypt. This should be used for new hashes when creating the password hash the first time. Use generateRandomSaltBcrypt` to generate a salt.

Arguments:
  • password – The providedPassword to hash
  • salt – The salt using the BCrypt salting
Returns:

The hashed password as string

bcryptCheckPassword(password, comparablePassword)

If a current hash of the password exists, this function should be used to compare the hash with the current password. If they match, then the already hashed password should be used as transformation result

Arguments:
  • password – The provided password
  • comparablePassword – A hashed password to compare with
Returns:

True if the passwords match. Always false if comparablePassword is null

phpassHashPassword(password)

Hash a password using Phpass

Arguments:
  • password – The providedPassword to hash
Returns:

The hashed password as string

phpassHashPassword(password, iterations)

Hash a password using Phpass

Arguments:
  • password – The providedPassword to hash
  • iterations – The number of iterations to initialize phpass with
Returns:

The hashed password as string

phpassCheckPassword(password, comparablePassword)

If a current hash of the password exists, this function should be used to compare the hash with the current password. If they match, then the already hashed password should be used as transformation result

Arguments:
  • password – The provided password
  • comparablePassword – A hashed password to compare with
Returns:

True if the passwords match. Always false if comparablePassword is null

generateRandomSalt(length)

Generates a random salt of given length.

Arguments:
  • length – The length of the string salt
Returns:

A random string

generateRandomSaltSha256(rounds)

Generates a random salt for SHA2 with SHA256, formatted according to SHAcrypt.

Arguments:
  • rounds – The number of rounds in the salt string
Returns:

A salt string for SHA2 with SHA256

generateRandomSaltSha512(rounds)

Generates a random salt for SHA2 with SHA512, formatted according to SHAcrypt.

Arguments:
  • rounds – The number of rounds in the salt string
Returns:

A salt string for SHA2 with SHA512

generateRandomSaltBcrypt()

Generates salt using BCrypt and default cost.

Returns:A salt string for Bcrypt
generateRandomSaltBcrypt(cost)

Generates salt using BCrypt with a given cost as the log2 number of rounds of hashing to apply - the work factor therefore increases as 2<sup>log_rounds</sup>

Arguments:
  • rounds – The the log<sub>2</sub> of the number of rounds of hashing to apply
Returns:

A salt string for Bcrypt

Examples

Implementing a plaintext transformer

A plaintext transformer does (as the name suggests) no transformation.

Listing 198 Procedure implementing plaintext
1
2
3
function result(context) {
    return context.getProvidedPassword();
}

Implementing a SHA512 transformer

A SHA512 transformer operating exactly as the built in Sha2WithSha512 transformer

Listing 199 Procedure implementing Sha2WithSha512
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
function result(context) {

    var comparablePassword = context.getComparablePassword()
    var providedPassword = context.getProvidedPassword()

    var result
    if (context.sha512CryptCheckPassword(providedPassword, comparablePassword))
    {
        result = comparablePassword;
    }
    else
    {
        result = context.sha512CryptHashPassword(providedPassword,
                    context.generateRandomSaltSha512(20000))
    }

    return result;
}