APIs by Example: The Calculate Hash Value Command

Back in time the _CIPHER MI instruction was the only immediately available function to produce an MD5 (Message Digest) or SHA-1 (Secure Hash Algorithm) hash value. Now that the SHA-1 algorithm has been deprecated, it appears that the _CIPHER MI instruction does not support the SHA-256 hash algorithm.

IBM probably decided to focus their effort on the more recent Calculate Hash (Qc3CalculateHash) API.

As documented, the Qc3CalculateHash API supports the MD5 as well as SHA-1 to SHA-512 hash algorithms, and will probably continue to be enhanced, if and when new algorithms are implemented. I have written a very simple Calculate Hash Value (CLCHASHVAL) command for the purpose of demonstrating how to call he Qc3CalculateHash API. The command processing program could easily be adapted to more specific requirements, given the need.

The Calculate Hash Value command is based on the following source members:

CBX277    RPGLE    Calculate Hash Value - CPP              
CBX277S   RPGLE    Encrypt and Decrypt Data - services     
CBX277B   SRVSRC   Encrypt and Decrypt Data - services     
CBX277H   PNLGRP   Calculate Hash Value - Help             
CBX277X   CMD      Calculate Hash Value
CBX277M   CLP      Calculate Hash Value - Build command

Compiling and running the CL-program CBX277M will create the utility for you, once you’ve copied the other source members to their respective default source files. The source members are located in the zip file ClcHashVal.zip available here:

Download the save file containing the source code.

Postscript: I have added the Calculate File Hash Value (CLCFILHASH) command to the download zip-file. The CLCFILHASH command is similar to the CLCHASHVAL command, but will produce the hash value based on the content of a specified input stream file name. You’ll find compilation instructions in each of the respective source file headers:

CBX2772   RPGLE    Calculate File Hash Value - CPP   
CBX2772H  PNLGRP   Calculate File Hash Value - Help  
CBX2772X  CMD      Calculate File Hash Value            

2 thoughts on “APIs by Example: The Calculate Hash Value Command

  1. Hi Carten
    sorry for disturbing you .. i have downloaded the zip ClcHashVal.zip, but running the command CLCHASHVAL, i find the result different from some online hash calculator;
    example if i run CLCHASHVAL CALCDATA(ABC) HASHALG(*SHA256)
    Input . . . : ABC
    Hash value . :
    but if go to for example to https://www.xorbin.com/tools/sha256-hash-calculator
    the result is
    where am i wrong ?
    Thanks in advance


    1. Hi Angiolo,

      Thanks for your e-mail! The difference in the results you’re seeing, is due to two different character sets being involved. Cryptographic processing is always based on the binary value of an input string – even if you see it as characters.

      The CLCHASHVAL command running on a System i, is therefore acting on an EBCDIC character set when you specify the input value ‘ABC’ – which is equal to the hexadecimal value x’C1C2C3’.

      And this site https://www.xorbin.com/tools/sha256-hash-calculator being a web-page, is seeing the UTF-8 representation for the same letters – so here ‘ABC’ amounts to x’414243’.

      This topic is explained in more detail here:

      If you run the following command you should see the result you’d expect:

      – Because now the CLCHASHVAL is processing the same binary value as the http://www.xorbin.com site does.

      Let me know if you have any questions, or need me to elaborate further.


Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s