Redvers Hashing Algorithm. User Guide. RCHASH Version 2.3

Transcription

1 Redvers Consulting Ltd Redvers Hashing Algorithm User Guide RCHASH Version 2.3

2 Contents Preface... 3 Introduction... 4 Overview... 5 Installation... 6 Calling RCHASH... 7 Parameters... 7 COMMUNICATION-BLOCK... 7 MESSAGE-STRING... 8 Sample Program with a single Message String... 9 Sample Program with multiple Message Strings Appendix A - Feedback Messages Appendix B - References Index Redvers Consulting Ltd Page 2

3 Preface This document describes the installation and operation of the Redvers Hashing Algorithm. It is designed for use by Information Technology departments running COBOL applications who wish to authenticate information transmitted to/from external sources or as a means to one-way encryption. This User Guide can be found on the internet at: Copyright 2015 Redvers Consulting Ltd. Redvers Consulting Ltd Page 3

4 Introduction Redvers Hashing Algorithm - User Guide 2.3 The Redvers Hashing Algorithm calculates a hash total, sometimes referred to as a message digest, representing a condensed abstract of the input message string. The total is not only dependant on the accumulation of all bit settings throughout the message but also the position of each bit within the message string. When data is to be transferred from one location to another, a hash total can be calculated at each location and compared to prove message completeness and authenticity. The possibility that two different messages could produce the same hash total (a collision ) is very unlikely for longer totals (384 bits or 512 bits) very, very unlikely. Hash totals cannot be used as a substitute for data encryption and decryption (see the Redvers Encryption Device [1] for details) as information is lost during the hashing process and therefore the output cannot be used to regenerate the original data. The Redvers Hashing Algorithm supports a total of nine Secure Hash Standard algorithms within the three algorithm groups: SHA-1, SHA-2 and SHA-3. SHA-1 produces a hash total length of 160 bits (20 bytes), with SHA-2 and SHA-3 each producing hash lengths of 224, 256, 384 or 512 bits (28, 32, 48 or 64 bytes respectively). In addition to the nine standard algorithms, truncated versions of SHA-512 (SHA- 512/224 and SHA-512/256) can also be generated. Definitions for the SHA-1 and SHA-2 algorithms can be found in the National Institute of Standards and Technology (NIST) [2] document FIPS PUB [3]. The current definitions for the SHA-3 algorithms can be found in the Keccak Reference [6] document. Redvers Consulting Ltd Page 4

5 Overview Redvers Hashing Algorithm - User Guide 2.3 The Redvers Hashing Algorithm is a COBOL subroutine (RCHASH) which may be called by applications running on any computer platform, in batch or on-line modes. Data to be hashed is passed to RCHASH in the form of a character string held in application storage. RCHASH then returns the binary hash total (message digest). Parameter information including the specific algorithm to be used, is transferred in a fixed format communication block. Data selected for hashing can consist of a single field, a record or a complete file of records, each passed to the subroutine in a CALL statement. Data Network Message sent Message received Application program RCHASH Message confirmed Application program RCHASH Redvers Consulting Ltd Page 5

6 Installation Redvers Hashing Algorithm - User Guide 2.3 The Redvers Hashing Algorithm (RCHASH) is a self-contained COBOL source program that requires no copybooks or objects. Before being despatched, the source code was passed through the Redvers COBOL Cloaking Device [4] which removes intellectual property within the source code without changing the logic. To install the program, copy the cloaked source code into your source code library and paste the activation key (sent in an when ordering/downloading) over the question marks in the last VALUE clause in WORKING-STORAGE. The program can then be compiled and linked using your standard COBOL compiler. If your site uses single quotes (apostrophes) rather than double quotes (speech marks) to delimit alphanumeric literals, a global change of all double quotes to single quotes can be made before compilation. CALL statements to RCHASH can now be added to applications as required. Details on how to call RCHASH can be found in the Calling RCHASH section of this guide. A sample calling program (RCHACALL) is also included in the downloaded trial package. If you should encounter any problems during installation, please contact your account manager or use our Contact facility at: Note: Free trial versions of RCHASH have the following limitations: It expires after 30 days; It cannot be called more than 100 times in a single execution. Redvers Consulting Ltd Page 6

