Hashes any of several types of source data using the specified hashing algorithm, and returns a RAW message digest value whose size and security depends on the algorithm.

Syntax

MESSAGE-DIGEST( hash-algorithm, data-to-hash[, hash-key ] )
hash-algorithm
A character string that specifies the hashing algorithm to use to hash the data specified by data-to-hash. You can specify one of the following options, which are generally in the order of increased security and decreased performance:
  • "MD5" — RSA Message Digest Hash Algorithm, which returns a 16-byte RAW binary message digest value.
    Note: This algorithm is provided for backward compatibility only and should not be used in new development. Existing applications and data storage should migrate away from this algorithm as soon as possible.
  • "SHA-1" — United States Government Secure Hash Algorithm, which returns a RAW 20-byte binary message digest value.
    Note: This algorithm is provided for backward compatibility only and should not be used in new development. Existing applications and data storage should migrate away from this algorithm as soon as possible.
  • "SHA-256" — United States Government Secure Hash Algorithm, which returns a RAW 32-byte binary message digest value.
  • "SHA-512" — United States Government Secure Hash Algorithm, which returns a RAW 64-byte binary message digest value.
  • "HMAC-SHA-1" — United States Government HMAC (Hash-based Message Authentication Code) algorithm, which returns a RAW 20-byte binary message digest value.
    Note: This algorithm is provided for backward compatibility only and should not be used in new development. Existing applications and data storage should migrate away from this algorithm as soon as possible.
  • "HMAC-SHA-256" — United States Government HMAC (Hash-based Message Authentication Code) algorithm, which returns a RAW 32-byte binary message digest value.
  • "HMAC-SHA-384" — United States Government HMAC (Hash-based Message Authentication Code) algorithm, which returns a RAW 48-byte binary message digest value.
  • "HMAC-SHA-512" — United States Government HMAC (Hash-based Message Authentication Code) algorithm, which returns a RAW 64-byte binary message digest value.
Note: If FIPS mode is enabled and an algorithm is specified that is not approved by the National Institute of Standards and Technology (NIST), the AVM generates a run-time error.
data-to-hash
The source data to hash. The data may be of type CHARACTER, LONGCHAR, RAW, or MEMPTR. If the data 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.
hash-key

A key value to use in the hash operation for the hashing algorithms. The key may be of type CHARACTER, LONGCHAR, RAW, or MEMPTR. If the key 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. This key value is used along with the source data during the hash operation.

For the HMAC algorithms, it is strongly recommended that you specify a hash key (preferably a randomly generated one). If hash-key is not specified, it defaults to the empty string ("") if hash-algorithm is an HMAC algorithm.

If either data-to-hash or hash-key is the Unknown value (?), then the Unknown value (?) is returned from the function.

If the hash-key value contains a null character, the null character is included in the hash operation.

Example

The following example demonstrates how to use the MESSAGE-DIGEST function.

DEFINE VARIABLE mydata AS CHARACTER NO-UNDO INITIAL "My data to hash".
DEFINE VARIABLE hashkey AS CHARACTER NO-UNDO INITIAL "My hash key".
DEFINE VARIABLE mdvalue AS RAW NO-UNDO.

mdvalue = MESSAGE-DIGEST("SHA-512", mydata, hashkey).

MESSAGE "LENGTH: " LENGTH(mdvalue) SKIP
        "VALUE: " STRING(mdvalue) VIEW-AS ALERT-BOX.

See also

MD5-DIGEST function, SHA1-DIGEST function