Performs a hashing operation on a value and returns a CHARACTER string with the hashed value encoded as a Base64-encoded string. GENERATE-PASSWORD-HASH() supports password hash generation using algorithms that are approved by the National Institute of Standards and Technology (NIST). You can use GENERATE-PASSWORD-HASH() as the replacement for the ENCODE function.

The GENERATE-PASSWORD-HASH() function performs a one-way hashing operation that you cannot revert. It is useful for storing scrambled copies of passwords in a database. It is impossible to determine the original password by examining the database. However, a procedure can prompt a user for a password, hash it, and compare the result with the stored hashed password to determine if the user supplied the correct password. Best practices define that when generating a password hash, you should also include a random salt value for added security, and that each time you re-hash a password, you use a different random salt. To be able to reproduce the hash value, you need to know the cleartext password, the salt value used, the hashing algorithm, and the number of iterations used for the hashing operation, so it is important to keep the hash password, salt, and iteration number used, to be able to reproduce the same hash value from a given cleartext password.

Syntax

GENERATE-PASSWORD-HASH ( password [, salt [, hash-algorithm ] ] )
password
Cleartext to be hashed of type CHARACTER, LONGCHAR, RAW, or MEMPTR. If password is a CHARACTER or LONGCHAR value, the AVM converts it to UTF-8 (which ensures a consistent value regardless of code page settings). To avoid this automatic conversion, specify a RAW or MEMPTR value. If you specify the Unknown value (?), the result returned is the Unknown value (?).
salt
An optional RAW expression that evaluates to the salt value (a random series of bytes) to use in generating the hashed password. If you do not pass a salt parameter or specify the unknown value (?), the current value of SECURITY-POLICY:PASSWORD-HASH-SALT is used. If no salt value is specified in SECURITY-POLICY:PASSWORD-HASH-SALT, no salt value is used.
Note: If FIPS mode is enabled, a salt value of 16 to 512 bytes in size is required, and must be specified either in SECURITY-POLICY:PASSWORD-HASH-SALT or as the salt argument in this function. Otherwise, the AVM generates a runtime error.

You can use the GENERATE-SALT function to get a random salt of the desired size.

hash-algorithm
An optional CHARACTER expression that specifies the hashing algorithm to use to hash the password.
The hashing algorithm must be one of the following (listed in order of increased security and decreased performance):
  • PBKDF2-HMAC-SHA-256
  • PBKDF2-HMAC-SHA-384
  • PBKDF2-HMAC-SHA-512

If hash-algorithm is specified and does not match one of the allowed algorithms, the AVM generates a runtime error.

If hash-algorithm is not specified or is the Unknown value (?), GENERATE-PASSWORD-HASH uses the algorithm specified in SECURITY-POLICY:PASSWORD-HASH-ALGORITHM.

Examples

GENERATE-PASSWORD-HASH(cPassword1, rSalt1, "PBKDF2-HMAC-SHA-384")

GENERATE-PASSWORD-HASH(cPassword2, rSalt2, ?)

GENERATE-PASSWORD-HASH(cPassword3, GENERATE-SALT(iSize), "PBKDF2-HMAC-SHA-512")

Notes

  • You can use GENERATE-PASSWORD-HASH() when FIPS mode is enabled or not. The results are the same either way, given the same input parameters.
  • GENERATE-PASSWORD-HASH() uses the value of the SECURITY-POLICY:PASSWORD-HASH-ROUNDS for determining the number of iterations performed when generating the hashed password.
  • If you call GENERATE-PASSWORD-HASH() multiple times with the same password string, hash algorithm, salt value, and number of iterations (specified by SECURITY-POLICY:PASSWORD-HASH-ROUNDS), the same password hash is generated each time.

See also

GENERATE-SALT function, PASSWORD-HASH-ALGORITHM attribute, PASSWORD-HASH-ROUNDS attribute, PASSWORD-HASH-SALT attribute