7 Calling RCHASH Parameters Redvers Hashing Algorithm - User Guide 2.3 A call to RCHASH requires two parameters in the following sequence: COMMUNICATION-BLOCK This group level field contains the following fixed length sub-parameter fields: Field Picture Input/ output Use ALGORITHM PIC 9(04) Input Hash algorithm to be used: 0001 = SHA = SHA bit 0256 = SHA bit 0384 = SHA bit 0512 = SHA bit 2224 = SHA-512/ bit 2256 = SHA-512/ bit 3224 = SHA bit 3256 = SHA bit 3384 = SHA bit 3512 = SHA bit 9999 = Repeat previous algorithm using additional message data. STRING-LENGTH PIC S9(8) COMP Input The length of message data to be hashed (stored in MESSAGE-STRING). HASH-BIN PIC X(128) Output Field that will contain the binary hash total after successful completion. The length of the hash total will depend on the algorithm chosen: 0001 = 20 bytes 0224 = 28 bytes 0256 = 32 bytes 0384 = 48 bytes 0512 = 64 bytes 2224 = 28 bytes 2256 = 32 bytes 3224 = 28 bytes 3256 = 32 bytes Redvers Consulting Ltd Page 7

8 3384 = 48 bytes 3512 = 64 bytes (Left justified). HASH-HEX PIC X(256) Output Field that will contain the same hash total as HASH-BIN, in hexadecimal format. (Left justified). HASH-B64 PIC X(172) Output Field that will contain the same hash total as HASH-BIN, in Base64 [5] format. (Left justified). FEEDBACK-CODE PIC S9(4) COMP Output Feedback message number indicating a successful (zero) or unsuccessful (not zero) call to RCHASH. See Feedback Messages for a full list of feedback codes and texts. FEEDBACK-TEXT PIC X(80) Output Message text relating to the FEEDBACK-CODE. See Feedback Messages for a full list of feedback codes and texts. MESSAGE-STRING This is the storage area containing the input message data to be hash totalled (left justified). It may be a group or elementary data item of any size supported by the site compiler. If a series of message strings are to be hashed (a sequential file of records for example), producing one hash total for the entire series/file, the ALGORITHM parameter must be set to 9999 for all calls after the first MESSAGE-STRING. Note: The parameter names used in this guide are suggestions only and may be changed to names more suitable to the application making the call. Redvers Consulting Ltd Page 8

9 Sample Program with a single Message String... WORKING-STORAGE SECTION. 01 CB-COMMUNICATION-BLOCK. 03 CB-ALGORITHM PIC 9(04). 88 CB-SHA-1 VALUE CB-SHA-224 VALUE CB-SHA-256 VALUE CB-SHA-384 VALUE CB-SHA-512 VALUE CB-SHA VALUE CB-SHA VALUE CB-SHA VALUE CB-SHA VALUE CB-SHA VALUE CB-SHA VALUE CB-REPEAT-SHA VALUE CB-STRING-LENGTH PIC S9(8) COMP. 03 CB-HASH-BIN PIC X(128). 03 CB-HASH-HEX PIC X(256). 03 CB-HASH-B64 PIC X(172). 03 CB-FEEDBACK-CODE PIC S9(4) COMP. 03 CB-FEEDBACK-TEXT PIC X(80). 01 MESSAGE-STRING PIC X(800). PROCEDURE DIVISION. TOP-LEVEL SECTION. ****************************************************************** * This section populates the calling parameter fields and * * message area before making the call to RCHASH. * ****************************************************************** TOP-ENTER. INITIALIZE SET CB-SHA-256 CB-COMMUNICATION-BLOCK. TO TRUE. MOVE 44 TO CB-STRING-LENGTH. MOVE "THE QUICK BROWN FOX JUMPS OVER THE LAZY DOG." TO MESSAGE-STRING. PERFORM A-CALL-RCHASH. * Send CB-HASH-BIN, CB-HASH-HEX or CB-HASH-B64 for reconciliation. STOP RUN. TOP-EXIT. EXIT. A-CALL-RCHASH SECTION. ****************************************************************** * This section makes the call to RCHASH checking the * * FEEDBACK-CODE for any problems. * ****************************************************************** Redvers Consulting Ltd Page 9

