MESSAGE-DIGEST function

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. This is provided for backward compatibility only and should not be used in new development.
• "SHA-1" — United States Government Secure Hash Algorithm, which returns a RAW 20-byte binary message digest value.
• "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.
• "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.

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