hash Function

Format

s = hash(valueʃ, lengthʃ, saltʅʅ);

Description

The hash function generates a hash value for the string or numeric expression value. This hash value is a fixed-length representation of the value and can be used for purposes such as storing passwords without storing the actual plaintext password. The hash value of the same text string will always be the same, but it is nontrivial (impossible for CSPro purposes) to work backwards to calculate the original text from the hash value.

The hash value is calculated using a SHA-256 key derivation algorithm. This results in a 32-byte value, which is returned as a hexadecimal string with each byte represented as two characters, thus resulting in a string of a length 64.

Optionally, you can specify a numeric expression length, which specifies the length of the hash value in bytes. The string returned will always be twice the value of length. The maximum value for length is 500.

You can also specify a string expression, salt, which is an additional input in generating the hash value. You must store this salt value somewhere to be able to use this hash function to perform any checks. More information on hash values, key derivation algorithms, and salt values is readily available online.

Hash values can also be created, with additional options, using the action Hash.createHash.

Return Value

The function returns a hash value represented as a hexadecimal string. When using logic version CSPro 8.0+, the hexadecimal characters are returned in lowercase; when using the original logic version, the characters are returned in uppercase.

Example

string userPassword = prompt("Enter your password", password);

if hash(userPassword) <> strip(USER_PASSWORD_HASH) then
errmsg("Invalid password. You cannot access this system.");
stop(1);
endif;

See also: Hash.createHash Action, HashMap Object