10 A-ENTER. CALL "RCHASH" USING CB-COMMUNICATION-BLOCK MESSAGE-STRING. IF CB-FEEDBACK-CODE = ZERO DISPLAY CB-FEEDBACK-TEXT ELSE DISPLAY "BAD RETURN FROM RCHASH - FEEDBACK CODE IS " CB-FEEDBACK-CODE DISPLAY CB-FEEDBACK-TEXT STOP RUN END-IF. A-EXIT. EXIT. Sample Program with multiple Message Strings... FD IN-FILE LABEL RECORDS STANDARD. 01 IN-RECORD PIC X(100).... WORKING-STORAGE SECTION. 01 CB-COMMUNICATION-BLOCK. 03 CB-ALGORITHM PIC 9(04). 88 CB-SHA-1 VALUE CB-SHA-224 VALUE CB-SHA-256 VALUE CB-SHA-384 VALUE CB-SHA-512 VALUE CB-SHA VALUE CB-SHA VALUE CB-SHA VALUE CB-SHA VALUE CB-SHA VALUE CB-SHA VALUE CB-REPEAT-SHA VALUE CB-STRING-LENGTH PIC S9(8) COMP. 03 CB-HASH-BIN PIC X(128). 03 CB-HASH-HEX PIC X(256). 03 CB-HASH-B64 PIC X(172). 03 CB-FEEDBACK-CODE PIC S9(4) COMP. 03 CB-FEEDBACK-TEXT PIC X(80). 01 WS-IN-FLAG PIC X VALUE SPACE. 88 END-OF-IN-FILE VALUE E. Redvers Consulting Ltd Page 10

11 PROCEDURE DIVISION. TOP-LEVEL SECTION. ****************************************************************** * This section populates the calling parameter fields, opens * * the input file and performs a call to RCHASH for each record * * on the input file. * ****************************************************************** TOP-ENTER. INITIALIZE SET CB-SHA-512 MOVE 100 OPEN INPUT IN-FILE. READ IN-FILE AT END SET END-OF-IN-FILE CB-COMMUNICATION-BLOCK. TO TRUE. TO CB-STRING-LENGTH. TO TRUE. PERFORM UNTIL END-OF-IN-FILE PERFORM A-CALL-RCHASH SET CB-REPEAT-SHA TO TRUE READ IN-FILE AT END SET END-OF-IN-FILE TO TRUE END-PERFORM. * Send CB-HASH-BIN, CB-HASH-HEX or CB-HASH-B64 for reconciliation. CLOSE IN-FILE. STOP RUN. TOP-EXIT. EXIT. A-CALL-RCHASH SECTION. ****************************************************************** * This section makes the call to RCHASH checking the * * FEEDBACK-CODE for any problems. * ****************************************************************** A-ENTER. CALL "RCHASH" USING CB-COMMUNICATION-BLOCK IN-RECORD. IF CB-FEEDBACK-CODE = ZERO DISPLAY CB-FEEDBACK-TEXT ELSE DISPLAY "BAD RETURN FROM RCHASH - FEEDBACK CODE IS " CB-FEEDBACK-CODE DISPLAY CB-FEEDBACK-TEXT STOP RUN END-IF. A-EXIT. EXIT. Redvers Consulting Ltd Page 11

