Get Security (Whirlpool) Hash

GetSecHash

The GetSecHash procedure returns the 512-bit Whirlpool cryptographic hash for the input string. The Whirlpool hash was designed by Vincent Rijmen and Paulo S. L. M. Barreto. It has been adopted by the International Organization for Standardization (ISO) and the International Electrotechnical Commission (IEC) as part of the joint ISO/IEC 10118-3 standard.

The Hash is often stored in database in place of pass phrases or passwords. Then when the user enters the password or pass phrase, the Hash is recalculated from the user-entered data and compared with the Hash stored in the database.

The Whirlpool Hash is a 64-byte (512-bit) value. By default the Hash is determined using the ASCII character set CCSID 819. To return the Hash in the CCSID of the job, specify 0 for the "to CCSID". 

length  =  GetSecHash(
  szRtnHash          128A    OPTIONS(*VARSIZE)
  pClearText            *    Value OPTIONS(*STRING)
  nFromCCSID          10I 0  Const OPTIONS(*NOPASS:*OMIT)
  nToCCSID            10I 0  Const OPTIONS(*NOPASS:*OMIT)
  bToHex               1N    Const OPTIONS(*NOPASS:*OMIT)
)

See also: GetMD5Hash, GetSecHashEx

Parameters

szRtnHash
[input Char(64 | 128) ]  Specify a field whose length is either 64 or 128 bytes in length. The Hash is returned in this parameter. If the optional bToHex parameter is not specified or is specified as something other than '1', then the hash is returned as a 64-byte value. If the bToHex is '1', the Hash value is returned in hexadecimal notation (a 128-byte value).
pClearText
[input Char(*) const]  The original text that is used to create the Whirlpool "message digest".  The 64-byte "signature", known as the "message digest" is returned after processing the value specified for this parameter with the Whirlpool Hash algorithm. Specify a field, literal, named constant or data structure for this parameter. A fixed-length or VARYING field is permitted. The value is automatically converted in a null-terminated string for you. The maximum length of a null terminated string is just short of 32k of data. To compute the Whirlpool hash for values longer than 32k, use GetSecHashEx.
 
