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 209 Dummy example of a credential transformation procedure that reverses the password
1
2
3
function result(context) {
    return context.getProvidedPassword().split("").reverse().join("");
}

The context object has type CredentialTransformationProcedureContext.

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

Note

The procedure context provides access to the internal PBKDF2 key derivation function, without any extra encoding applied. This is useful when needing to use stored passwords created by systems that use PBKDF2 with a different encoding scheme (e.g. ASP.NET).

Examples

Implementing a plaintext transformer

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

Listing 211 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 212 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;
}