HASH

9.5A, NCHAR

The HASH instruction evaluates an input source string and uses a cryptographic hash function that returns a fixed-sized bit string. The resulting hash string has a length depending on the type of cryptographic hash function that is used. The instruction uses the following format:

Where:

label

Optional. A Program Execution Label.

source

Required. A previously defined Character String Variable or National Character String Variable that is evaluated to generate a hash string.

sep

Required. A comma or one of the following prepositions: BY, TO, OF, FROM, USING, WITH, IN, or INTO.

dest

Required. A previously defined character variable the receives the cryptographic hash string result. This variable must have a size as determined by the type of hash function that is being executed.

hashtype

Optional. A Decimal Number or a Numeric Variable that specifies the type of cryptographic hash function to be executed.

Flags Affected: ZERO, EOS

Note the following:

1. The Logical String of the {source} variable is evaluated to generate the hash string. A NULL source variable is valid for generating a hash string.

2. The {dest} variable can not be a NCHAR because the output hash string is not a valid UTF-8 string.

3. The optional MODE value identifies that type of cryptographic hash function that is to be executed. If the MODE value is not specified, the default hash function is executed using the MD5 algorithm. If the MODE value is invalid, a F11 error occurs. The acceptable MODE values are defined as follows:

 

Mode Value	Hash Function Type
0	MD5 with context initialization
1	SHA-256 with context initialization
2	SHA-284 with context initialization
3	SHA-512 with context initialization
4	SHA1 with context initialization
100	MD5 without context initialization
101	SHA-256 without context initialization
102	SHA-284 without context initialization
103	SHA-512 without context initialization
104	SHA1 without context initialization

 

4. The {dest} DIM variable size is determined based on the type of cryptographic hash function that is executed. The EOS flag is set if the {dest} DIM variable size is too small to receive all of the hash string data. The required sizes are defined as follows:

 

 

Hash Function	Destination Size in Bytes
MD5	16
SHA1	20
SHA-256	32
SHA-284	48
SHA-512	64

 

5. The ZERO flag is set if the hash string is generated.

6. The HASH types without context initialization generate a hash string value that is accumulated using multiple parts of a hash data stream. An application can create an accumulated hash string value by executing the HASH for multiple strings. As an example, a hash string value could be accumulated against multiple fields in a record without having all of the fields packed into a single DIM. Also, a hash string value could be accumulated for the data in a file by reading and hashing multiple records from a file. The following steps are required to generate an accumulated hash string value:
    

1. Execute a HASH instruction using a hash type with context initialization for the first data string included in the hash. This requires a hash type value less than 100. All hash type values less than 100 perform an initialization of the hash context before the hashing is started

2. Execute HASH instructions without context initialization for multiple partial strings being hashed for a data stream. The hash types without context initialization have values from 100 to 199. Make sure that the same hashing algorithm is being used for steps (a.) and (b

3. The last hash string value returned after the last partial data string is the final hash string value

4. A new accumulated hash string value can be started with step (a.).

 

Example:

 

Hash1 DIM 16

Hash2 DIM 16

.

Str1 INIT "Hello "

Str2 INIT "Sunbelt "

Str3 INIT "World!"

.

         PACK S$CMDLIN, Str1, Str2, Str3

          HASH S$CMDLIN, Hash1, Mode=0 ;Context initialized

.

         HASH Str1, Hash2, Mode=0 ;Context initialized

         HASH Str2, Hash2, Mode=100 ;Context not initialized

         HASH Str3, Hash2, Mode=100 ;Context not initialized

.

         IF ( Hash1 == Hash2 )

         DISPLAY "Hash values are same!"

         ELSE

         DISPLAY "Hash values are different!"

         ENDIF

         KEYIN "Hit enter to exit:",S$CMDLIN

 

7. The MD5 hash string is generated using the RSA Data Security, Inc. MD5 Message-Digest Algorithm.

8. The SHA1/SHA2 hash functions for the PLB HASH statement provides the SHA1, SHA-256, SHA-384, and SHA-512 secure hash algorithms. The logic that is used has been written and provided under the open source BSD licensing. This logic has a copyright and is provided with the following disclaimer:

 

THIS SOFTWARE IS PROVIDED BY THE AUTHOR(S) AND CONTRIBUTOR(S)``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR(S) OR CONTRIBUTOR(S) BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

See Also: Character String Instructions