nFromCCSID  [[optional] DFT(0)
[input int(4) const]  This parameter identifies the CCSID of the text passed to the GetSecHash procedure on the pClearText parameter.  If the parameter is not specified or is equal to 0, the text is considered to be in the default CCSID of the job.  
nToCCSID  [[optional] DFT(0)
[input int(4) const]  This parameter identifies the CCSID of the Hash value returned to the caller on the szRtnHash parameter. The data specified on the pClearText parameter is convert to this CCSID and then the hash is calculated, thus producing a hash in the target CCSID.  If the parameter is not specified it defaults to 0 and the CCSID of the job is used. A CCSID value of 819 is often used to return the Hash in PC ASCII .
 
bToHex  [optional] DFT(*OFF)
[input Indy const]  This parameter indicates whether or not the Whirlpool Hash is returned as hexadecimal (128-bytes) or character (64-bytes).  If this parameter is not specified or is specified as something other than '1', then the hash is returned as a 64-byte value. If  '1' (or *ON) is specified, the Hash value is returned in hexadecimal notation (a 128-byte value).

Return Value

If the function succeeds, the return hash is a 64-byte Whirlpool "message digest" or the 128-byte hexadecimal Whirlpool "message digest". The returned length is the length of the returned message digest value (i.e., 64 or 128).

 

Example 1 - Retrieve Whirlpool Hash

 
      /INCLUDE QCPYSRC,security

     D PWD             S             80A   Inz('The quick brown fox jumps +   

     D                                          over the lazy dog.') VARYING

     D szRtnHash       S             64A   

 

     C                   callp     GetSecHash(szRtnHash: PWD )

As a result of the call to GetSecHash(), the field szRtnHash contains the "message digest" for the text stored in the PWD field. This 64-byte value is unique and may be stored in a database file for comparison later on.

Example 2 - Retrieve Whirlpool Hash as a Hex String

 
      /INCLUDE QCPYSRC,security

     D PWD             S             80A   Inz('The quick brown fox jumps +   

     D                                          over the lazy dog.') VARYING

     D szRtnHash       S            128A 

  

     C                   callp     GetSecHash(szRtnHash : PWD : 0 : 0 : *ON)

 

As a result of the call to GetSecHash() in this example, the 64-byte Whirlpool Hash is returned after converting it to 128 hexadecimal characters.

There is an example program in the QRPGEXTRA source file, shipped with the RPG xTools, named HASHPROOF. This source member, when compiled and run, is a program that generates the Whirlpool Hash for the so called Proof of accuracy values. The output from calling the HashProof program is in ASCII hexadecimal so it can be compared with external sources.

The follow example output is from the ISO standards test.

1. In this example the data-string is the empty string, i.e. the string of length zero.

19FA61D75522A466 9B44E39C1D2E1726 C530232130D407F8 9AFEE0964997F7A7
3E83BE698B288FEB CF88E3E03C4F0757 EA8964E59B63D937 08B138CC42A66EB3

2. In this example the data-string consists of a single byte, namely the ASCII-coded version of the letter 'a'.

8ACA2602792AEC6F 11A67206531FB7D7 F0DFF59413145E69 73C45001D0087B42
D11BC645413AEFF6 3A42391A39145A59 1A92200D560195E5 3B478584FDAE231A

3. In this example the data-string is the three-byte string consisting of the ASCII-coded version of 'abc'.

4E2448A4C6F486BB 16B6562C73B4020B F3043E3A731BCE72 1AE1B303D97E6D4C
7181EEBDB6C57E27 7D0E34957114CBD6 C797FC9D95D8B582 D225292076D4EEF5

4. In this example the data-string is the 14-byte string consisting of the ASCII-coded version of 'message digest'.

378C84A4126E2DC6 E56DCC7458377AAC 838D00032230F53C E1F5700C0FFB4D3B
8421557659EF55C1 06B4B52AC5A4AAA6 92ED920052838F33 62E86DBD37A8903E

5. In this example the data-string is the 26-byte string consisting of the ASCII-coded version of 'abcdefghijklmnopqrstuvwxyz'.

F1D754662636FFE9 2C82EBB9212A484A 8D38631EAD4238F5 442EE13B8054E41B
08BF2A9251C30B6A 0B8AAE86177AB4A6 F68F673E7207865D 5D9819A3DBA4EB3B

6. In this example the data-string is the 62-byte string consisting of the ASCII-coded version of 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789'.

DC37E008CF9EE69B F11F00ED9ABA2690 1DD7C28CDEC066CC 6AF42E40F82F3A1E
08EBA26629129D8F B7CB57211B9281A6 5517CC879D7B9621 42C65F5A7AF01467

7. In this example the data-string is the 80-byte string consisting of the ASCII-coded version of eight repetitions of '1234567890'.

466EF18BABB0154D 25B9D38A6414F5C0 8784372BCCB204D6 549C4AFADB601429
4D5BD8DF2A6C44E5 38CD047B2681A51A 2C60481E88C5A20B 2C2A80CF3A9A083B

8. In this example the data-string is the 32-byte string consisting of the ASCII-coded version of 'abcdbcdecdefdefgefghfghighijhijk'.

2A987EA40F917061 F5D6F0A0E4644F48 8A7A5A52DEEE6562 07C562F988E95C69
16BDC8031BC5BE1B 7B947639FE050B56 939BAAA0ADFF9AE6 745B7B181C3BE3FD

9. In this example the data-string is the 1000000-byte string consisting of the ASCII-coded version of 'a' repeated 10^6 times.

0C99005BEB57EFF5 0A7CF005560DDF5D 29057FD86B20BFD6 2DECA0F1CCEA4AF5
1FC15490EDDC47AF 32BB2B66C34FF9AD 8C6008AD677F7712 6953B226E4ED8B01