12 Appendix A - Feedback Messages Zero Feedback code from RCHASH: SHA-9999 HASH TOTAL COMPUTED FORZZ,ZZZ,ZZ9 DATA BYTES. Error Feedback codes from RCHASH: Feedbk Code Feedback Text Reason 0103 PROCESSING EXCEPTION. PLEASE CONTACT REDVERS CONSULTING BINARY STORAGE REALIGNMENT REQUIRED. PLEASE CONTACT REDVERS CONSULTING INVALID ALGORITHM PARAMETER. An unexpected logical error has occurred. Please contact your account manager or use our Contact facility at: The compiled RCHASH object code has produced some non-standard binary field lengths. This may occur when compiler options are set to special installation requirements. Please ask your account manager to provide a binary realigned version of RCHASH or use our Contact facility at: RCHASH currently supports the SHA-1, SHA-2 and SHA-3 algorithm types. For SHA-2 and SHA-3, four hash total lengths are available: 224 bit, 256 bit, 384 bit or 512 bit. For the first call to RCHASH, the ALGORITHM parameter must be set as follows: 0001 for SHA-1, 0224 for SHA bit, 0256 for SHA bit, 0384 for SHA bit, 0512 for SHA bit, 2224 for SHA-512/224 (truncated), 2256 for SHA-512/256 (truncated), 3224 for SHA bit, 3256 for SHA bit, 3384 for SHA bit, 3512 for SHA bit. Subsequent calls may use the 9999 ALGORITHM setting to repeat the previous algorithm using additional data held in MESSAGE-STRING. Redvers Consulting Ltd Page 12

13 0180 INVALID ACTIVATION KEY. PLEASE PLACE YOUR ACTIVATION KEY IN THE LAST W.S. FIELD DAY TRIAL PERIOD EXPIRED OR CALL LIMIT REACHED When the Redvers Hashing Algorithm was ordered or downloaded, a 32 byte activation key should have been sent from Redvers Consulting to the ordering or downloading customer. This key should be copied into the VALUE literal of the last field coded in the WORKING-STORAGE SECTION. The program must then be compiled and linked into the calling application. Additional activation keys may be requested from your account manager or using our Contact facility at: The Redvers Hashing Algorithm can be downloaded or ordered on a free 30 day trial basis. Either the thirty days have now elapsed or the limit of 100 calls in a continuous execution has been reached. To purchase a fully functional perpetual product licence or to request an additional thirty day trial please contact your Redvers Consulting account manager or use our Contact facility at: Redvers Consulting Ltd Page 13

14 Appendix B - References [1] Redvers Encryption Device: [2] National Institute of Standards and Technology (NIST): [3] Federal Information Processing Standards Publication 180-4: [4] Redvers COBOL Cloaking Device: [5] Base64 from Wikipedia, the free encyclopedia: [6] The Keccak Reference (SHA-3): Redvers Consulting Ltd Page 14

15 Index A account manager, 6, 12, 13 activation key, 6, 13 algorithm, 5, 12 ALGORITHM, 7 apostrophes, 6 B Base64, 8, 14 batch, 5 binary, 12 byte-storage mode, 12 C Calling, 7 Cloaking Device, 6, 14 COBOL, 3, 5, 6 collision, 4 COMMUNICATION-BLOCK, 7 compile, 6 Contact, 6, 12, 13 copybooks, 6 D double quotes, 6 E Encryption Device, 14 F Feedback Messages, 12 FEEDBACK-CODE, 8 FEEDBACK-TEXT, 8 FIPS PUB 180-4, 4 H HASH-B64, 8 HASH-BIN, 7 HASH-HEX, 8 I intellectual property, 6 K Keccak Reference, 4, 14 L literals, 6 logical error, 12 M message, 7 message digest, 4, 5 MESSAGE-STRING, 7, 8 N NIST, 4, 14 O objects, 6 on-line, 5 P Parameters, 7 R RCHASH, 5, 6 References, 14 Redvers Consulting Ltd Page 15

16 S Sample Program, 9, 10 SHA-1, 4, 7, 12 SHA-2, 4, 7, 12 SHA-3, 4, 7, 12 single quotes, 6 source code, 6 speech marks, 6 STRING-LENGTH, 7, 8 sub-parameter, 7 T trial, 13 Redvers Consulting Ltd Page 16

17 Redvers Consulting Ltd 44 Broadway, London E15 1XH, UK