Produces a 20-byte message digest from an input text string using the secure hash algorithm (SHA-1).
Note: When calling this routine, ensure you compile using DIALECT"RM".


CALL "C$SecureHash" USING message-text [message-length]
                    GIVING message-digest


PIC X(n)
PIC 9(n)
PIC X(n)

On Entry:


Its value is the input text string to the secure hash algorithm. While the secure hash algorithm supports messages of length 2**64 or less bits (2**61 or less bytes), this implementation is limited to messages of length 2**32 or less bits (2**29 or less bytes).


Its value specifies the number of bytes of message-text to be considered when producing the message digest. Thus, the value must be less than or equal to the length of data item referenced by message-text. If message-length is omitted, the entire value of the data item referenced by message-text is used, as if LENGTH OF message-text had been specified for message-length.

On Exit:


It must be an identifier that references a nonnumeric data item of exactly 20 bytes in length. The message digest result from the secure hash algorithm is returned in the referenced data item. The message digest value is stored in the form most significant byte at lowest address to least significant byte at highest address regardless of the memory architecture of the machine on which C$SecureHash is called.

When there is insufficient memory for C$SecureHash to do its work, the contents of message-digest are set to all binary zeroes. This only occurs when a memory area slightly larger than the size of the message text cannot be allocated. The secure hash algorithm used by C$SecureHash, other than the length limitation, is the one defined as the secure hash standard by Federal Information Processing Standard (FIPS) Publication 180-1, which is often referred to as SHA-1.


One example of the usefulness of a message digest is storing a password in a secure form. Since message-digest is produced using a one-way hash of the password, it is computationally infeasible to recover the password from the message-digest value. (However, if the password is easy to guess or find in a dictionary, a computer program can be used to search for a password that hashes to a given message-digest value.)
Note: The input text string “abc” (length = 3 bytes) produces the hash value:


Since this is a well-known test result for the secure hash algorithm (documented in FIPS Pub 180-1), “abc” is not recommended as a password value. Message digests are also often used to verify that a message has not been changed from its original value. This involves computing the message-digest of the original message-text and transmitting it in a secure manner, either on a separate secure channel or by using encryption of message-digest to guarantee that it is not modified during transmission. The receiver of the message can then compute the message digest from the received message-text and verify that the resulting message-digest matches the one supplied. If they match, it is extremely unlikely that the message text has been modified during transmission.