HashWithSalt function

Syntax

HashWithSalt(cleartext_string [, &salt_string] [, hash_type] [, disallow_emptystring])

Description

Use the HashWithSalt function to generate a hashed (or “salted”) string. The output is Base64 encoded. For example, use the HashWithSalt function to generate a password for storage in the database. Because the HashWithSalt function generates output from the clear text password and a randomly generated salt value, it provides more secure hashing than the Hash function.

Important:

When you store a hashed password generated by HashWithSalt in PSOPRDEFN.OPERPSWD, you must also store the salt string used in PSOPRDEFN.OPERPSWDSALT.

To compare a clear text input value with an hashed value, use either the VerifyOprPassword function (for hashed and stored passwords) or the VerifyHash function for other salted strings.

Parameters

Parameter	Description
cleartext_string	Specifies the string, such as a password, to be hashed.
&salt_string	Specifies the randomly generated salt value as a string value. Important: If the supplied salt value is a null value, then the HashWithSalt function will generate a salt value that will be returned as the value of this variable or record field.
hash_type	Specifies the hashing algorithm to be used as a quoted literal string: "SHA1" – Use the SHA-1 algorithm. Important: Oracle reserves the right to remove support for SHA-1 hashing in a future release. "SHA256" – Use the SHA-256 algorithm of the SHA-2 family. Note: The default value is "SHA256".
disallow_emptystring	Specifies a Boolean value indicating whether to disallow an empty string as the text to be hashed. Note: The default value is False.

Returns

A String value.

Examples

The following examples demonstrate three methods for generating and storing a hashed password:

• Method 1 – Presents a loop that could process a series of passwords. In this specific case, only one salt value is generated and the loop is executed once only. Because SecureRandomGen is based on the Java security SecureRandom function, it is more efficient to call it once to return an array of required salt values than it is to call it for each salt value required.

  /* method 1 */
  Local array of string &operpwsdsalt;
  Local string &resultSalt;
  &operpwsdsalt = SecureRandomGen();
  If (&operpwsdsalt <> Null) Then
     For &i = 1 To &operpwsdsalt.Len
        &resultSalt = &operpwsdsalt [&i];
        &pswd = HashWithSalt(&OPRPSWD, &operpwsdsalt [&i]);
        PSOPRDEFN.OPERPSWD = &pswd;
        PSOPRDEFN.OPERPSWDSALT = &resultSalt;
     End-For;
  End-If;
  

• Method 2 – Uses the &resultSalt variable as a salt value to generate the hashed password. When the &resultSalt variable is null, HashWithSalt generates a salt value, which in turn is automatically returned back to the variable. Both the hashed password and the salt value are stored together in the database.

  /* method 2 */
  Local string &resultSalt;
  &pswd = HashWithSalt(&OPRPSWD, &resultSalt); 
  PSOPRDEFN.OPERPSWD = &pswd;
  PSOPRDEFN.OPERPSWDSALT = &resultSalt;

• Method 3 – Uses the PSOPRDEFN.OPERPSWDSALT field as a salt value to generate the hashed password, which is then stored in the database. When PSOPRDEFN.OPERPSWDSALT is null, HashWithSalt generates a salt value, which in turn is automatically returned back to the PSOPRDEFN.OPERPSWDSALT field.

  /* method 3 */
  &pswd = HashWithSalt(&OPRPSWD, PSOPRDEFN.OPERPSWDSALT);
  PSOPRDEFN.OPERPSWD = &pswd;