Message digest APIs

Message digest algorithms are used to ensure data integrity.

These algorithms produce a fixed-length message digest (hash) of the data using a key and variable size data strings as input. In short, a message digest is a fingerprint of the data. If the data changes, the fingerprint (message digest) changes in ways you cannot predict.

Secure Hash Algorithm (SHA) is a common message digest algorithm. Common SHA algorithms are SHA-1 (160 bit), SHA-256 (256 bit), and SHA-512 (512 bit).

z/TPF provides APIs to create message digests from contiguous and discontiguous data using the SHA-1, SHA-256, SHA-512 message digest algorithms.

Use the tpf_SHA1_Init, tpf_SHA1_Update, and tpf_SHA1_Final functions to create a message digest from discontiguous data using SHA-1. Use the tpf_SHA1_Digest function to create a message digest from contiguous data using SHA-1.

Use the tpf_SHA256_Init, tpf_SHA256_Update, and tpf_SHA256_Final functions to create a message digest from discontiguous data using SHA-256. Use the tpf_SHA256_Digest function to create a message digest from contiguous data using SHA-256.

Use the tpf_SHA512_Init, tpf_SHA512_Update, and tpf_SHA512_Final functions to create a message digest from discontiguous data using SHA-512. Use the tpf_SHA512_Digest function to create a message digest from contiguous data using SHA-512.

The CP Assist for Cryptographic Function (CPACF) must be installed on the processor that the function calls are issued from. The CPACF must support the SHA-256 algorithm if you are using the SHA-256 APIs and must support the SHA-512 algorithm if you are using the SHA-512 APIs.

In the following figure, the tpf_SHA1_Digest function is used to create a message digest from contiguous data. The application issues tpf_SHA1_Digest, passing a pointer to the contiguous data, the length of the contiguous data, and a buffer into which the final message digest is to be placed.
Figure 1. A message digest is created from contiguous data
A message digest is created from discontiguous data in the following figure:
Figure 2. A message digest is created from discontiguous data
Message digest steps for discontiguous data:
  1. The application issues the tpf_SHA1_Init function to initialize the structure that will be used to create the digest.
  2. The application issues the tpf_SHA1_Update function, passing the structure, a pointer to the first piece of discontiguous data, and the length of that piece of data. The digest is updated in the structure.
  3. The application issues the tpf_SHA1_Update function for the second piece of discontiguous data. The digest is updated in the structure. (Use the tpf_SHA1_Update function for each piece of discontiguous data.)
  4. The application issues the tpf_SHA1_Final function, passing the structure and a buffer into which the final message digest is to be placed.