Upload
vankiet
View
268
Download
1
Embed Size (px)
Citation preview
Programmers Guide
Crypto Complete version: 3.50 Publication date: April 19
th, 2016
© Copyright 2007-2016, LINOMA SOFTWARE
LINOMA SOFTWARE is a division of LINOMA GROUP, Inc.
Crypto Complete
Version 3.50 Linoma Software Page 2
Table of Contents
Introduction ................................................................................................................... 5
Which APIs to use? ....................................................................................................... 6
Field Encryption Registry APIs .................................................................................................................. 6 Other Encryption APIs ............................................................................................................................... 7
ILE Procedure APIs for Encryption/Decryption .......................................................... 8
EncFld – Encrypt Field Value .................................................................................................................. 10 DecFld – Decrypt Field Value (Full value) ............................................................................................... 11 DecFldMask – Decrypt Field Value (Masked value) ............................................................................... 12 DecFldAuth – Decrypt Field Value (Authorized value) ............................................................................ 13 InsEncFld – Insert Encrypted Field Value into External File ................................................................... 15 UpdEncFld – Update Encrypted Field Value in External File .................................................................. 16 DltEncFld – Delete Encrypted Field Value from External File ................................................................. 17 GetEncFld – Get Decrypted Field Value from External File (Full value) ................................................. 18 GetEncFldMask – Get Decrypted Field Value from External File (Masked value) ................................. 19 GetEncFldAuth – Get Decrypted Field Value from External File (Authorized value) .............................. 20 GetFldAttr – Get Attributes for Field Identifier ......................................................................................... 22 GetActiveFldId – Get active Field Identifier from Registry ...................................................................... 24 GetEncFldKeyInf – Get Current Key information for Field Identifier ....................................................... 25 GetFirstFldKeyInf – Get First Key information for Field Identifier............................................................ 26 GetNextFldKeyInf – Get Next Key information for Field Identifier ........................................................... 27 GetExtFiLInf – Get External File Information for Field Identifier .............................................................. 28 GetFldIdx – Get Index for Field Value from External File ........................................................................ 29 CvtExtIdxDec – Convert Index Number from Character to Decimal ....................................................... 30 ReqKeyTkn – Request a token to a Key contained in a Key Store ......................................................... 31 RlsKeyTkn – Release a token to a Key ................................................................................................... 32 EncAES1 – Encrypt text with AES256 using Key Token (ECB block mode) .......................................... 33 DecAES1 – Decrypt text with AES256 using Key Token (ECB block mode) .......................................... 35 EncAES2 – Encrypt text with AES256 using Key Label (ECB block mode) ........................................... 36 DecAES2 – Decrypt text with AES256 using Key Label (ECB block mode) ........................................... 38 EncTDES1 – Encrypt text with TDES using Key Token (ECB block mode) ........................................... 40 DecTDES1 – Decrypt text with TDES using Key Token (ECB block mode) ........................................... 42 EncTDES2 – Encrypt text with TDES using Key Label (ECB block mode) ............................................ 43 DecTDES2 – Decrypt text with TDES using Key Label (ECB block mode) ............................................ 45 EncAdv3 – Encrypt text with Advanced options using Key Token .......................................................... 47 DecAdv3 – Decrypt text with Advanced options using Key Token.......................................................... 50 EncAdv4 – Encrypt text with Advanced options using Key Label ........................................................... 52 DecAdv4 – Decrypt text with Advanced options using Key Label ........................................................... 55 GenSha1Hash – Generate SHA1 Hash .................................................................................................. 57 GenHashValue – Generate Hash Value (MD5, SHA-1, SHA-256, SHA-384, SHA-512)........................ 58 VfyCRVL001 – Verify CRVL001 .............................................................................................................. 60 PtgEnc – Encrypt text in Protegrity format .............................................................................................. 61 PtgDec – Decrypt text from Protegrity format .......................................................................................... 63
Program APIs for Encryption/Decryption ................................................................. 65
CRRP615 – Encrypt Field Value ............................................................................................................. 67 CRRP616 – Decrypt Field Value (Full value) .......................................................................................... 68 CRRP639 – Decrypt Field Value (Masked value) ................................................................................... 69 CRRP637 – Decrypt Field Value (Authorized value) .............................................................................. 70 CRRP617 – Insert Encrypted Field Value into External File ................................................................... 71
Crypto Complete
Version 3.50 Linoma Software Page 3
CRRP618 – Update Encrypted Field Value in External File ................................................................... 72 CRRP619 – Delete Encrypted Field Value from External File ................................................................ 73 CRRP620 – Get Decrypted Field Value from External File (Full value) .................................................. 74 CRRP640 – Get Decrypted Field Value from External File (Masked value) ........................................... 75 CRRP638 – Get Decrypted Field Value from External File (Authorized value) ...................................... 76 CRRP631 – Get Attributes for Field Identifier ......................................................................................... 77 CRRP621 – Get active Field Identifier from Registry .............................................................................. 78 CRRP622 – Get Current Key information for Field Identifier .................................................................. 79 CRRP627 – Get First Key information for Field Identifier ....................................................................... 80 CRRP628 – Get Next Key information for Field Identifier ....................................................................... 81 CRRP625 – Get External File Information for Field Identifier ................................................................. 82 CRRP642 – Get Index for a Field Value from External File .................................................................... 83 CRRP626 – Convert Index Number from Character to Decimal ............................................................. 84 CRRP600 – Request a token to a Key contained in a Key Store ........................................................... 85 CRRP601 – Release a token to a Key .................................................................................................... 86 CRRP602 – Encrypt text with AES256 using Key Token (ECB block mode) ......................................... 87 CRRP603 – Decrypt text with AES256 using Key Token (ECB block mode) ......................................... 88 CRRP604 – Encrypt text with AES256 using Key Label (ECB block mode) .......................................... 89 CRRP605 – Decrypt text with AES256 using Key Label (ECB block mode) .......................................... 91 CRRP606 – Encrypt text with TDES using Key Token (ECB block mode) ............................................. 92 CRRP607 – Decrypt text with TDES using Key Token (ECB block mode) ............................................. 93 CRRP608 – Encrypt text with TDES using Key Label (ECB block mode) .............................................. 94 CRRP609 – Decrypt text with TDES using Key Label (ECB block mode) .............................................. 96 CRRP633 – Encrypt text with Advanced options using Key Token ........................................................ 97 CRRP634 – Decrypt text with Advanced options using Key Token ...................................................... 100 CRRP635 – Encrypt text with Advanced options using Key Label ....................................................... 102 CRRP636 – Decrypt text with Advanced options using Key Label ....................................................... 105 CRRP614 – Generate SHA1 Hash ....................................................................................................... 107 CRRP632 – Verify CRVL001................................................................................................................. 108 CRRP641 – Close External File ............................................................................................................ 109 CRRP643 – Generate Hash Value (MD5, SHA-1, SHA-256, SHA-384, SHA-512) .............................. 110
SQL Function APIs for Encryption/Decryption ....................................................... 112
F_EncFld – Encrypt Field Value ............................................................................................................ 113 F_DecFld – Decrypt Field Value (Full value) ......................................................................................... 114 F_DecFldMask – Decrypt Field Value (Masked value) ......................................................................... 115 F_DecFldAuth – Decrypt Field Value (Authorized value) ...................................................................... 116 F_InsEncFld – Insert Encrypted Field Value into External File - Decimal ............................................. 117 F_InsEncFldChr – Insert Encrypted Field Value into External File - Character .................................... 118 F_UpdEncFld – Update Encrypted Field Value in External File - Decimal ........................................... 119 F_UpdEncFldChr – Update Encrypted Field Value in External File - Character ................................... 120 F_DltEncFld – Delete Encrypted Field Value from External File - Decimal .......................................... 121 F_DltEncFldChr – Delete Encrypted Field Value from External File - Character .................................. 122 F_GetEncFld – Get Decrypted Field Value from External File – Decimal (Full value).......................... 123 F_GetEncFldChr – Get Decrypted Field Value from External File – Character (Full value) ................. 124 F_GetEncFldMask – Get Decrypted Field Value from External File – Decimal (Masked value) .......... 125 F_GetEncFldMaskChr – Get Decrypted Field Value from External File – Character (Masked value) . 126 F_GetEncFldAuth – Get Decrypted Field Value from External File – Decimal (Auth. Value) ............... 127 F_GetEncFldAuthChr – Get Decrypted Field Value from External File – Character (Auth. value) ....... 128 F_EncAES2 – Encrypt text with AES256 (ECB block mode) ................................................................ 129 F_DecAES2 – Decrypt text with AES256 (ECB block mode) ............................................................... 130 F_EncAdv – Encrypt text with Advanced options .................................................................................. 131 F_DecAdv – Decrypt text with Advanced options ................................................................................. 133
Crypto Complete
Version 3.50 Linoma Software Page 4
Stored Procedure APIs for Encryption/Decryption ................................................ 135
P_EncFld – Encrypt Field Value ............................................................................................................ 136 P_DecFld – Decrypt Field Value (Full value) ........................................................................................ 137 P_DecFldMask – Decrypt Field Value (Masked value) ......................................................................... 138 P_DecFldAuth – Decrypt Field Value (Authorized value) ..................................................................... 139 P_InsEncFld – Insert Encrypted Field Value into External File ............................................................. 140 P_UpdEncFld – Update Encrypted Field Value in External File ........................................................... 141 P_DltEncFld – Delete Encrypted Field Value from External File .......................................................... 142 P_GetEncFld – Get Decrypted Field Value from External File (Full value) .......................................... 143 P_GetEncFldMask – Get Decrypted Field Value from External File (Masked value) ........................... 144 P_GetEncFldAuth – Get Decrypted Field Value from External File (Authorized value)........................ 145 P_GetFldIdx – Get Index for a Field Value from External File .............................................................. 146 P_EncAES2 – Encrypt text with AES256 using Key Label (ECB block mode) ..................................... 147 P_DecAES2 – Decrypt text with AES256 using Key Label (ECB block mode) .................................... 148 P_EncAdv – Encrypt text with Advanced options using Key Label ....................................................... 149 P_DecAdv – Decrypt text with Advanced options using Key Label ...................................................... 151
Deprecated APIs ........................................................................................................ 153
License agreement and limited warranty ................................................................ 154
Contacting Linoma Software .................................................................................... 155
Crypto Complete
Version 3.50 Linoma Software Page 5
Introduction
Crypto Complete is a comprehensive solution for protecting sensitive data on the IBM i (iSeries) through strong encryption technology and integrated key management. This Programmers Guide explains the procedures, programs and functions (APIs) which are included with Crypto Complete. These APIs can be called from within your applications for encrypting and decrypting data. ILE procedure APIs are provided in Crypto Complete for encrypting/decrypting data withing ILE languages such as ILE RPG, ILE COBOL and ILE C. These ILE procedures offer high performance and can be used within expressions. Program APIs are additionally offered in Crypto Complete. These program APIs offer the same functionality as the ILE procedures APIs, but are intended for developers who are more comfortable with calling programs (instead of procedures) using traditional syntax. SQL Function APIs are also included in Crypto Complete for encrypting and decrypting data. These functions are intended for use within SQL SELECT, INSERT and UPDATE statements. Stored Procedure APIs can additionally be used in Crypto Complete to encrypt and decrypt data from within SQL CALL statements. Note: Read the Installation and Users Guide for information on how to utilize Crypto Complete’s commands and screens.
Crypto Complete
Version 3.50 Linoma Software Page 6
Which APIs to use?
Field Encryption Registry APIs
Listed below are the APIs which can be utilized for fields which are registered in Crypto Complete’s Field Encryption Registry. The applicable APIs depend on if SQL Triggers or DB2 Field Procedures are used, and whether the encrypted field values are stored in a separate external file or are stored in the existing database field.
Encryption APIs (if not using SQL Triggers or DB2 Field Procedures to auto-encrypt the field values)
ILE Procedures and Programs:
Values Stored in External File?
ILE Procedures
Programs
Comments
Yes InsEncFld UpdEncFld DltEncFld
CRRP617 CRRP618 CRRP619
Inserts encrypted value into ext. file Updates encrypted value in ext. file Deletes encrypted value from ext. file
No EncFld CRRP615 Encrypts field value (for storing internally)
SQL Functions and Stored Procedures:
Values Stored in External File?
SQL Functions (if numeric data)
SQL Functions (if alpha data)
Stored Procedures
Yes F_InsEncFld F_UpdEncFld F_DltEncFld
F_InsEncFldChr F_UpdEncFldChr F_DltEncFldChr
P_InsEncFld P_UpdEncFld P_DltEncFld
No * not applicable * F_EncFld P_EncFld
Decryption APIs (if not using DB2 Field Procedures to auto-decrypt the field values)
ILE Procedures and Programs:
Values Stored in External File?
ILE Procedures
Programs
Comments
Yes GetEncFld GetEncFldMask GetEncFldAuth
CRRP620 CRRP640 CRRP638
Returns full decrypted value Returns masked value Returns authorized value (full or masked)
No DecFld DecFldMask DecFldAuth
CRRP616 CRRP639 CRRP637
Returns full decrypted value Returns masked value Returns authorized value (full or masked)
SQL Functions and Stored Procedures:
Values Stored in External File?
SQL Functions (if numeric data)
SQL Functions (if alpha data)
Stored Procedures
Yes F_GetEncFld F_GetEncFldMask F_GetEncFldAuth
F_GetEncFldChr F_GetEncFldMaskChr F_GetEncFldAuthChr
P_GetEncFld P_GetEncFldMask P_GetEncFldAuth
No * not applicable * F_DecFld F_DecFldMask F_DecFldAuth
P_DecFld P_DecFldMask P_DecFldAuth
Crypto Complete
Version 3.50 Linoma Software Page 7
Other Encryption APIs
If the Field Encryption Registry is not utilized, then you can use the APIs below to encrypt and decrypt values from within your applications. The applicable APIs depend on the encryption algorithm and whether a Key Token or Key Label will be used for the encryption/decryption processes.
AES with standard options
Use Key Token or Label?
ILE Procedures
Programs
SQL Functions
Stored Procedures
Key Token ReqKeyTkn RlsKeyTkn EncAES1 DecAES1
CRRP600 CRRP601 CRRP602 CRRP603
Key Label EncAES2 DecAES2
CRRP604 CRRP605
F_EncAES2 F_DecAES2
P_EncAES2 P_DecAES2
TDES with standard options
Use Key Token or Label?
ILE Procedures
Programs
Key Token ReqKeyTkn RlsKeyTkn EncTDES1 DecTDES1
CRRP600 CRRP601 CRRP606 CRRP607
Key Label EncTDES2 DecTDES2
CRRP608 CRRP609
AES or TDES with Advanced Options
Use Key Token or Label?
ILE Procedures
Programs
SQL Functions
Stored Procedures
Key Token ReqKeyTkn RlsKeyTkn EncAdv3 DecAdv3
CRRP600 CRRP601 CRRP633 CRRP634
Key Label EncAdv4 DecAdv4
CRRP635 CRRP636
F_EncAdv F_DecAdv
P_EncAdv P_DecAdv
Protegrity compatible format
Use Key Token or Label?
ILE Procedures
Key Label PtgEnc PtgDec
Crypto Complete
Version 3.50 Linoma Software Page 8
ILE Procedure APIs for Encryption/Decryption Crypto Complete includes ILE Procedure APIs which can be called for encrypting and decrypting text and field values from within ILE programs (ILE RPG, ILE COBOL, ILE C) on the IBM i. These ILE Procedures are contained in Service Program (*SRVPGM) objects within the CRYPTO library. During the compilation of your application’s program, you can either bind to the Service Program(s) needed or you can specify the binding directory CRYPTO/CRYPTO. The prototypes for the ILE Procedures are included in the source file CRYPTO/QCPYLESRC. ILE Procedure APIs if using Field Encryption Registry:
Name Description Service Program
EncFld Encrypt field value using Registry CRSP505
DecFld Decrypt field value using Registry (full value) CRSP505
DecFldMask Decrypt field value using Registry (masked value) CRSP505
DecFldAuth Decrypt field value using Registry (auth. value) CRSP505
InsEncFld Encrypt and insert field value into external file CRSP505
UpdEncFld Encrypt and update field value in external file CRSP505
DltEncFld Delete encrypted field value from external file CRSP505
GetEncFld Get decrypted field value from external file (full value) CRSP505
GetEncFldMask Get decrypted field value from external file (masked value) CRSP505
GetEncFldAuth Get decrypted field value from external file (auth. value) CRSP505
GetFldAttr Get Field Attributes from Registry CRSP505
GetActiveFldId Get active Field Identifier from Registry CRSP505
GetEncFldKeyInf Get Current Key information for Field Identifier CRSP505
GetFirstFldKeyInf Get First Key information for Field Identifier CRSP505
GetNextFldKeyInf Get Next Key information for Field Identifier CRSP505
GetExtFiLInf Get External File Information for Field Identifier CRSP505
GetFldIdx Get External Index for Field Value from External File CRSP513
CvtExtIdxDec Convert Index Number from Character to Decimal CRSP505
Crypto Complete
Version 3.50 Linoma Software Page 9
Other ILE procedures:
Name Description Service Program
ReqKeyTkn Request a token to a Key contained in a Key Store CRSP500
RlsKeyTkn Release a token to a Key CRSP500
EncAES1 Encrypt text with AES256 using Key token (ECB block mode) CRSP501
DecAES1 Decrypt text with AES256 using Key token (ECB block mode) CRSP501
EncAES2 Encrypt text with AES256 using Key label (ECB block mode) CRSP501
DecAES2 Decrypt text with AES256 using Key label (ECB block mode) CRSP501
EncTDES1 Encrypt text with TDES using Key token (ECB block mode) CRSP504
DecTDES1 Decrypt text with TDES using Key token (ECB block mode) CRSP504
EncTDES2 Encrypt text with TDES using Key label (ECB block mode) CRSP504
DecTDES2 Decrypt text with TDES using Key label (ECB block mode) CRSP504
EncAdv3 Encrypt text with Advanced options using Key token CRSP510
DecAdv3 Decrypt text with Advanced options using Key token CRSP510
EncAdv4 Encrypt text with Advanced options using Key label CRSP510
DecAdv4 Decrypt text with Advanced options using Key label CRSP510
GenSha1Hash Generate a SHA1 hash CRSP503
GenHashValue Generate an MD5, SHA-1, SHA-256, SHA-384 or SHA512 Hash Value
CRSP503
VfyCRVL001 Verify CRVL001 object CRSP509
PtgEnc Encrypt text in Protegrity format CRSP512
PtgDec Decrypt text from Protegrity format CRSP512
Crypto Complete
Version 3.50 Linoma Software Page 10
EncFld – Encrypt Field Value
The EncFld procedure will encrypt a field value using the settings specified in the Field Encryption Registry. This procedure should only be used if all of the following conditions are met:
The field is registered and *ACTIVE in the Encryption Registry
Triggers are not used to automatically encrypt the field values
The encrypted values are not stored in an external file Procedure name: EncFld Bind to Service Program: CRSP505 Prototype source member: @CRSP505 in CRYPTO/QCPYLESRC source file Parameters for EncFld procedure:
Name Description Type Length In/Out Required
FldId Field identifier Alpha 30 In Yes
PlainText Plain Text Alpha 32624 In Yes
LogCmt Audit Log Comment Alpha 50 In No
CipherText Encrypted Text Alpha 32624 Out
MsgId Message Id Alpha 7 Out
MsgText Message Text Alpha 80 Out
Return value: *ON if successful, *OFF if errors Example in /Free form RPG:
H BNDDIR('CRYPTO/CRYPTO') DFTACTGRP(*NO)
D/COPY CRYPTO/QCPYLESRC,@CRSP505
/FREE
// Encrypt value in CreditCardValue using registry field id CCFIELD
If EncFld (‘CCFIELD’
:CreditCardValue
:LogCmt
:EncryptedValue
:MsgId
:MsgText);
// Success-> The encrypted value is in EncryptedValue variable
… logic …
Else;
// Errors-> Display MsgId and MsgText values
… logic …
Endif;
/END-FREE
Crypto Complete
Version 3.50 Linoma Software Page 11
DecFld – Decrypt Field Value (Full value)
The DecFld procedure will decrypt a field value using the settings specified in the Field Encryption Registry.
The user will be authorized to the full decrypted value if they have 1) at least *USE authority to the ‘Full’ Authorization List specified for the field and 2) at least *USE authority to the Key Store which holds the Decryption Key. The names of the Authorization List and Key Store can be found for the field identifier in the Encryption Registry.
This procedure should only be used if all of the following conditions are met:
The field is registered and *ACTIVE in the Encryption Registry
The encrypted values are not stored in an external file Procedure name: DecFld Bind to Service Program: CRSP505 Prototype source member: @CRSP505 in CRYPTO/QCPYLESRC source file Parameters for DecFld procedure:
Name Description Type Length In/Out Required
FldId Field identifier Alpha 30 In Yes
CipherText Encrypted Text Alpha 32624 In Yes
LogCmt Audit Log Comment Alpha 50 In No
PlainText Plain Text Alpha 32624 Out
MsgId Message Id Alpha 7 Out
MsgText Message Text Alpha 80 Out
Return value: *ON if successful, *OFF if errors Example in /Free form RPG:
H BNDDIR('CRYPTO/CRYPTO') DFTACTGRP(*NO)
D/COPY CRYPTO/QCPYLESRC,@CRSP505
/FREE
// Decrypt value in EncryptedValue using registry field id CCFIELD
If DecFld (‘CCFIELD’
:EncryptedValue
:LogCmt
:CreditCardValue
:MsgId
:MsgText);
// Success-> The decrypted value is in CreditCardValue variable
… logic …
Else;
// Errors-> Display MsgId and MsgText values
… logic …
Endif;
/END-FREE
Crypto Complete
Version 3.50 Linoma Software Page 12
DecFldMask – Decrypt Field Value (Masked value)
The DecFldMask procedure will decrypt a field value and apply a mask, based on the settings specified in the Field Encryption Registry. For instance, if a mask of ‘************9999’ is specified in the Registry for a credit card number, then a sample of a returned credit card number would be ‘************1234’.
The user will be authorized to the masked value if they have 1) at least *USE authority to the ‘Masked’ Authorization List specified for the field and 2) at least *USE authority to the Key Store which holds the Decryption Key. The names of the Authorization List and Key Store can be found for the field identifier in the Encryption Registry.
This procedure should only be used if all of the following conditions are met:
The field is registered and *ACTIVE in the Encryption Registry
The field has a mask value specified in the Encryption Registry
The encrypted values are not stored in an external file Procedure name: DecFldMask Bind to Service Program: CRSP505 Prototype source member: @CRSP505 in CRYPTO/QCPYLESRC source file Parameters for DecFldMask procedure:
Name Description Type Length In/Out Required
FldId Field identifier Alpha 30 In Yes
CipherText Encrypted Text Alpha 32624 In Yes
LogCmt Audit Log Comment Alpha 50 In No
PlainText Plain Text (masked) Alpha 32624 Out
MsgId Message Id Alpha 7 Out
MsgText Message Text Alpha 80 Out
Return value: *ON if successful, *OFF if errors Example in /Free form RPG:
H BNDDIR('CRYPTO/CRYPTO') DFTACTGRP(*NO)
D/COPY CRYPTO/QCPYLESRC,@CRSP505
/FREE
// Process value in EncryptedValue using registry field id CCFIELD
If DecFldMask (‘CCFIELD’
:EncryptedValue
:LogCmt
:MaskedValue
:MsgId
:MsgText);
// Success-> The decrypted masked value is in the MaskedValue variable
… logic …
Else;
// Errors-> Display MsgId and MsgText values
… logic …
Endif;
/END-FREE
Note: If a mask is not specified for the Field in the Registry, then no value will be returned.
Crypto Complete
Version 3.50 Linoma Software Page 13
DecFldAuth – Decrypt Field Value (Authorized value) Based on the user’s authority to the field, the DecFldAuth procedure will return either 1) the fully decrypted value for the field or 2) the masked value for the field or 3) the not-authorized fill value that is specified for the field in the Registry, which may be blanks. The user’s authority to the field is determined by checking the Authority Lists indicated on the field’s AUTLDEC and AUTLMASK settings that are specified in the Field Encryption Registry. If a masked value is returned, the mask will be based on the field’s FLDMASK setting that is specified in the Field Encryption Registry. This procedure should only be used if all of the following conditions are met:
The field is registered and *ACTIVE in the Encryption Registry
The encrypted values are not stored in an external file Procedure name: DecFldAuth Bind to Service Program: CRSP505 Prototype source member: @CRSP505 in CRYPTO/QCPYLESRC source file Parameters for DecFldAuth procedure:
Name Description Type Length In/Out Required
FldId Field identifier Alpha 30 In Yes
CipherText Encrypted Text Alpha 32624 In Yes
LogCmt Audit Log Comment Alpha 50 In No
OutputText Output Text Alpha 32624 Out
MsgId Message Id Alpha 7 Out
MsgText Message Text Alpha 80 Out
Return value: *ON if successful, *OFF if errors (see source example on next page)
Note: The user will additionally need at least *USE authority to the Key Store object which holds the key needed for decryption.
Crypto Complete
Version 3.50 Linoma Software Page 14
DecFldAuth example in /Free form RPG:
H BNDDIR('CRYPTO/CRYPTO') DFTACTGRP(*NO)
D/COPY CRYPTO/QCPYLESRC,@CRSP505
/FREE
// Decrypt value in EncryptedValue using registry field id CCFIELD
If DecFldAuth (‘CCFIELD’
:EncryptedValue
:LogCmt
:OutputValue
:MsgId
:MsgText);
// Success-> The returned value is in the OutputValue variable.
// Based on the user’s authorities, it returns either the fully
// decrypted value, the masked value or a fill/blank value
… logic …
Else;
// Errors-> Display MsgId and MsgText values
… logic …
Endif;
/END-FREE
Crypto Complete
Version 3.50 Linoma Software Page 15
InsEncFld – Insert Encrypted Field Value into External File
The InsEncFld procedure will encrypt a field value and then insert it into the external file specified in the Field Encryption Registry. This procedure should only be used if all of the following conditions are met:
The field is registered and *ACTIVE in the Encryption Registry
Triggers are not used to automatically encrypt the field values
The encrypted values are stored in an external file Procedure name: InsEncFld Bind to Service Program: CRSP505 Prototype source member: @CRSP505 in CRYPTO/QCPYLESRC source file Parameters for InsEncFld procedure:
Name Description Type Length In/Out Required
FldId Field identifier Alpha 30 In Yes
PlainText Plain Text Alpha 32624 In Yes
LogCmt Audit Log Comment Alpha 50 In No
ExtIndex Index number of value Packed 13,0 Out
MsgId Message Id Alpha 7 Out
MsgText Message Text Alpha 80 Out
Return value: *ON if successful, *OFF if errors Example in /Free form RPG:
H BNDDIR('CRYPTO/CRYPTO') DFTACTGRP(*NO)
D/COPY CRYPTO/QCPYLESRC,@CRSP505
/FREE
// Encrypt value in CreditCardValue and insert into external file
If InsEncFld (‘CCFIELD’
:CreditCardValue
:LogCmt
:ExtIndex
:MsgId
:MsgText);
// Success-> Store the ExtIndex (index number) in existing DB field
… logic …
Else;
// Errors-> Display MsgId and MsgText values
… logic …
Endif;
/END-FREE
Crypto Complete
Version 3.50 Linoma Software Page 16
UpdEncFld – Update Encrypted Field Value in External File
The UpdEncFld procedure will encrypt a field value and then update the record in the external file with this encrypted value. The name of the external file is specified in the Field Encryption Registry. This procedure should only be used if all of the following conditions are met:
The field is registered and *ACTIVE in the Encryption Registry
Triggers are not used to automatically encrypt the field values
The encrypted values are stored in an external file Procedure name: UpdEncFld Bind to Service Program: CRSP505 Prototype source member: @CRSP505 in CRYPTO/QCPYLESRC source file Parameters for UpdEncFld procedure:
Name Description Type Length In/Out Required
FldId Field identifier Alpha 30 In Yes
ExtIndex Index number of value Packed 13,0 In Yes
PlainText Plain Text Alpha 32624 In Yes
LogCmt Audit Log Comment Alpha 50 In No
MsgId Message Id Alpha 7 Out
MsgText Message Text Alpha 80 Out
Return value: *ON if successful, *OFF if errors Example in /Free form RPG:
H BNDDIR('CRYPTO/CRYPTO') DFTACTGRP(*NO)
D/COPY CRYPTO/QCPYLESRC,@CRSP505
/FREE
// Convert the index number (stored in ccno) from alphanumeric to decimal
ExtIndex = %dec(ccno:16:0);
// Using the index specified in ExtIndex, encrypt value in
// CreditCardValue and update record in external file
If UpdEncFld (‘CCFIELD’
:ExtIndex
:CreditCardValue
:LogCmt
:MsgId
:MsgText);
// Success-> Encrypted value was stored
… logic …
Else;
// Errors-> Display MsgId and MsgText values
… logic …
Endif;
/END-FREE
Crypto Complete
Version 3.50 Linoma Software Page 17
DltEncFld – Delete Encrypted Field Value from External File
The DltEncFld procedure will remove the encrypted field value from the external file. The name of the external file is specified in the Field Encryption Registry. This procedure should only be used if all of the following conditions are met:
The field is registered and *ACTIVE in the Encryption Registry
Triggers are not used to automatically encrypt the field values
The encrypted values are stored in an external file Procedure name: DltEncFld Bind to Service Program: CRSP505 Prototype source member: @CRSP505 in CRYPTO/QCPYLESRC source file Parameters for DltEncFld procedure:
Name Description Type Length In/Out Required
FldId Field identifier Alpha 30 In Yes
ExtIndex Index number of value Packed 13,0 In Yes
MsgId Message Id Alpha 7 Out
MsgText Message Text Alpha 80 Out
Return value: *ON if successful, *OFF if errors Example in /Free form RPG:
H BNDDIR('CRYPTO/CRYPTO') DFTACTGRP(*NO)
D/COPY CRYPTO/QCPYLESRC,@CRSP505
/FREE
// Convert the index number (stored in ccno) from alphanumeric to decimal
ExtIndex = %dec(ccno:16:0);
// Using the index specified in ExtIndex, remove the encrypted value
// from the external file
If DltEncFld (‘CCFIELD’
:ExtIndex
:MsgId
:MsgText);
// Success-> Encrypted value was removed
… logic …
Else;
// Errors-> Display MsgId and MsgText values
… logic …
Endif;
/END-FREE
Crypto Complete
Version 3.50 Linoma Software Page 18
GetEncFld – Get Decrypted Field Value from External File (Full value)
The GetEncFld procedure will retrieve an encrypted field value from an external file and decrypt it for use in the application. The name of the external file is specified in the Field Encryption Registry.
The user will be authorized to the full decrypted value if they have 1) at least *USE authority to the ‘Full’ Authorization List specified for the field and 2) at least *USE authority to the Key Store which holds the Decryption Key. The names of the Authorization List and Key Store can be found for the field identifier in the Encryption Registry.
This procedure should only be used if all of the following conditions are met:
The field is registered and *ACTIVE in the Encryption Registry
The encrypted values are stored in an external file Procedure name: GetEncFld Bind to Service Program: CRSP505 Prototype source member: @CRSP505 in CRYPTO/QCPYLESRC source file Parameters for GetEncFld procedure:
Name Description Type Length In/Out Required
FldId Field identifier Alpha 30 In Yes
ExtIndex Index number of value Packed 13,0 In Yes
LogCmt Audit Log Comment Alpha 50 In No
PlainText Plain Text Alpha 32624 Out
MsgId Message Id Alpha 7 Out
MsgText Message Text Alpha 80 Out
Return value: *ON if successful, *OFF if errors Example in /Free form RPG:
H BNDDIR('CRYPTO/CRYPTO') DFTACTGRP(*NO)
D/COPY CRYPTO/QCPYLESRC,@CRSP505
/FREE
// Convert the index number (stored in ccno) from alphanumeric to decimal
ExtIndex = %dec(ccno:16:0);
// Using the index specified in ExtIndex, retrieve the value from
// external file, decrypt and return it.
If GetEncFld (‘CCFIELD’
:ExtIndex
:LogCmt
:CreditCardValue
:MsgId
:MsgText);
// Success-> The decrypted value is in CreditCardValue variable
… logic …
Else;
// Errors-> Display MsgId and MsgText values
… logic …
Endif;
/END-FREE
Crypto Complete
Version 3.50 Linoma Software Page 19
GetEncFldMask – Get Decrypted Field Value from External File (Masked value)
The GetEncFldMask procedure will retrieve an encrypted field value from an external file, then decrypt it and apply a mask, based on the settings specified in the Field Encryption Registry. For instance, if a mask of ‘************9999’ is specified in the Registry for a credit card number, then a sample of a returned credit card number would be ‘************1234’.
The user will be authorized to the masked value if they have 1) at least *USE authority to the ‘Masked’ Authorization List specified for the field and 2) at least *USE authority to the Key Store which holds the Decryption Key. The names of the Authorization List and Key Store can be found for the field identifier in the Encryption Registry.
This procedure should only be used if all of the following conditions are met:
The field is registered and *ACTIVE in the Encryption Registry
The field has a mask value specified in the Encryption Registry
The encrypted values are stored in an external file Procedure name: GetEncFldMask Bind to Service Program: CRSP505 Prototype source member: @CRSP505 in CRYPTO/QCPYLESRC source file Parameters for GetEncFldMask procedure:
Name Description Type Length In/Out Required
FldId Field identifier Alpha 30 In Yes
ExtIndex Index number of value Packed 13,0 In Yes
LogCmt Audit Log Comment Alpha 50 In No
PlainText Plain Text (masked) Alpha 32624 Out
MsgId Message Id Alpha 7 Out
MsgText Message Text Alpha 80 Out
Return value: *ON if successful, *OFF if errors Example in /Free form RPG:
H BNDDIR('CRYPTO/CRYPTO') DFTACTGRP(*NO)
D/COPY CRYPTO/QCPYLESRC,@CRSP505
/FREE // Convert the index number (stored in ccno) from alphanumeric to decimal
ExtIndex = %dec(ccno:16:0);
// Using the index specified in ExtIndex, retrieve the value from
// external file, decrypt, mask and return it.
If GetEncFldMask (‘CCFIELD’
:ExtIndex
:LogCmt
:MaskedValue
:MsgId
:MsgText);
// Success-> The decrypted masked value is in the MaskedValue variable
… logic …
Else;
// Errors-> Display MsgId and MsgText values
… logic …
Endif;
/END-FREE
Crypto Complete
Version 3.50 Linoma Software Page 20
GetEncFldAuth – Get Decrypted Field Value from External File (Authorized value)
The GetEncFldAuth procedure can be used if the encrypted field values are stored in an external file. Based on the user’s authority to the field, the GetEncFldAuth procedure will return either 1) the fully decrypted value for the field or 2) the masked value for the field or 3) the not-authorized fill value that is specified for the field in the Registry, which may be blanks. The user’s authority to the field is determined by checking the Authority Lists indicated on the field’s AUTLDEC and AUTLMASK settings that are specified in the Field Encryption Registry. If a masked value is returned, the mask will be based on the field’s FLDMASK setting that is specified in the Field Encryption Registry. This procedure should only be used if all of the following conditions are met:
The field is registered and *ACTIVE in the Encryption Registry
The encrypted values are stored in an external file Procedure name: GetEncFldAuth Bind to Service Program: CRSP505 Prototype source member: @CRSP505 in CRYPTO/QCPYLESRC source file Parameters for GetEncFldAuth procedure:
Name Description Type Length In/Out Required
FldId Field identifier Alpha 30 In Yes
ExtIndex Index number of value Packed 13,0 In Yes
LogCmt Audit Log Comment Alpha 50 In No
OutputText Output Text Alpha 32624 Out
MsgId Message Id Alpha 7 Out
MsgText Message Text Alpha 80 Out
Return value: *ON if successful, *OFF if errors (see source example on next page)
Note: The users (or user groups) which should have access to the decrypted (or masked) values will also need at least *USE authority to the Key Store object which holds the Decryption Key.
Crypto Complete
Version 3.50 Linoma Software Page 21
GetEncFldAuth example in /Free form RPG:
H BNDDIR('CRYPTO/CRYPTO') DFTACTGRP(*NO)
D/COPY CRYPTO/QCPYLESRC,@CRSP505
/FREE
// Convert the index number (stored in ccno) from alphanumeric to decimal
ExtIndex = %dec(ccno:16:0);
// Using the index specified in ExtIndex, retrieve the encrypted value
// from the external file. Based on the user’s authorities, it returns
// either the fully decrypted value, the masked value or a fill/blank
// value.
If GetEncFldAuth (‘CCFIELD’
:ExtIndex
:LogCmt
:OutputValue
:MsgId
:MsgText);
// Success-> The returned value is in the OutputValue variable
… logic …
Else;
// Errors-> Display MsgId and MsgText values
… logic …
Endif;
/END-FREE
Crypto Complete
Version 3.50 Linoma Software Page 22
GetFldAttr – Get Attributes for Field Identifier
The GetFldAttr procedure will return certain attributes for the specified Field, such as the field status, mask value, database field type, length and decimal positions. This information will be retrieved from the Field Encryption Registry. Procedure name: GetFldAttr Bind to Service Program: CRSP505 Prototype source member: @CRSP505 in CRYPTO/QCPYLESRC source file Parameters for GetFldAttr procedure:
Name Description Type Length In/Out Required
FldId Field identifier Alpha 30 In Yes
Attribute Attribute name 1 Alpha 30 In Yes
Value Value 2 Alpha 30 Out
MsgId Message Id Alpha 7 Out
MsgText Message Text Alpha 80 Out
Return value: *ON if successful, *OFF if errors Parameter Notes:
1 Specify the type of attribute to retrieve for the field:
*CIPHERLEN – The calculated length of the encrypted value.
*FLDDEC – The number of decimal positions for the database field.
*FLDLEN – The length of the database field.
*FLDTYP – The type of the database field. Possible returned values are *CHAR and *DEC.
*MASK – The masked value for the field
*STATUS – The status of the field in the registry. Possible returned values are *ACTIVE, *INACTIVE, *ERROR, *PROCESS and *UNKNOWN.
2 The value returned for the attribute
(See source example on next page)
Crypto Complete
Version 3.50 Linoma Software Page 23
GetFldAttr example in /Free form RPG:
H BNDDIR('CRYPTO/CRYPTO') DFTACTGRP(*NO)
D/COPY CRYPTO/QCPYLESRC,@CRSP505
/FREE
// Get the status for field id ‘CCFIELD’
If GetFldAttr (‘CCFIELD’
:‘*STATUS’
:FldValue
:MsgId
:MsgText);
// Success-> The status of the field is in FldValue.
… logic …
Else;
// Errors-> Display MsgId and MsgText values
… logic …
Endif;
/END-FREE
Crypto Complete
Version 3.50 Linoma Software Page 24
GetActiveFldId – Get active Field Identifier from Registry
The GetActiveFldId procedure will retrieve the name of the active Field Identifier (within the Encryption Registry) for the specified database field name, file name and library. This procedure is useful if you know the database field name and you want to programmatically determine its corresponding Field Identifier to use for the Field APIs (such as GetEncFld). Procedure name: GetActiveFldId Bind to Service Program: CRSP505 Prototype source member: @CRSP505 in CRYPTO/QCPYLESRC source file Parameters for GetActiveFldId procedure:
Name Description Type Length In/Out Required
DbFld Database field name Alpha 30 In Yes
DbFile Database file name Alpha 10 In Yes
DbLib Database library name Alpha 10 In Yes
FldId Field identifier Alpha 30 Out
MsgId Message Id Alpha 7 Out
MsgText Message Text Alpha 80 Out
Return value: *ON if successful, *OFF if errors Example in /Free form RPG:
H BNDDIR('CRYPTO/CRYPTO') DFTACTGRP(*NO)
D/COPY CRYPTO/QCPYLESRC,@CRSP505
/FREE
// Get the active Field Identifier for the database field CCNO in
// the file OELIB/ORDERS.
If GetActiveFldId (‘CCNO’
:‘ORDERS’
:‘OELIB’
:FldId
:MsgId
:MsgText);
// Success-> The Field Identifier name is in the FldId variable
… logic …
Else;
// Errors-> Display MsgId and MsgText values
… logic …
Endif;
/END-FREE
Crypto Complete
Version 3.50 Linoma Software Page 25
GetEncFldKeyInf – Get Current Key information for Field Identifier
The GetEncFldKeyInf procedure will retrieve the current set of encryption/decryption Key Labels and Key Store names for the specified Field Identifier. This information will be retrieved from the Field Encryption Registry. This procedure is useful if you want to programmatically determine the current Keys to use for encryption/decryption APIs (such as EncAES2). Procedure name: GetEncFldKeyInf Bind to Service Program: CRSP505 Prototype source member: @CRSP505 in CRYPTO/QCPYLESRC source file Parameters for GetEncFldKeyInf procedure:
Name Description Type Length In/Out Required
FldId Field identifier Alpha 30 In Yes
EncKeyStrNam Encryption Key Store Name Alpha 10 Out
EncKeyStrLib Encryption Key Store Library Alpha 10 Out
EncKeyLabel Encryption Key Label Alpha 30 Out
DecKeyStrNam Decryption Key Store Name Alpha 10 Out
DecKeyStrLib Decryption Key Store Library Alpha 10 Out
DecKeyLabel Decryption Key Label Alpha 30 Out
MsgId Message Id Alpha 7 Out
MsgText Message Text Alpha 80 Out
Return value: *ON if successful, *OFF if errors Example in /Free form RPG:
H BNDDIR('CRYPTO/CRYPTO') DFTACTGRP(*NO)
D/COPY CRYPTO/QCPYLESRC,@CRSP505
/FREE
// Get the current Key Labels and Key Stores used for field id ‘CCFIELD’
If GetEncFldKeyInf (‘CCFIELD’
:EncKeyStrNam
:EncKeyStrLib
:EncKeyLabel
:DecKeyStrNam
:DecKeyStrLib
:DecKeyLabel
:MsgId
:MsgText);
// Success-> Current Keys found
… logic …
Else;
// Errors-> Display MsgId and MsgText values
… logic …
Endif;
/END-FREE
Crypto Complete
Version 3.50 Linoma Software Page 26
GetFirstFldKeyInf – Get First Key information for Field Identifier
The GetFirstFldKeyInf procedure will retrieve the first set of encryption/decryption Key Labels and Key Store names used for the specified Field Identifier. This information will be retrieved from the Field Encryption Registry. If field values are still encrypted under older (non-current) Keys, this procedure is useful to programmatically determine the Keys to use for decryption APIs (such as DecAES2). Procedure name: GetFirstFldKeyInf Bind to Service Program: CRSP505 Prototype source member: @CRSP505 in CRYPTO/QCPYLESRC source file Parameters for GetFirstFldKeyInf procedure:
Name Description Type Length In/Out Required
FldId Field identifier Alpha 30 In Yes
KeyId Key identifier Signed 5,0 Out
EncKeyStrNam Encryption Key Store Name Alpha 10 Out
EncKeyStrLib Encryption Key Store Library Alpha 10 Out
EncKeyLabel Encryption Key Label Alpha 30 Out
DecKeyStrNam Decryption Key Store Name Alpha 10 Out
DecKeyStrLib Decryption Key Store Library Alpha 10 Out
DecKeyLabel Decryption Key Label Alpha 30 Out
MsgId Message Id Alpha 7 Out
MsgText Message Text Alpha 80 Out
Return value: *ON if successful, *OFF if errors Example in /Free form RPG:
H BNDDIR('CRYPTO/CRYPTO') DFTACTGRP(*NO)
D/COPY CRYPTO/QCPYLESRC,@CRSP505
/FREE
// Get the first set of Key Labels and Key Stores used for ‘CCFIELD’
If GetFirstFldKeyInf (‘CCFIELD’
:KeyId
:EncKeyStrNam
:EncKeyStrLib
:EncKeyLabel
:DecKeyStrNam
:DecKeyStrLib
:DecKeyLabel
:MsgId
:MsgText);
// Success-> First set of Keys found
… logic …
Else;
// Errors-> Display MsgId and MsgText values
… logic …
Endif;
/END-FREE
Crypto Complete
Version 3.50 Linoma Software Page 27
GetNextFldKeyInf – Get Next Key information for Field Identifier
After executing the GetFirstFldKeyInf procedure, you can execute the GetNextFldKeyInf procedure to retrieve the next set of encryption/decryption Key Labels and Key Store names used for the specified Field Identifier. This information will be retrieved from the Field Encryption Registry. If field values are still encrypted under older (non-current) Keys, this procedure is useful to programmatically determine the Keys to use for decryption APIs (such as DecAES2). Procedure name: GetNextFldKeyInf Bind to Service Program: CRSP505 Prototype source member: @CRSP505 in CRYPTO/QCPYLESRC source file Parameters for GetNextFldKeyInf procedure:
Name Description Type Length In/Out Required
FldId Field identifier Alpha 30 In Yes
InKeyId Previous Key identifier (in) Signed 5,0 In Yes
OutKeyId Next Key identifier (out) Signed 5,0 Out
EncKeyStrNam Encryption Key Store Name Alpha 10 Out
EncKeyStrLib Encryption Key Store Library Alpha 10 Out
EncKeyLabel Encryption Key Label Alpha 30 Out
DecKeyStrNam Decryption Key Store Name Alpha 10 Out
DecKeyStrLib Decryption Key Store Library Alpha 10 Out
DecKeyLabel Decryption Key Label Alpha 30 Out
MsgId Message Id Alpha 7 Out
MsgText Message Text Alpha 80 Out
Return value: *ON if successful, *OFF if errors
Example in /Free form RPG:
H BNDDIR('CRYPTO/CRYPTO') DFTACTGRP(*NO)
D/COPY CRYPTO/QCPYLESRC,@CRSP505
/FREE
// Get the next set of Key Labels and Key Stores used for ‘CCFIELD’
If GetNextFldKeyInf (‘CCFIELD’
:InKeyId
:OutKeyId
:EncKeyStrNam
:EncKeyStrLib
:EncKeyLabel
:DecKeyStrNam
:DecKeyStrLib
:DecKeyLabel
:MsgId
:MsgText);
// Success-> Next set of Keys found
… logic …
Else;
// Errors-> Display MsgId and MsgText values
… logic …
Endif;
/END-FREE
Crypto Complete
Version 3.50 Linoma Software Page 28
GetExtFiLInf – Get External File Information for Field Identifier
The GetExtFiLInf procedure will return the name and library of the external physical file which contains the encrypted values for the specified Field Identifier. If a logical file is based on the external physical file, then the name and library of this logical file will also be returned. This information will be retrieved from the Field Encryption Registry. Procedure name: GetExtFiLInf Bind to Service Program: CRSP505 Prototype source member: @CRSP505 in CRYPTO/QCPYLESRC source file Parameters for GetExtFiLInf procedure:
Name Description Type Length In/Out Required
FldId Field identifier Alpha 30 In Yes
ExtFile External Physical File Name Alpha 10 Out
ExtLib External Physical File Library Alpha 10 Out
ExtFileL External Logical File Name Alpha 10 Out
ExtLibL External Logical File Library Alpha 10 Out
MsgId Message Id Alpha 7 Out
MsgText Message Text Alpha 80 Out
Return value: *ON if successful, *OFF if errors Example in /Free form RPG:
H BNDDIR('CRYPTO/CRYPTO') DFTACTGRP(*NO)
D/COPY CRYPTO/QCPYLESRC,@CRSP505
/FREE
// Get the External file name and library used for field id ‘CCFIELD’
If GetExtFiLInf (‘CCFIELD’
:ExtFile
:ExtLib
:ExtFileL
:ExtLibL
:MsgId
:MsgText);
// Success-> External file information found. The physical file name
// and library is in ExtFile and ExtLib. The logical file name and
// library is in ExtFileL and ExtLibL.
… logic …
Else;
// Errors-> Display MsgId and MsgText values
… logic …
Endif;
/END-FREE
Crypto Complete
Version 3.50 Linoma Software Page 29
GetFldIdx – Get Index for Field Value from External File
The GetFldIdx procedure will return the first external Index number found for the plain text value specified. If no record is found, then a 0 will be returned for the Index. This procedure should only be used if the field is active in the Field Encryption Registry and the encrypted values are stored in an external file. Procedure name: GetFldIdx Bind to Service Program: CRSP513 Prototype source member: @CRSP513 in CRYPTO/QCPYLESRC source file Parameters for GetFldIdx procedure:
Name Description Type Length In/Out Required
FldId Field Identifier Alpha 30 In Yes
PlainText Plain Text Alpha 32624 In Yes
ExtIndex Index of Value Packed 13,0 Out
MsgId Message Id Alpha 7 Out
MsgText Message Text Alpha 80 Out
Return value: *ON if successful, *OFF if errors Example in /Free form RPG:
H BNDDIR('CRYPTO/CRYPTO') DFTACTGRP(*NO) D/COPY CRYPTO/QCPYLESRC,@CRSP513 /FREE // Using the Credit Card value, retrieve the first Index value found // from the external file
If GetFldIdx (‘CCFIELD’ :CreditCardValue
:ExtIndex :MsgId :MsgText);
// Success-> Check to see if an Index number was found (not 0)
… logic … Else; // Errors-> Display MsgId and MsgText values
… logic …
Endif;
/END-FREE
Crypto Complete
Version 3.50 Linoma Software Page 30
CvtExtIdxDec – Convert Index Number from Character to Decimal
The CvtExtIdxDec procedure will convert an index number from a character value into a numeric value. This procedure will additionally strip any padding characters that may be contained in the index number. The CvtExtIdxDec is useful for converting an index number into its numeric format before calling the GetEncFld procedure. Procedure name: CvtExtIdxDec Bind to Service Program: CRSP505 Prototype source member: @CRSP505 in CRYPTO/QCPYLESRC source file Parameters for CvtExtIdxDec procedure:
Name Description Type Length In/Out Required
FldId Field identifier Alpha 30 In Yes
ExtIndex External Index Nbr. - Char Alpha 34 In Yes
ExtIndexDec External Index Nbr. - Dec Packed 13,0 Out
MsgId Message Id Alpha 7 Out
MsgText Message Text Alpha 80 Out
Return value: *ON if successful, *OFF if errors Example in /Free form RPG:
H BNDDIR('CRYPTO/CRYPTO') DFTACTGRP(*NO)
D/COPY CRYPTO/QCPYLESRC,@CRSP505
/FREE
// Move in the index number from the alphanumeric database field
ExtIndex = ccno;
// Convert the index number into numeric format for field id ‘CCFIELD’
If CvtExtIdxDec (‘CCFIELD’
:ExtIndex
:ExtIndexDec
:MsgId
:MsgText);
// Use the numeric version of the index number in ExtIndexDec to
// retrieve the field value from the external file.
If GetEncFld (‘CCFIELD’
:ExtIndexDec
:LogCmt
:CreditCardValue
:MsgId
:MsgText);
// Success-> The decrypted value is in CreditCardValue variable
… logic …
Endif;
Endif;
/END-FREE
Crypto Complete
Version 3.50 Linoma Software Page 31
ReqKeyTkn – Request a token to a Key contained in a Key Store
The ReqKeyTkn procedure will request a token to a Key contained in a Key Store. This token can then be used on encryption/decryption procedures which are token based (i.e. EncAES1 and DecAES1). Using tokens to encrypt and decrypt data is recommended for optimal performance since the key does not need to be retrieved from the Key Store and validated for each decrypt or encrypt operation. Procedure name: ReqKeyTkn Bind to Service Program: CRSP500 Prototype source member: @CRSP500 in CRYPTO/QCPYLESRC source file Parameters for ReqKeyTkn procedure:
Name Description Type Length In/Out Required
KeyStrNam Key Store Name Alpha 10 In No
KeyStrLib Key Store Library Alpha 10 In No
KeyLabel Key Label Alpha 30 In Yes
KeyTkn Key Token Alpha 8 Out
MsgId Message Id (if errors) Alpha 7 Out
MsgText Message Text (if errors) Alpha 80 Out
Return value: *ON if successful, *OFF if errors Example in /Free form RPG:
H BNDDIR('CRYPTO/CRYPTO') DFTACTGRP(*NO)
D/COPY CRYPTO/QCPYLESRC,@CRSP500
/FREE
// Request token for key label CREDIT_CARD_KEY
If ReqKeyTkn (‘OE_KEYS’
:‘*LIBL’
:‘CREDIT_CARD_KEY’
:KeyTkn
:MsgId
:MsgText);
// Success-> The token to the key is in variable KeyTkn
… logic …
Else;
// Errors-> Display MsgId and MsgText values
… logic …
Endif;
/END-FREE
Notes for ReqKeyTkn:
Specify the special value of *DEFAULT for the Key Store Name in order to use the default key store name indicated at the Key Policy level.
Specify *LIBL for the Key Store Library to locate the key store in the library list.
Each Key token will represent a unique Key Label contained in a Key Store.
Up to 99 Key tokens can be active at one time in memory per job.
When a token is no longer needed, the token can be released with the RlsKeyTkn procedure.
Crypto Complete
Version 3.50 Linoma Software Page 32
RlsKeyTkn – Release a token to a Key
The RlsKeyTkn procedure will release a token to a Key. It is recommended to release tokens when they are no longer needed in order to minimize memory usage. Procedure name: RlsKeyTkn Bind to Service Program: CRSP500 Prototype source member: @CRSP500 in CRYPTO/QCPYLESRC source file Parameters for ReqKeyTkn procedure:
Name Description Type Length In/Out Required
KeyTkn Key Token Alpha 8 Out
MsgId Message Id (if errors) Alpha 7 Out
MsgText Message Text (if errors) Alpha 80 Out
Return value: *ON if successful, *OFF if errors Example in /Free form RPG:
H BNDDIR('CRYPTO/CRYPTO') DFTACTGRP(*NO)
D/COPY CRYPTO/QCPYLESRC,@CRSP500
/FREE
// Release token
If RlsKeyTkn (KeyTkn
:MsgId
:MsgText);
// Success
… logic …
Else;
// Errors-> Display MsgId and MsgText values
… logic …
Endif;
/END-FREE
Crypto Complete
Version 3.50 Linoma Software Page 33
EncAES1 – Encrypt text with AES256 using Key Token (ECB block mode)
The EncAES1 procedure will encrypt text using the AES256 algorithm and ECB block mode. This procedure requires a Key Token, which can be acquired through the ReqKeyTkn procedure. Procedure name: EncAES1 Bind to Service Program: CRSP501 Prototype source member: @CRSP501 in CRYPTO/QCPYLESRC source file Parameters for EncAES1 procedure:
Name Description Type Length In/Out Required
PlainText Plain Text Alpha 32678 In Yes
PlainTextLen Plain Text Length Integer 10,0 In Yes
KeyTkn Key Token Alpha 8 In Yes
LogCmt Audit Log Comment Alpha 50 In No
CipherText Encrypted Text Alpha 32768 Out
CipherTextLen Encrypted Text Length Integer 10,0 Out
MsgId Message Id Alpha 7 Out
MsgText Message Text Alpha 80 Out
Return value: *ON if successful, *OFF if errors Example in /Free form RPG:
H BNDDIR('CRYPTO/CRYPTO') DFTACTGRP(*NO)
D/COPY CRYPTO/QCPYLESRC,@CRSP501
/FREE
// Encrypt value contained in CreditCard variable
If EncAES1 (CreditCard
:CreditCardLength
:KeyTkn
:‘Audit Log comment…’
:CipherText
:CipherTextLen
:MsgId
:MsgText);
// Success-> The encrypted value is in CipherText variable
… logic …
Else;
// Errors-> Display MsgId and MsgText values
… logic …
Endif;
/END-FREE
Crypto Complete
Version 3.50 Linoma Software Page 34
Notes for EncAES1:
With AES block mode, the returned Cipher Text length will be a minimum of 16 bytes long. This returned Cipher text length will be divisible by 16 or 24. For instance:
Plain Text Length Cipher Text Length
10 bytes 16 bytes
16 bytes 16 bytes
17 bytes 24 bytes
24 bytes 24 bytes
32 bytes 32 bytes
Crypto Complete
Version 3.50 Linoma Software Page 35
DecAES1 – Decrypt text with AES256 using Key Token (ECB block mode)
The DecAES1 procedure will decrypt text using the AES256 algorithm and ECB block mode. This procedure requires a Key Token, which can be acquired through the ReqKeyTkn procedure. Procedure name: DecAES1 Bind to Service Program: CRSP501 Prototype source member: @CRSP501 in CRYPTO/QCPYLESRC source file Parameters for DecAES1 procedure:
Name Description Type Length In/Out Required
CipherText Encrypted Text Alpha 32768 In Yes
CipherTextLen Encrypted Text Length Integer 10,0 In Yes
KeyTkn Key Token Alpha 8 In Yes
LogCmt Audit Log Comment Alpha 50 In No
PlainText Plain Text Alpha 32768 Out
PlainTextLen Plain Text Length Integer 10,0 Out
MsgId Message Id Alpha 7 Out
MsgText Message Text Alpha 80 Out
Return value: *ON if successful, *OFF if errors Example in /Free form RPG:
H BNDDIR('CRYPTO/CRYPTO') DFTACTGRP(*NO)
D/COPY CRYPTO/QCPYLESRC,@CRSP501
/FREE
// Decrypt the value contained in CipherText variable
If DecAES1 (CipherText
:CipherTextLength
:KeyTkn
:‘Audit Log comment…’
:CreditCard
:ReturnedLength
:MsgId
:MsgText);
// Success-> The decrypted value is in CreditCard variable
… logic …
Else;
// Errors-> Display MsgId and MsgText values
… logic …
Endif;
/END-FREE
Crypto Complete
Version 3.50 Linoma Software Page 36
EncAES2 – Encrypt text with AES256 using Key Label (ECB block mode)
The EncAES2 procedure will encrypt text using the AES256 algorithm and ECB block mode. This procedure requires a Key Label. Procedure name: EncAES2 Bind to Service Program: CRSP501 Prototype source member: @CRSP501 in CRYPTO/QCPYLESRC source file Parameters for EncAES2 procedure:
Name Description Type Length In/Out Required
PlainText Plain Text Alpha 32768 In Yes
PlainTextLen Plain Text Length Integer 10,0 In Yes
KeyStrNam Key Store Name Alpha 10 In No
KeyStrLib Key Store Library Alpha 10 In No
KeyLabel Key Label Alpha 30 In Yes
LogCmt Audit Log Comment Alpha 50 In No
CipherText Encrypted Text Alpha 32768 Out
CipherTextLen Encrypted Text Length Integer 10,0 Out
MsgId Message Id Alpha 7 Out
MsgText Message Text Alpha 80 Out
Return value: *ON if successful, *OFF if errors Example in /Free form RPG:
H BNDDIR('CRYPTO/CRYPTO') DFTACTGRP(*NO)
D/COPY CRYPTO/QCPYLESRC,@CRSP501
/FREE
// Encrypt value contained in CreditCard variable
If EncAES2 (CreditCard
:CreditCardLength
:‘OE_KEYS’
:‘*LIBL’
:‘CREDIT_CARD_KEY’
:‘Audit Log comment…’
:CipherText
:CipherTextLen
:MsgId
:MsgText);
// Success-> The encrypted value is in CipherText variable
… logic …
Else;
// Errors-> Display MsgId and MsgText values
… logic …
Endif;
/END-FREE
Crypto Complete
Version 3.50 Linoma Software Page 37
Notes for EncAES2:
Specify the special value of *DEFAULT for the Key Store Name in order to use the default key store name indicated at the Key Policy level.
Specify *LIBL for the Key Store Library to locate the Key Store in the library list.
With AES block mode, the returned Cipher Text length will be a minimum of 16 bytes long. This returned Cipher text length will be divisible by 16 or 24. For instance:
Plain Text Length Cipher Text Length
10 bytes 16 bytes
16 bytes 16 bytes
17 bytes 24 bytes
24 bytes 24 bytes
32 bytes 32 bytes
Crypto Complete
Version 3.50 Linoma Software Page 38
DecAES2 – Decrypt text with AES256 using Key Label (ECB block mode)
The DecAES2 procedure will decrypt text using the AES256 algorithm and ECB block mode. This procedure requires a Key Label. Procedure name: DecAES2 Bind to Service Program: CRSP501 Prototype source member: @CRSP501 in CRYPTO/QCPYLESRC source file Parameters for DecAES2 procedure:
Name Description Type Length In/Out Required
CipherText Encrypted Text Alpha 32768 In Yes
CipherTextLen Encrypted Text Length Integer 10,0 In Yes
KeyStrNam Key Store Name Alpha 10 In No
KeyStrLib Key Store Library Alpha 10 In No
KeyLabel Key Store Label Alpha 30 In Yes
LogCmt Audit Log Comment Alpha 50 In No
PlainText Plain Text Alpha 32768 Out
PlainTextLen Plain Text Length Integer 10,0 Out
MsgId Message Id Alpha 7 Out
MsgText Message Text Alpha 80 Out
Return value: *ON if successful, *OFF if errors Example in /Free form RPG:
H BNDDIR('CRYPTO/CRYPTO') DFTACTGRP(*NO)
D/COPY CRYPTO/QCPYLESRC,@CRSP501
/FREE
// Decrypt value in CipherText variable
If DecAES2 (CipherText
:CipherTextLength
:‘OE_KEYS’
:‘*LIBL’
:‘CREDIT_CARD_KEY’
:‘Audit Log comment…’
:CreditCard
:CreditCardLen
:MsgId
:MsgText);
// Success-> The decrypted value is in CreditCard variable
… logic …
Else;
// Errors-> Display MsgId and MsgText values
… logic …
Endif;
/END-FREE
Crypto Complete
Version 3.50 Linoma Software Page 39
Notes for DecAES2:
Specify the special value of *DEFAULT for the Key Store Name in order to use the default key store name indicated at the Key Policy level.
Specify *LIBL for the Key Store Library to locate the Key Store in the library list.
Crypto Complete
Version 3.50 Linoma Software Page 40
EncTDES1 – Encrypt text with TDES using Key Token (ECB block mode)
The EncTDES1 procedure will encrypt text using the TDES (Triple DES) algorithm and ECB block mode. This procedure requires a Key Token, which can be acquired through the ReqKeyTkn procedure. Procedure name: EncTDES1 Bind to Service Program: CRSP504 Prototype source member: @CRSP504 in CRYPTO/QCPYLESRC source file Parameters for EncTDES1 procedure:
Name Description Type Length In/Out Required
PlainText Plain Text Alpha 32768 In Yes
PlainTextLen Plain Text Length Integer 10,0 In Yes
KeyTkn Key Token Alpha 8 In Yes
LogCmt Audit Log Comment Alpha 50 In No
CipherText Encrypted Text Alpha 32768 Out
CipherTextLen Encrypted Text Length Integer 10,0 Out
MsgId Message Id Alpha 7 Out
MsgText Message Text Alpha 80 Out
Return value: *ON if successful, *OFF if errors Example in /Free form RPG:
H BNDDIR('CRYPTO/CRYPTO') DFTACTGRP(*NO)
D/COPY CRYPTO/QCPYLESRC,@CRSP504
/FREE
// Encrypt value in CreditCard variable
If EncTDES1(CreditCard
:CreditCardLength
:KeyTkn
:‘Audit Log comment…’
:CipherText
:CipherTextLen
:MsgId
:MsgText);
// Success-> The encrypted value is in CipherText variable
… logic …
Else;
// Errors-> Display MsgId and MsgText values
… logic …
Endif;
/END-FREE
Crypto Complete
Version 3.50 Linoma Software Page 41
Notes for EncTDES1: With TDES block mode, the returned Cipher Text length will be a minimum of 8 bytes long. This
returned Cipher text length will be divisible by 8. For instance:
Plain Text Length Cipher Text Length
5 bytes 8 bytes
8 bytes 8 bytes
9 bytes 16 bytes
16 bytes 16 bytes
Crypto Complete
Version 3.50 Linoma Software Page 42
DecTDES1 – Decrypt text with TDES using Key Token (ECB block mode)
The DecAES1 procedure will decrypt text using the TDES (Triple DES) algorithm and ECB block mode. This procedure requires a Key Token, which can be acquired through the ReqKeyTkn procedure. Procedure name: DecTDES1 Bind to Service Program: CRSP504 Prototype source member: @CRSP504 in CRYPTO/QCPYLESRC source file Parameters for DecTDES1 procedure:
Name Description Type Length In/Out Required
CipherText Encrypted Text Alpha 32768 In Yes
CipherTextLen Encrypted Text Length Integer 10,0 In Yes
KeyTkn Key Token Alpha 8 In Yes
LogCmt Audit Log Comment Alpha 50 In No
PlainText Plain Text Alpha 32768 Out
PlainTextLen Plain Text Length Integer 10,0 Out
MsgId Message Id Alpha 7 Out
MsgText Message Text Alpha 80 Out
Return value: *ON if successful, *OFF if errors Example in /Free form RPG:
H BNDDIR('CRYPTO/CRYPTO') DFTACTGRP(*NO)
D/COPY CRYPTO/QCPYLESRC,@CRSP504
/FREE
// Decrypt value in CipherText variable
If DecTDES1(CipherText
:CipherTextLength
:KeyTkn
:‘Audit Log comment…’
:CreditCard
:ReturnedLength
:MsgId
:MsgText);
// Success-> The decrypted value is in CreditCard variable
… logic …
Else;
// Errors-> Display MsgId and MsgText values
… logic …
Endif;
/END-FREE
Crypto Complete
Version 3.50 Linoma Software Page 43
EncTDES2 – Encrypt text with TDES using Key Label (ECB block mode)
The EncTDES2 procedure will encrypt text using the TDES (Triple DES) algorithm and ECB block mode. This procedure requires a Key Label. Procedure name: EncTDES2 Bind to Service Program: CRSP504 Prototype source member: @CRSP504 in CRYPTO/QCPYLESRC source file Parameters for EncTDES2 procedure:
Name Description Type Length In/Out Required
PlainText Plain Text Alpha 32768 In Yes
PlainTextLen Plain Text Length Integer 10,0 In Yes
KeyStrNam Key Store Name Alpha 10 In No
KeyStrLib Key Store Library Alpha 10 In No
KeyLabel Key Label Alpha 30 In Yes
LogCmt Audit Log Comment Alpha 50 In No
CipherText Encrypted Text Alpha 32768 Out
CipherTextLen Encrypted Text Length Integer 10,0 Out
MsgId Message Id Alpha 7 Out
MsgText Message Text Alpha 80 Out
Return value: *ON if successful, *OFF if errors Example in /Free form RPG:
H BNDDIR('CRYPTO/CRYPTO') DFTACTGRP(*NO)
D/COPY CRYPTO/QCPYLESRC,@CRSP504
/FREE
// Encrypt value in CreditCard variable
If EncTDES2(CreditCard
:CreditCardLength
:‘OE_KEYS’
:‘*LIBL’
:‘CREDIT_CARD_KEY’
:‘Audit Log comment…’
:CipherText
:CipherTextLen
:MsgId
:MsgText);
// Success-> The encrypted value is in CipherText variable
… logic …
Else;
// Errors-> Display MsgId and MsgText values
… logic …
Endif;
/END-FREE
Crypto Complete
Version 3.50 Linoma Software Page 44
Notes for EncTDES2:
Specify the special value of *DEFAULT for the Key Store Name in order to use the default key store name that is indicated at the Key Policy level.
Specify *LIBL for the Key Store Library to locate the Key Store in the library list.
With TDES block mode, the returned Cipher Text length will be a minimum of 8 bytes long. This returned Cipher text length will be divisible by 8. For instance:
Plain Text Length Cipher Text Length
5 bytes 8 bytes
8 bytes 8 bytes
9 bytes 16 bytes
16 bytes 16 bytes
Crypto Complete
Version 3.50 Linoma Software Page 45
DecTDES2 – Decrypt text with TDES using Key Label (ECB block mode)
The DecAES2 procedure will decrypt text using the TDES (Triple DES) algorithm and ECB block mode. This procedure requires a Key Label. Procedure name: DecTDES2 Bind to Service Program: CRSP504 Prototype source member: @CRSP504 in CRYPTO/QCPYLESRC source file Parameters for DecTDES2 procedure:
Name Description Type Length In/Out Required
CipherText Encrypted Text Alpha 32768 In Yes
CipherTextLen Encrypted Text Length Integer 10,0 In Yes
KeyStrNam Key Store Name Alpha 10 In No
KeyStrLib Key Store Library Alpha 10 In No
KeyLabel Key Store Label Alpha 30 In Yes
LogCmt Audit Log Comment Alpha 50 In No
PlainText Plain Text Alpha 32768 Out
PlainTextLen Plain Text Length Integer 10,0 Out
MsgId Message Id Alpha 7 Out
MsgText Message Text Alpha 80 Out
Return value: *ON if successful, *OFF if errors Example in /Free form RPG:
H BNDDIR('CRYPTO/CRYPTO') DFTACTGRP(*NO)
D/COPY CRYPTO/QCPYLESRC,@CRSP504
/FREE
// Decrypt value in CipherText variable
If DecTDES2(CipherText
:CipherTextLength
:‘OE_KEYS’
:‘*LIBL’
:‘CREDIT_CARD_KEY’
:‘Audit Log comment…’
:CreditCard
:CreditCardLen
:MsgId
:MsgText);
// Success-> The decrypted value is in CreditCard variable
… logic …
Else;
// Errors-> Display MsgId and MsgText values
… logic …
Endif;
/END-FREE
Crypto Complete
Version 3.50 Linoma Software Page 46
Notes for DecTDES2:
Specify the special value of *DEFAULT for the Key Store Name in order to use the default key store name that is indicated at the Key Policy level.
Specify *LIBL for the Key Store Library to locate the Key Store in the library list.
Crypto Complete
Version 3.50 Linoma Software Page 47
EncAdv3 – Encrypt text with Advanced options using Key Token
The EncAdv3 procedure will encrypt text using advanced options. This procedure requires a Key Token, which can be acquired through the ReqKeyTkn procedure. Procedure name: EncAdv3 Bind to Service Program: CRSP510 Prototype source member: @CRSP510 in CRYPTO/QCPYLESRC source file Parameters for EncAdv3 procedure:
Name Description Type Length In/Out Required
PlainText Plain Text Alpha 32768 In Yes
PlainTextLen Plain Text Length Integer 10,0 In Yes
KeyTkn Key Token Alpha 8 In Yes
LogCmt Audit Log Comment Alpha 50 In No
Algorithm Algorithm 1 Alpha 10 In Yes
Mode Mode of Algorithm 2 Alpha 1 In No
BlockLen Block Length 3 Integer 10,0 In No
PadOption Pad Option 4 Alpha 1 In No
PadChar Pad Character Alpha 1 In No
OutputType Output Type 5 Alpha 7 In No
OutputFmt Output Format 6 Alpha 7 In No
InitVector Initialization Vector (Salt) 7 Alpha 32 In/Out No
CipherText Encrypted Text Alpha 32768 Out
CipherTextLen Encrypted Text Length Integer 10,0 Out
MsgId Message Id Alpha 7 Out
MsgText Message Text Alpha 80 Out
Return value: *ON if successful, *OFF if errors Parameter Notes:
1 Algorithms supported are *TDES (for Triple DES), *AES128, *AES192 and *AES256
2 Modes supported are ‘0’ for ECB, ‘1’ for CBC and ‘6’ for CUSP
3 Block length:
For *AES128, *AES192 and *AES256 algorithms: either specify a 0 to automatically calculate the block length or specify a block length of 16, 24 or 32.
For *TDES algorithm: specify a 0 to automatically calculate the block length or specify a block length of 8.
4 Valid values for the PadOption are:
‘0’ or blanks = No Padding ‘1’ = Pad using pad character (only valid with the *TDES algorithm) ‘2’ = Pad using pad number
Specifying a PadOption will pad the data in the PlainText out to the next block length multiple. For example, the block length would be 8 for *TDES algorithm. Therefore, a value’s length of 20 is padded to 24, 32 is padded to 40, and so forth. The last byte of data will contain a 1-byte binary counter containing the number of pad characters used (a value from 1 to 8). If PadOption is a ‘1’, the PadChar value is used for the rest of the pad characters. If PadOption is ‘2’, the binary counter is used for the rest of the pad characters.
Crypto Complete
Version 3.50 Linoma Software Page 48
5 OutputType valid values are *EBCDIC and *ASCII. If none is specified, then the default value of
*EBCDIC will be used.
6 OutputFmt valid values are *CHAR, *HEX and *BASE64. If none is specified, then the default value
of *CHAR will be used.
7 Initialization vector (IV): Specify an IV value to manipulate the encryption operation. In other words,
the same Plain Text which is encrypted with different IVs will produce different Cipher text values. For *AES algorithms, the IV length should not exceed the block length. For *TDES, the IV length should not exceed 8. The IV need not be secret, but it should be unique. Upon completion of the operation, an output chaining value will be returned in the IV field. This value can be used as the IV for the next operation when encrypting or decrypting text in multiple blocks. Refer to ANSI X9.52 for an explanation of its use. Allowed for algorithm modes of ‘1’ (CBC) and ‘6’ (CUSP).
Example in /Free form RPG:
H BNDDIR('CRYPTO/CRYPTO') DFTACTGRP(*NO)
D/COPY CRYPTO/QCPYLESRC,@CRSP510
/FREE
// Encrypt value in CreditCard variable using AES256
If EncAdv3 (CreditCard
:CreditCardLength
:KeyTkn
:‘Audit Log comment…’
:‘*AES256’
:‘0’
:16
:PadOption
:PadChar
:‘*EBCDIC’
:‘*CHAR’
:InitVector
:CipherText
:CipherTextLen
:MsgId
:MsgText);
// Success-> The encrypted value is in CipherText variable
… logic …
Else;
// Errors-> Display MsgId and MsgText values
… logic …
Endif;
/END-FREE
Crypto Complete
Version 3.50 Linoma Software Page 49
Additional Notes for EncAdv3:
When using *AES128, *AES192 and *AES256 algorithms with ECB or CBC modes, the returned Cipher Text length will be a minimum of 16 bytes long. This returned Cipher text length will be divisible by 16 or 24. For instance:
Plain Text Length Cipher Text Length
10 bytes 16 bytes
16 bytes 16 bytes
17 bytes 24 bytes
24 bytes 24 bytes
32 bytes 32 bytes
When using *AES128, *AES192 and *AES256 algorithms with CUSP mode, the returned Cipher Text length will be the same as the Plain Text length.
For *TDES algorithm, the returned Cipher Text length will be a minimum of 8 bytes long. This returned Cipher text length will be divisible by 8. For instance:
Plain Text Length Cipher Text Length
5 bytes 8 bytes
8 bytes 8 bytes
9 bytes 16 bytes
16 bytes 16 bytes
Crypto Complete
Version 3.50 Linoma Software Page 50
DecAdv3 – Decrypt text with Advanced options using Key Token
The DecAdv3 procedure will decrypt text using advanced options. This procedure requires a Key Token, which can be acquired through the ReqKeyTkn procedure. Procedure name: DecAdv3 Bind to Service Program: CRSP510 Prototype source member: @CRSP510 in CRYPTO/QCPYLESRC source file Parameters for DecAdv3 procedure:
Name Description Type Length In/Out Required
CipherText Encrypted Text Alpha 32768 In Yes
CipherTextLen Encrypted Text Length Integer 10,0 In Yes
InputType Input Type 1 Alpha 7 In No
InputFmt Input Format 2 Alpha 7 In No
KeyTkn Key Token Alpha 8 In Yes
LogCmt Audit Log Comment Alpha 50 In No
Algorithm Algorithm 3 Alpha 10 In Yes
Mode Mode of Algorithm 4 Alpha 1 In No
BlockLen Block Length 5 Integer 10,0 In No
PadOption Pad Option 6 Alpha 1 In No
PadChar Pad Character Alpha 1 In No
InitVector Initialization Vector (Salt) 7 Alpha 32 In/Out No
PlainText Plain Text Alpha 32768 Out
PlainTextLen Plain Text Length Integer 10,0 Out
MsgId Message Id Alpha 7 Out
MsgText Message Text Alpha 80 Out
Return value: *ON if successful, *OFF if errors Parameter Notes:
1 InputType valid values are *EBCDIC and *ASCII. If none is specified, then the default value of
*EBCDIC will be used.
2 InputFmt valid values are *CHAR, *HEX and *BASE64. If none is specified, then the default value of
*CHAR will be used.
3 Algorithms supported are *TDES (for Triple DES), *AES128, *AES192 and *AES256
4 Modes supported are ‘0’ for ECB, ‘1’ for CBC and ‘6’ for CUSP
5 Block length:
o For *AES128, *AES192 and *AES256 algorithms: either specify a 0 to automatically calculate the block length or specify a block length of 16, 24 or 32.
o For *TDES algorithm: specify a 0 to automatically calculate the block length or specify a block length of 8.
Crypto Complete
Version 3.50 Linoma Software Page 51
6 Valid values for the PadOption are:
‘0’ or blanks = Value is not padded ‘1’ = Value is padded using a pad character (only valid with the *TDES algorithm) ‘2’ = Value is padded using a pad number
Specifying a PadOption will strip the pad bytes off the end of the value before returning it in the PlainText.
7 Initialization vector (IV): Specify an IV value to manipulate the decryption operation. In other words,
the same Cipher which is decrypted with different IVs will produce different Plain text values. For *AES algorithms, the IV length should not exceed the block length. For *TDES, the IV length should not exceed 8. The IV need not be secret, but it should be unique. Upon completion of the operation, an output chaining value will be returned in the IV field. This value can be used as the IV for the next operation when encrypting or decrypting text in multiple blocks. Refer to ANSI X9.52 for an explanation of its use. Allowed for algorithm modes of ‘1’ (CBC) and ‘6’ (CUSP).
Example in /Free form RPG:
H BNDDIR('CRYPTO/CRYPTO') DFTACTGRP(*NO)
D/COPY CRYPTO/QCPYLESRC,@CRSP510
/FREE
// Decrypt value in CipherText variable using AES256 algorithm
If DecAdv3 (CipherText
:CipherTextLen
:‘*EBCDIC’
:‘*CHAR’
:KeyTkn
:‘Audit Log comment…’
:‘*AES256’
:‘0’
:16
:PadOption
:PadChar
:InitVector
:CreditCard
:CreditCardLength
:MsgId
:MsgText);
// Success-> The decrypted value is in CreditCard variable
… logic …
Else;
// Errors-> Display MsgId and MsgText values
… logic …
Endif;
/END-FREE
Crypto Complete
Version 3.50 Linoma Software Page 52
EncAdv4 – Encrypt text with Advanced options using Key Label
The EncAdv4 procedure will encrypt text using advanced options. This procedure requires a Key Label. Procedure name: EncAdv4 Bind to Service Program: CRSP510 Prototype source member: @CRSP510 in CRYPTO/QCPYLESRC source file Parameters for EncAdv4 procedure:
Name Description Type Length In/Out Required
PlainText Plain Text Alpha 32768 In Yes
PlainTextLen Plain Text Length Integer 10,0 In Yes
KeyStrNam Key Store Name 1 Alpha 10 In No
KeyStrLib Key Store Library 2 Alpha 10 In No
KeyLabel Key Store Label Alpha 30 In Yes
LogCmt Audit Log Comment Alpha 50 In No
Algorithm Algorithm 3 Alpha 10 In Yes
Mode Mode of Algorithm 4 Alpha 1 In No
BlockLen Block Length 5 Integer 10,0 In No
PadOption Pad Option 6 Alpha 1 In No
PadChar Pad Character Alpha 1 In No
OutputType Output Type 7 Alpha 7 In No
OutputFmt Output Format 8 Alpha 7 In No
InitVector Initialization Vector (Salt) 9 Alpha 32 In/Out No
CipherText Encrypted Text Alpha 32768 Out
CipherTextLen Encrypted Text Length Integer 10,0 Out
MsgId Message Id Alpha 7 Out
MsgText Message Text Alpha 80 Out
Return value: *ON if successful, *OFF if errors Parameter Notes:
1 Specify the special value of *DEFAULT for the Key Store Name in order to use the default key store
name indicated at the Key Policy level.
2 Specify *LIBL for the Key Store Library to locate the Key Store in the library list.
3 Algorithms supported are *TDES (for Triple DES), *AES128, *AES192 and *AES256
4 Modes supported are ‘0’ for ECB, ‘1’ for CBC and ‘6’ for CUSP
5 Block length:
For *AES128, *AES192 and *AES256 algorithms: either specify a 0 to automatically calculate the block length or specify a block length of 16, 24 or 32.
For *TDES algorithm: specify a 0 to automatically calculate the block length or specify a block length of 8.
Crypto Complete
Version 3.50 Linoma Software Page 53
6 Valid values for the PadOption are:
‘0’ or blanks = No Padding ‘1’ = Pad using pad character (only valid with the *TDES algorithm) ‘2’ = Pad using pad number
Specifying a PadOption will pad the data in the PlainText out to the next block length multiple. For example, the block length would be 8 for *TDES algorithm. Therefore, a value’s length of 20 is padded to 24, 32 is padded to 40, and so forth. The last byte of data will contain a 1-byte binary counter containing the number of pad characters used (a value from 1 to 8). If PadOption is a ‘1’, the PadChar value is used for the rest of the pad characters. If PadOption is ‘2’, the binary counter is used for the rest of the pad characters.
7 OutputType valid values are *EBCDIC and *ASCII. If none is specified, then the default value of
*EBCDIC will be used. 8 OutputFmt valid values are *CHAR, *HEX and *BASE64. If none is specified, then the default value
of *CHAR will be used. 9 Initialization vector (IV): Specify an IV value to manipulate the encryption operation. In other words,
the same Plain Text which is encrypted with different IVs will produce different Cipher text values. For *AES algorithms, the IV length should not exceed the block length. For *TDES, the IV length should not exceed 8. The IV need not be secret, but it should be unique. Upon completion of the operation, an output chaining value will be returned in the IV field. This value can be used as the IV for the next operation when encrypting or decrypting text in multiple blocks. Refer to ANSI X9.52 for an explanation of its use. Allowed for algorithm modes of ‘1’ (CBC) and ‘6’ (CUSP).
Example in /Free form RPG:
H BNDDIR('CRYPTO/CRYPTO') DFTACTGRP(*NO)
D/COPY CRYPTO/QCPYLESRC,@CRSP510
/FREE
// Encrypt value in CreditCard variable using AES256 algorithm
If EncAdv4 (CreditCard
:CreditCardLength
:‘OE_KEYS’
:‘*LIBL’
:‘CREDIT_CARD_KEY’
:‘Audit Log comment…’
:‘*AES256’
:‘0’
:16
:PadOption
:PadChar
:‘*EBCDIC’
:‘*CHAR’
:InitVector
:CipherText
:CipherTextLen
:MsgId
:MsgText);
// Success-> The encrypted value is in CipherText variable
… logic …
Else;
// Errors-> Display MsgId and MsgText values
… logic …
Endif;
/END-FREE
Crypto Complete
Version 3.50 Linoma Software Page 54
Additional notes for EncAdv4:
When using *AES128, *AES192 and *AES256 algorithms with ECB or CBC modes, the returned Cipher Text length will be a minimum of 16 bytes long. This returned Cipher text length will be divisible by 16 or 24. For instance:
Plain Text Length Cipher Text Length
10 bytes 16 bytes
16 bytes 16 bytes
17 bytes 24 bytes
24 bytes 24 bytes
32 bytes 32 bytes
When using *AES128, *AES192 and *AES256 algorithms with CUSP mode, the returned Cipher Text length will be the same as the Plain Text length.
For *TDES algorithm, the returned Cipher Text length will be a minimum of 8 bytes long. This returned Cipher text length will be divisible by 8. For instance:
Plain Text Length Cipher Text Length
5 bytes 8 bytes
8 bytes 8 bytes
9 bytes 16 bytes
16 bytes 16 bytes
Crypto Complete
Version 3.50 Linoma Software Page 55
DecAdv4 – Decrypt text with Advanced options using Key Label
The DecAdv4 procedure will decrypt text using advanced options. This procedure requires a Key Label. Procedure name: DecAdv4 Bind to Service Program: CRSP510 Prototype source member: @CRSP510 in CRYPTO/QCPYLESRC source file Parameters for DecAdv4 procedure:
Name Description Type Length In/Out Required
CipherText Encrypted Text Alpha 32768 In Yes
CipherTextLen Encrypted Text Length Integer 10,0 In Yes
InputType Input Type 1 Alpha 7 In No
InputFmt Input Format 2 Alpha 7 In No
KeyStrNam Key Store Name 3 Alpha 10 In No
KeyStrLib Key Store Library 4 Alpha 10 In No
KeyLabel Key Store Label Alpha 30 In Yes
LogCmt Audit Log Comment Alpha 50 In No
Algorithm Algorithm 5 Alpha 10 In Yes
Mode Mode of Algorithm 6 Alpha 1 In No
BlockLen Block Length 7 Integer 10,0 In No
PadOption Pad Option 8 Alpha 1 In No
PadChar Pad Character Alpha 1 In No
InitVector Initialization Vector (Salt) 9 Alpha 32 In/Out No
PlainText Plain Text Alpha 32768 Out
PlainTextLen Plain Text Length Integer 10,0 Out
MsgId Message Id Alpha 7 Out
MsgText Message Text Alpha 80 Out
Return value: *ON if successful, *OFF if errors Parameter Notes:
1 InputType valid values are *EBCDIC and *ASCII. If none is specified, then the default value of
*EBCDIC will be used.
2 InputFmt valid values are *CHAR, *HEX and *BASE64. If none is specified, then the default value of
*CHAR will be used.
3 Specify the special value of *DEFAULT for the Key Store Name in order to use the default key store
name indicated at the Key Policy level.
4 Specify *LIBL for the Key Store Library to locate the Key Store in the library list.
5 Algorithms supported are *TDES (for Triple DES), *AES128, *AES192 and *AES256
6 Modes supported are ‘0’ for ECB, ‘1’ for CBC and ‘6’ for CUSP
7 Block length:
o For *AES128, *AES192 and *AES256 algorithms: either specify a 0 to automatically calculate the block length or specify a block length of 16, 24 or 32.
o For *TDES algorithm: specify a 0 to automatically calculate the block length or specify a block length of 8.
Crypto Complete
Version 3.50 Linoma Software Page 56
8 Valid values for the PadOption are:
‘0’ or blanks = Value is not padded ‘1’ = Value is padded with a pad character (only valid with the *TDES algorithm) ‘2’ = Value is padded with a pad number
Specifying a PadOption will strip the pad bytes off the end of the value before returning it in the PlainText.
9 Initialization vector (IV): Specify an IV value to manipulate the decryption operation. In other words,
the same Cipher which is decrypted with different IVs will produce different Plain text values. For *AES algorithms, the IV length should not exceed the block length. For *TDES, the IV length should not exceed 8. The IV need not be secret, but it should be unique. Upon completion of the operation, an output chaining value will be returned in the IV field. This value can be used as the IV for the next operation when encrypting or decrypting text in multiple blocks. Refer to ANSI X9.52 for an explanation of its use. Allowed for algorithm modes of ‘1’ (CBC) and ‘6’ (CUSP).
Example in /Free form RPG:
H BNDDIR('CRYPTO/CRYPTO') DFTACTGRP(*NO)
D/COPY CRYPTO/QCPYLESRC,@CRSP510
/FREE
// Decrypt value in CipherText variable using AES256 algorithm
If DecAdv4 (CipherText
:CipherTextLen
:‘*EBCDIC’
:‘*CHAR’
:‘OE_KEYS’
:‘*LIBL’
:‘CREDIT_CARD_KEY’
:‘Audit Log comment…’
:‘*AES256’
:‘0’
:16
:PadOption
:PadChar
:InitVector
:CreditCard
:CreditCardLength
:MsgId
:MsgText);
// Success-> The decrypted value is in CreditCard variable
… logic …
Else;
// Errors-> Display MsgId and MsgText values
… logic …
Endif;
/END-FREE
Crypto Complete
Version 3.50 Linoma Software Page 57
GenSha1Hash – Generate SHA1 Hash
The GenSha1Hash procedure will generate an encrypted hash value using the SHA1 (Secure Hash Algorithm) standard. SHA1 is designed as a one-way encryption algorithm. In other words, the hash value is not intended for decryption. Procedure name: GenSha1Hash Bind to Service Program: CRSP503 Prototype source member: @CRSP503 in CRYPTO/QCPYLESRC source file Parameters for GenSha1Hash procedure:
Name Description Type Length In/Out Required
InputValue Input Value Alpha 1000 In Yes
InputLen Input Length Integer 10,0 In Yes
HashValue Hash value Alpha 20 Out
MsgId Message Id Alpha 7 Out
MsgText Message Text Alpha 80 Out
Example in /Free form RPG:
H BNDDIR('CRYPTO/CRYPTO') DFTACTGRP(*NO)
D/COPY CRYPTO/QCPYLESRC,@CRSP503
/FREE
// Generate a hash value based on the AppPassword variable
If GenSha1Hash (AppPassword
:10
:HashValue
:MsgId
:MsgText);
// Success-> The hash is in HashValue variable
… logic …
Else;
// Errors-> Display MsgId and MsgText values
… logic …
Endif;
/END-FREE
Notes for GenSha1Hash:
A hash is a good technique for protecting and storing passwords used in an application. For instance,
an application setup screen could prompt the user to establish a password they wish to use in that application. You could then generate a hash from that password and store this hash value in a database. When a user attempts to signon to an application with a password, you can hash the password entered and compare it to the hash value stored in the database. If the hash values do not match, then you know the password is not valid.
Crypto Complete
Version 3.50 Linoma Software Page 58
GenHashValue – Generate Hash Value (MD5, SHA-1, SHA-256, SHA-384, SHA-512)
The GenHashValue procedure will generate an MD5, SHA-1, SHA-256, SHA-384 or SHA-512 Hash Value. Hash values are designed as a one-way encryption algorithm. In other words, the hash value is not intended for decryption. Procedure name: GenHashValue Bind to Service Program: CRSP503 Prototype source member: @CRSP503 in CRYPTO/QCPYLESRC source file Parameters for GenHashValue procedure:
Name Description Type Length In/Out Required
InputValue Input Value Alpha 32768 In Yes
InputLen Input Length Integer 10,0 In Yes
HashType Hash Type 1 Alpha 7 In Yes
OutputType Output Type 2 Alpha 7 In Yes
OutputFmt Output Format 3 Alpha 7 In Yes
HashValue Hash value Alpha 256 Out
MsgId Message Id Alpha 7 Out
MsgText Message Text Alpha 80 Out
Example in /Free form RPG:
H BNDDIR('CRYPTO/CRYPTO') DFTACTGRP(*NO)
D/COPY CRYPTO/QCPYLESRC,@CRSP503
/FREE
// Generate a hash value based on the AppPassword variable
If GenHashValue (AppPassword
:10
:HashType
:OutputType
:OutputFmt
:HashValue
:MsgId
:MsgText);
// Success-> The hash is in HashValue variable
… logic …
Else;
// Errors-> Display MsgId and MsgText values
… logic …
Endif;
/END-FREE
Notes for GenHashValue:
A hash is a good technique for protecting and storing passwords used in an application. For instance, an application setup screen could prompt the user to establish a password they wish to use in that application. You could then generate a hash from that password and store this hash value in a database. When a user attempts to signon to an application with a password, you can hash the
Crypto Complete
Version 3.50 Linoma Software Page 59
password entered and compare it to the hash value stored in the database. If the hash values do not match, then you know the password is not valid.
Parameter Notes:
1 Valid hash types are MD5, SHA-1, SHA-256, SHA-384 and SHA-512.
2 OutputType valid values are *EBCDIC and *ASCII. If none is specified, then the default value of
*EBCDIC will be used. 3 OutputFmt valid values are *CHAR, *HEX and *BASE64. If none is specified, then the default value
of *CHAR will be used.
Crypto Complete
Version 3.50 Linoma Software Page 60
VfyCRVL001 – Verify CRVL001
The VfyCRVL001 procedure allows you to verify that the CRVL001 object is valid for your installation. This should generally only need to be executed after a system restore.
The CRVL001 object contains your organization’s key policy settings, key officers and master keys.
If the VfyCRVL001 returns a failure message, it is most likely because the CRVL001 object was copied from another machine (with a different serial number).
Procedure name: VfyCRVL001 Bind to Service Program: CRSP509 Prototype source member: @CRSP509 in CRYPTO/QCPYLESRC source file Parameters for VfyCRVL001 procedure:
Name Description Type Length In/Out
MsgId Message Id Alpha 7 Out
MsgText Message Text Alpha 80 Out
Example in /Free form RPG:
H BNDDIR('CRYPTO/CRYPTO') DFTACTGRP(*NO)
D/COPY CRYPTO/QCPYLESRC,@CRSP509
/FREE
// Verify CRVL001
If VfyCRVL001 ( MsgId
:MsgText);
// Success-> The CRVL001 object is valid
… logic …
Else;
// Errors-> The CRVL001 object is not valid
… logic …
Endif;
/END-FREE
Notes for CRVL001 object:
You should NOT copy the CRVL001 *VLDL object between machines with different serial numbers since the settings in CRVL001 are encrypted with the Product Encryption Key (PEK), which is unique per IBM i serial number.
Crypto Complete
Version 3.50 Linoma Software Page 61
PtgEnc – Encrypt text in Protegrity format
The PtgEnc procedure will encrypt text using a format which is compatible with Protegrity’s cryptographic functions. Procedure name: PtgEnc Bind to Service Program: CRSP512 Prototype source member: @CRSP512 in CRYPTO/QCPYLESRC source file Parameters for PtgEnc procedure:
Name Description Type Length In/Out Required
PlainText Plain Text Alpha 32768 In Yes
PlainTextLen Plain Text Length Integer 10,0 In Yes
KeyStrNam Key Store Name 1 Alpha 10 In No
KeyStrLib Key Store Library 2 Alpha 10 In No
KeyLabel Key Store Label Alpha 30 In Yes
LogCmt Audit Log Comment Alpha 50 In No
Algorithm Algorithm 3 Alpha 10 In Yes
Mode Mode 4 Alpha 5 In Yes
OutputType Output Type 5 Alpha 7 In No
OutputFmt Output Format 6 Alpha 7 In No
CRC Use CRC checksum 7 Alpha 4 In No
InitVector Initialization Vector (Salt) 8 Alpha 4 In Yes
CipherText Encrypted Text Alpha 32768 Out
CipherTextLen Encrypted Text Length Integer 10,0 Out
MsgId Message Id Alpha 7 Out
MsgText Message Text Alpha 80 Out
Return value: *ON if successful, *OFF if errors Parameter Notes:
1 Specify the special value of *DEFAULT for the Key Store Name in order to use the default key store
name indicated at the Key Policy level.
2 Specify *LIBL for the Key Store Library to locate the Key Store in the library list.
3 Algorithms supported are *TDES (for Triple DES), *AES128, *AES192 and *AES256
4 Mode supported is *CRC
5 OutputType valid values are *EBCDIC and *ASCII. If none is specified, then the default value of
*EBCDIC will be used.
6 OutputFmt valid values are *CHAR, *HEX and *BASE64. If none is specified, then the default value of
*CHAR will be used.
7 CRC Checksum; The valid values are *YES or *NO.
8 Initialization vector (IV): The valid values are *YES or *NO.
Crypto Complete
Version 3.50 Linoma Software Page 62
Example in /Free form RPG:
H BNDDIR('CRYPTO/CRYPTO') DFTACTGRP(*NO)
D/COPY CRYPTO/QCPYLESRC,@CRSP512
/FREE
// Encrypt the value in CreditCard variable using AES256 algorithm
If PtgEnc (CreditCard
:CreditCardLength
:‘OE_KEYS’
:‘*LIBL’
:‘CREDIT_CARD_KEY’
:‘Audit Log comment…’
:‘*AES256’
:‘*CRC’
:‘*EBCDIC’
:‘*CHAR’
:‘*YES’
:‘*YES’
:CipherText
:CipherTextLen
:MsgId
:MsgText);
// Success-> The encrypted value is in CipherText variable
… logic …
Else;
// Errors-> Display MsgId and MsgText values
… logic …
Endif;
/END-FREE
Additional Notes for PtgEnc:
When using *AES128, *AES192 and *AES256 algorithms, the returned Cipher Text length will be a minimum of 16 bytes long. This returned Cipher text length will be divisible by 16 or 24. For instance:
Plain Text Length Cipher Text Length
10 bytes 16 bytes
16 bytes 16 bytes
17 bytes 24 bytes
24 bytes 24 bytes
32 bytes 32 bytes
For *TDES algorithm, the returned Cipher Text length will be a minimum of 8 bytes long. This returned Cipher text length will be divisible by 8. For instance:
Plain Text Length Cipher Text Length
5 bytes 8 bytes
8 bytes 8 bytes
9 bytes 16 bytes
16 bytes 16 bytes
Crypto Complete
Version 3.50 Linoma Software Page 63
PtgDec – Decrypt text from Protegrity format
The PtgDec procedure will decrypt text from a format which was used by Protegrity’s cryptographic functions. Procedure name: PtgDec Bind to Service Program: CRSP512 Prototype source member: @CRSP512 in CRYPTO/QCPYLESRC source file Parameters for PtgDec procedure:
Name Description Type Length In/Out Required
CipherText Encrypted Text Alpha 32768 In Yes
CipherTextLen Encrypted Text Length Integer 10,0 In Yes
InputType Input Type 1 Alpha 7 In No
InputFmt Input Format 2 Alpha 7 In No
KeyStrNam Key Store Name 3 Alpha 10 In No
KeyStrLib Key Store Library 4 Alpha 10 In No
KeyLabel Key Store Label Alpha 30 In Yes
LogCmt Audit Log Comment Alpha 50 In No
Algorithm Algorithm 5 Alpha 10 In Yes
Mode Mode 6 Alpha 5 In Yes
CRC Use CRC checksum 7 Alpha 4 In No
InitVector Initialization Vector (Salt) 8 Alpha 4 In Yes
PlainText Plain Text Alpha 32768 Out
PlainTextLen Plain Text Length Integer 10,0 Out
MsgId Message Id Alpha 7 Out
MsgText Message Text Alpha 80 Out
Return value: *ON if successful, *OFF if errors Parameter Notes:
1 InputType valid values are *EBCDIC and *ASCII. If none is specified, then the default value of
*EBCDIC will be used.
2 InputFmt valid values are *CHAR, *HEX and *BASE64. If none is specified, then the default value of
*CHAR will be used.
3 Specify the special value of *DEFAULT for the Key Store Name in order to use the default key store
name indicated at the Key Policy level.
4 Specify *LIBL for the Key Store Library to locate the Key Store in the library list.
5 Algorithms supported are *TDES (for Triple DES), *AES128, *AES192 and *AES256
6 Mode supported is *CRC
7 CRC Checksum; The valid values are *YES or *NO.
8 Initialization vector (IV): The valid values are *YES or *NO.
Crypto Complete
Version 3.50 Linoma Software Page 64
Example in /Free form RPG:
H BNDDIR('CRYPTO/CRYPTO') DFTACTGRP(*NO)
D/COPY CRYPTO/QCPYLESRC,@CRSP512
/FREE
// Decrypt the value in CipherText variable using AES256 algorithm
If PtgDec (CipherText
:CipherTextLength
:‘*EBCDIC’
:‘*CHAR’
:‘OE_KEYS’
:‘*LIBL’
:‘CREDIT_CARD_KEY’
:‘Audit Log comment…’
:‘*AES256’
:‘*CRC ’
:‘*YES’
:‘*YES’
:CreditCard
:CreditCardLength
:MsgId
:MsgText);
// Success-> The decrypted value is in CreditCard variable
… logic …
Else;
// Errors-> Display MsgId and MsgText values
… logic …
Endif;
/END-FREE
Crypto Complete
Version 3.50 Linoma Software Page 65
Program APIs for Encryption/Decryption Crypto Complete includes program APIs which can be called for encrypting and decrypting text and field values from a variety of languages including RPG/400, ILE RPG, COBOL and CL. These programs are contained in the CRYPTO library. Program APIs if using Field Encryption Registry:
Program Name Description
CRRP615 Encrypt field value
CRRP616 Decrypt field value (Full value)
CRRP639 Decrypt field value (Masked value)
CRRP637 Decrypt field value (Authorized value)
CRRP617 Insert encrypted field value into external file
CRRP618 Update encrypted field value in external file
CRRP619 Delete encrypted field from external file
CRRP620 Get decrypted field value from external file (Full value)
CRRP640 Get decrypted field value from external file (Masked value)
CRRP638 Get decrypted field value from external file (Authorized value)
CRRP631 Get Field Attributes from Registry
CRRP621 Get active Field Identifier from Registry
CRRP622 Get current Key information for Field Identifier
CRRP627 Get first Key information for Field Identifier
CRRP628 Get next Key information for Field Identifier
CRRP625 Get External File information for Field Identifier
CRRP642 Get External Index for a Field Value from External File
CRRP626 Convert Index Number from Character to Decimal
Crypto Complete
Version 3.50 Linoma Software Page 66
Other Program APIs:
Program Name Description
CRRP600 Request a token to a Key contained in a Key Store
CRRP601 Release a token to a Key
CRRP602 Encrypt text with AES256 using Key token (ECB block mode)
CRRP603 Decrypt text with AES256 using Key token (ECB block mode)
CRRP604 Encrypt text with AES256 using Key label (ECB block mode)
CRRP605 Decrypt text with AES256 using Key label (ECB block mode)
CRRP606 Encrypt text with TDES using Key token (ECB block mode)
CRRP607 Decrypt text with TDES using Key token (ECB block mode)
CRRP608 Encrypt text with TDES using Key label (ECB block mode)
CRRP609 Decrypt text with TDES using Key label (ECB block mode)
CRRP633 Encrypt text with Advanced options using Key token
CRRP634 Decrypt text with Advanced options using Key token
CRRP635 Encrypt text with Advanced options using Key label
CRRP636 Decrypt text with Advanced options using Key label
CRRP614 Generate a SHA1 hash
CRRP632 Verify CRVL001 object
CRRP641 Close External File
CRRP643 Generate Hash Value (MD5, SHA-1, SHA-256, SHA-384, SHA-512)
Crypto Complete
Version 3.50 Linoma Software Page 67
CRRP615 – Encrypt Field Value
The CRRP615 program will encrypt a field value using the settings specified in the Field Encryption Registry. This program should only be used if all of the following conditions are met:
The field is registered and *ACTIVE in the Encryption Registry
Triggers are not used to automatically encrypt the field values
The encrypted values are not stored in an external file Parameters for CRRP615 program:
Name Description Type Length In/Out Required
FldId Field identifier Alpha 30 In Yes
PlainText Plain Text Alpha 32624 In Yes
LogCmt Audit Log Comment Alpha 50 In No
CipherText Encrypted Text Alpha 32624 Out
MsgId Message Id Alpha 7 Out
MsgText Message Text Alpha 80 Out
Errors Errors occurred (Y=Yes) Alpha 1 Out
Example in Fixed format RPG:
C* Encrypt value in PLAINTEXT variable using registry field id CCFIELD
C CALL 'CRRP615'
C PARM 'CCFIELD' FLDID 30
C PARM '123456789' PLAINTEXT 32624
C PARM 'log comment' LOGCMT 50
C PARM CIPHERTEXT 32624
C PARM MSGID 7
C PARM MSGTEXT 80
C PARM ERRORS 1
C* Success-> The encrypted value is contained in variable CIPHERTEXT
C IF ERRORS <> ‘Y’
C … Success logic …
C ELSE
C* Errors-> Display MSGID and MSGTEXT
C … Error logic …
C ENDIF
Crypto Complete
Version 3.50 Linoma Software Page 68
CRRP616 – Decrypt Field Value (Full value)
The CRRP616 program will decrypt a field value using the settings specified in the Field Encryption Registry.
The user will be authorized to the full decrypted value if they have 1) at least *USE authority to the ‘Full’ Authorization List specified for the field and 2) at least *USE authority to the Key Store which holds the Decryption Key. The names of the Authorization List and Key Store can be found for the field identifier in the Encryption Registry.
This program should only be used if all of the following conditions are met:
The field is registered and *ACTIVE in the Encryption Registry
The encrypted values are not stored in an external file Parameters for CRRP616 program:
Name Description Type Length In/Out Required
FldId Field identifier Alpha 30 In Yes
CipherText Encrypted Text Alpha 32624 In Yes
LogCmt Audit Log Comment Alpha 50 In No
PlainText Plain Text Alpha 32624 Out
MsgId Message Id Alpha 7 Out
MsgText Message Text Alpha 80 Out
Errors Errors occurred (Y=Yes) Alpha 1 Out
Example in Fixed format RPG:
C* Decrypt value in CIPHERTEXT variable using registry field id CCFIELD
C CALL 'CRRP616'
C PARM 'CCFIELD' FLDID 30
C PARM CIPHERTEXT 32624
C PARM 'log comment' LOGCMT 50
C PARM PLAINTEXT 32624
C PARM MSGID 7
C PARM MSGTEXT 80
C PARM ERRORS 1
C* Success-> The decrypted value is contained in variable PLAINTEXT
C IF ERRORS <> ‘Y’
C … Success logic …
C ELSE
C* Errors-> Display MSGID and MSGTEXT
C … Error logic …
C ENDIF
Crypto Complete
Version 3.50 Linoma Software Page 69
CRRP639 – Decrypt Field Value (Masked value)
The CRRP639 program will decrypt a field value and apply a mask, based on the settings specified in the Field Encryption Registry. For instance, if a mask of ‘************9999’ is specified in the Registry for a credit card number, then a sample of a returned credit card number would be ‘************1234’.
The user will be authorized to the masked value if they have 1) at least *USE authority to the ‘Masked’ Authorization List specified for the field and 2) at least *USE authority to the Key Store which holds the Decryption Key. The names of the Authorization List and Key Store can be found for the field identifier in the Encryption Registry.
This program should only be used if all of the following conditions are met:
The field is registered and *ACTIVE in the Encryption Registry
The field has a mask value specified in the Encryption Registry
The encrypted values are not stored in an external file Parameters for CRRP639 program:
Name Description Type Length In/Out Required
FldId Field identifier Alpha 30 In Yes
CipherText Encrypted Text Alpha 32624 In Yes
LogCmt Audit Log Comment Alpha 50 In No
PlainText Plain Text (masked) Alpha 32624 Out
MsgId Message Id Alpha 7 Out
MsgText Message Text Alpha 80 Out
Errors Errors occurred (Y=Yes) Alpha 1 Out
Example in Fixed format RPG:
C* Process value in CIPHERTEXT variable using registry field id CCFIELD
C CALL 'CRRP639'
C PARM 'CCFIELD' FLDID 30
C PARM CIPHERTEXT 32624
C PARM 'log comment' LOGCMT 50
C PARM MASKEDTEXT 32624
C PARM MSGID 7
C PARM MSGTEXT 80
C PARM ERRORS 1
C* Success-> The decrypted masked value is contained in variable MASKEDTEXT
C IF ERRORS <> ‘Y’
C … Success logic …
C ELSE
C* Errors-> Display MSGID and MSGTEXT
C … Error logic …
C ENDIF
Note: If a mask is not specified for the Field in the Registry, then no value will be returned.
Crypto Complete
Version 3.50 Linoma Software Page 70
CRRP637 – Decrypt Field Value (Authorized value)
Based on the user’s authority to the field, the CRRP637 program will return either 1) the fully decrypted value for the field or 2) the masked value for the field or 3) the not-authorized fill value that is specified for the field in the Registry, which may be blanks. The user’s authority to the field is determined by checking the Authority Lists indicated on the field’s AUTLDEC and AUTLMASK settings that are specified in the Field Encryption Registry. If a masked value is returned, the mask will be based on the field’s FLDMASK setting that is specified in the Field Encryption Registry. This program should only be used if all of the following conditions are met:
The field is registered and *ACTIVE in the Encryption Registry
The encrypted values are not stored in an external file Parameters for CRRP637 program:
Name Description Type Length In/Out Required
FldId Field identifier Alpha 30 In Yes
CipherText Encrypted Text Alpha 32624 In Yes
LogCmt Audit Log Comment Alpha 50 In No
OutputText Output Text Alpha 32624 Out
MsgId Message Id Alpha 7 Out
MsgText Message Text Alpha 80 Out
Errors Errors occurred (Y=Yes) Alpha 1 Out
Example in Fixed format RPG:
C* Decrypt value in CIPHERTEXT variable using registry field id CCFIELD
C CALL 'CRRP637'
C PARM 'CCFIELD' FLDID 30
C PARM CIPHERTEXT 32624
C PARM 'log comment' LOGCMT 50
C PARM OUTPUTTEXT 32624
C PARM MSGID 7
C PARM MSGTEXT 80
C PARM ERRORS 1
C* Success-> The returned value is in the OUTPUTTEXT variable.
C* Based on the user’s authorities, it returns either the fully
C* decrypted value, the masked value or a fill/blank value
C IF ERRORS <> ‘Y’
C … Success logic …
C ELSE
C* Errors-> Display MSGID and MSGTEXT
C … Error logic …
C ENDIF
Note: The users (or user groups) which should have access to the decrypted (or masked) values will also need at least *USE authority to the Key Store object which holds the Decryption Key.
Crypto Complete
Version 3.50 Linoma Software Page 71
CRRP617 – Insert Encrypted Field Value into External File
The CRRP617 program will encrypt a field value and insert it into the external file specified in the Field Encryption Registry. This program should only be used if all of the following conditions are met:
The field is registered and *ACTIVE in the Encryption Registry
Triggers are not used to automatically encrypt the field values
The encrypted values are stored in an external file Parameters for CRRP617 program:
Name Description Type Length In/Out Required
FldId Field identifier Alpha 30 In Yes
PlainText Plain Text Alpha 32624 In Yes
LogCmt Audit Log Comment Alpha 50 In No
ExtIndex Index number of value Packed 13,0 Out
MsgId Message Id Alpha 7 Out
MsgText Message Text Alpha 80 Out
Errors Errors occurred (Y=Yes) Alpha 1 Out
Example in Fixed format RPG:
C* Encrypt value in PLAINTEXT variable and insert into external file
C CALL 'CRRP617'
C PARM 'CCFIELD' FLDID 30
C PARM '123456789' PLAINTEXT 32624
C PARM 'log comment' LOGCMT 50
C PARM EXTINDEX 13 0
C PARM MSGID 7
C PARM MSGTEXT 80
C PARM ERRORS 1
C* Success-> Store the EXTINDEX (index number) in the existing db field
C IF ERRORS <> ‘Y’
C … Success logic …
C ELSE
C* Errors-> Display MSGID and MSGTEXT
C … Error logic …
C ENDIF
Crypto Complete
Version 3.50 Linoma Software Page 72
CRRP618 – Update Encrypted Field Value in External File
The CRRP618 program will encrypt a field value and update the record in the external file with this encrypted value. The name of the external file is specified in the Field Encryption Registry. This program should only be used if all of the following conditions are met:
The field is registered and *ACTIVE in the Encryption Registry
Triggers are not used to automatically encrypt the field values
The encrypted values are stored in an external file Parameters for CRRP618 program:
Name Description Type Length In/Out Required
FldId Field identifier Alpha 30 In Yes
ExtIndex Index number of value Packed 13,0 In Yes
PlainText Plain Text Alpha 32624 In Yes
LogCmt Audit Log Comment Alpha 50 In No
MsgId Message Id Alpha 7 Out
MsgText Message Text Alpha 80 Out
Errors Errors occurred (Y=Yes) Alpha 1 Out
Example in Fixed format RPG:
C* Convert the index number (stored in CCNO) from alphanumeric to decimal
C EVAL EXTINDEX = %DEC(CCNO:16:0)
C* Using the index specified in EXTINDEX, encrypt value in PLAINTEXT
C* variable and update in external file
C CALL 'CRRP618'
C PARM 'CCFIELD' FLDID 30
C PARM EXTINDEX 13 0
C PARM '123456789' PLAINTEXT 32624
C PARM 'log comment' LOGCMT 50
C PARM MSGID 7
C PARM MSGTEXT 80
C PARM ERRORS 1
C* Success-> Encrypted value was stored
C IF ERRORS <> ‘Y’
C … Success logic …
C ELSE
C* Errors-> Display MSGID and MSGTEXT
C … Error logic …
C ENDIF
Crypto Complete
Version 3.50 Linoma Software Page 73
CRRP619 – Delete Encrypted Field Value from External File
The CRRP619 program will remove the encrypted field value from the external file. The name of the external file is specified in the Field Encryption Registry. This program should only be used if all of the following conditions are met:
The field is registered and *ACTIVE in the Encryption Registry
Triggers are not used to automatically encrypt the field values
The encrypted values are stored in an external file Parameters for CRRP619 program:
Name Description Type Length In/Out Required
FldId Field identifier Alpha 30 In Yes
ExtIndex Index number of value Packed 13,0 In Yes
MsgId Message Id Alpha 7 Out
MsgText Message Text Alpha 80 Out
Errors Errors occurred (Y=Yes) Alpha 1 Out
Example in Fixed format RPG:
C* Convert the index number (stored in CCNO) from alphanumeric to decimal
C EVAL EXTINDEX = %DEC(CCNO:16:0)
C* Using the index specified in EXTINDEX, remove the encrypted value
C* from the external file
C CALL 'CRRP619'
C PARM 'CCFIELD' FLDID 30
C PARM EXTINDEX 13 0
C PARM MSGID 7
C PARM MSGTEXT 80
C PARM ERRORS 1
C* Success-> Encrypted value was removed
C IF ERRORS <> ‘Y’
C … Success logic …
C ELSE
C* Errors-> Display MSGID and MSGTEXT
C … Error logic …
C ENDIF
Crypto Complete
Version 3.50 Linoma Software Page 74
CRRP620 – Get Decrypted Field Value from External File (Full value)
The CRRP620 program will retrieve an encrypted field value from an external file and decrypt it for use in the application. The name of the external file is specified in the Field Encryption Registry.
The user will be authorized to the full decrypted value if they have 1) at least *USE authority to the ‘Full’ Authorization List specified for the field and 2) at least *USE authority to the Key Store which holds the Decryption Key. The names of the Authorization List and Key Store can be found for the field identifier in the Encryption Registry.
This program should only be used if all of the following conditions are met:
The field is registered and *ACTIVE in the Encryption Registry
The encrypted values are stored in an external file Parameters for CRRP620 program:
Name Description Type Length In/Out Required
FldId Field identifier Alpha 30 In Yes
ExtIndex Index number of value Packed 13,0 In Yes
LogCmt Audit Log Comment Alpha 50 In No
PlainText Plain Text Alpha 32624 Out
MsgId Message Id Alpha 7 Out
MsgText Message Text Alpha 80 Out
Errors Errors occurred (Y=Yes) Alpha 1 Out
Example in Fixed format RPG:
C* Convert the index number (stored in CCNO) from alphanumeric to decimal
C EVAL EXTINDEX = %DEC(CCNO:16:0)
C* Using the index specified in EXTINDEX, retrieve the value from the
C* external file, decrypt and return it.
C CALL 'CRRP620'
C PARM 'CCFIELD' FLDID 30
C PARM EXTINDEX 13 0
C PARM 'log comment' LOGCMT 50
C PARM PLAINTEXT 32624
C PARM MSGID 7
C PARM MSGTEXT 80
C PARM ERRORS 1
C* Success-> Decrypted value is in PLAINTEXT variable
C IF ERRORS <> ‘Y’
C … Success logic …
C ELSE
C* Errors-> Display MSGID and MSGTEXT
C … Error logic …
C ENDIF
Crypto Complete
Version 3.50 Linoma Software Page 75
CRRP640 – Get Decrypted Field Value from External File (Masked value)
The CRRP640 program will retrieve an encrypted field value from an external file, then decrypt it and apply a mask, based on the settings specified in the Field Encryption Registry. For instance, if a mask of ‘************9999’ is specified in the Registry for a credit card number, then a sample of a returned credit card number would be ‘************1234’.
The user will be authorized to the masked value if they have 1) at least *USE authority to the ‘Masked’ Authorization List specified for the field and 2) at least *USE authority to the Key Store which holds the Decryption Key. The names of the Authorization List and Key Store can be found for the field identifier in the Encryption Registry.
This program should only be used if all of the following conditions are met:
The field is registered and *ACTIVE in the Encryption Registry
The field has a mask value specified in the Encryption Registry
The encrypted values are stored in an external file Parameters for CRRP640 program:
Name Description Type Length In/Out Required
FldId Field identifier Alpha 30 In Yes
ExtIndex Index number of value Packed 13,0 In Yes
LogCmt Audit Log Comment Alpha 50 In No
PlainText Plain Text (masked) Alpha 32624 Out
MsgId Message Id Alpha 7 Out
MsgText Message Text Alpha 80 Out
Errors Errors occurred (Y=Yes) Alpha 1 Out
Example in Fixed format RPG:
C* Convert the index number (stored in CCNO) from alphanumeric to decimal
C EVAL EXTINDEX = %DEC(CCNO:16:0)
C* Using the index specified in EXTINDEX, retrieve the value from the
C* external file, decrypt, mask and return it.
C CALL 'CRRP640'
C PARM 'CCFIELD' FLDID 30
C PARM EXTINDEX 13 0
C PARM 'log comment' LOGCMT 50
C PARM MASKEDTEXT 32624
C PARM MSGID 7
C PARM MSGTEXT 80
C PARM ERRORS 1
C* Success-> The decrypted masked value is in the MASKEDTEXT variable
C IF ERRORS <> ‘Y’
C … Success logic …
C ELSE
C* Errors-> Display MSGID and MSGTEXT
C … Error logic …
C ENDIF
Note: If a mask is not specified for the Field in the Registry, then no value will be returned.
Crypto Complete
Version 3.50 Linoma Software Page 76
CRRP638 – Get Decrypted Field Value from External File (Authorized value)
The CRRP638 can be used if the encrypted field values are stored in an external file. Based on the user’s authority to the field, the CRRP638 program will return either 1) the fully decrypted value for the field or 2) the masked value for the field or 3) the not-authorized fill value that is specified for the field in the Registry, which may be blanks. The user’s authority to the field is determined by checking the Authority Lists indicated on the field’s AUTLDEC and AUTLMASK settings that are specified in the Field Encryption Registry. If a masked value is returned, the mask will be based on the field’s FLDMASK setting that is specified in the Field Encryption Registry. This program should only be used if all of the following conditions are met:
The field is registered and *ACTIVE in the Encryption Registry
The encrypted values are stored in an external file Parameters for CRRP638 program:
Name Description Type Length In/Out Required
FldId Field identifier Alpha 30 In Yes
ExtIndex Index number of value Packed 13,0 In Yes
LogCmt Audit Log Comment Alpha 50 In No
OutputText Output Text Alpha 32624 Out
MsgId Message Id Alpha 7 Out
MsgText Message Text Alpha 80 Out
Errors Errors occurred (Y=Yes) Alpha 1 Out
Example in Fixed format RPG:
C* Convert the index number (stored in CCNO) from alphanumeric to decimal
C EVAL EXTINDEX = %DEC(CCNO:16:0)
C* Using the index specified in EXTINDEX, retrieve the encrypted value
C* from the external file. Based on the user’s authorities, it returns
C* either the fully decrypted value, the masked value or a fill/blank
C* value.
C CALL 'CRRP638'
C PARM 'CCFIELD' FLDID 30
C PARM EXTINDEX 13 0
C PARM 'log comment' LOGCMT 50
C PARM OUTPUTTEXT 32624
C PARM MSGID 7
C PARM MSGTEXT 80
C PARM ERRORS 1
C* Success-> The returned value is in the OUTPUTTEXT variable
C IF ERRORS <> ‘Y’
C … Success logic …
C ELSE
C* Errors-> Display MSGID and MSGTEXT
C … Error logic …
C ENDIF
Note: The users (or user groups) which should have access to the decrypted (or masked) values will also need at least *USE authority to the Key Store object which holds the Decryption Key.
Crypto Complete
Version 3.50 Linoma Software Page 77
CRRP631 – Get Attributes for Field Identifier
The CRRP631 program will return certain attributes for the specified Field Identifier, such as the field status, mask value, database field type, length and decimal positions. This information will be retrieved from the Field Encryption Registry. Parameters for CRRP631 program:
Name Description Type Length In/Out Required
FldId Field identifier Alpha 30 In Yes
Attribute Attribute name 1 Alpha 30 In Yes
Value Value 2 Alpha 30 Out
MsgId Message Id Alpha 7 Out
MsgText Message Text Alpha 80 Out
Errors Errors occurred (Y=Yes) Alpha 80 Out
Parameter Notes:
1 The type of attribute to retrieve for the field:
*CIPHERLEN – The calculated length of the encrypted value.
*FLDDEC – The number of decimal positions for the database field.
*FLDLEN – The length of the database field.
*FLDTYP – The type of the database field. Possible returned values are *CHAR and *DEC.
*MASK – The masked value for the field
*STATUS – The status of the field in the registry. Possible returned values are *ACTIVE, *INACTIVE, *ERROR, *PROCESS and *UNKNOWN.
2 The value returned for the attribute
Example in /Free form RPG:
C* Get the status for field id ‘CCFIELD’
C CALL 'CRRP631'
C PARM 'CCFIELD’ FLDID 30
C PARM '*STATUS' FLDATTR 30
C PARM FLDVALUE 30
C PARM MSGID 7
C PARM MSGTEXT 80
C PARM ERRORS 1
C* Success-> The status of the Field is in FLDVALUE
C IF ERRORS <> ‘Y’
C … Success logic …
C ELSE
C* Errors-> Display MSGID and MSGTEXT
C … Error logic …
C ENDIF
Crypto Complete
Version 3.50 Linoma Software Page 78
CRRP621 – Get active Field Identifier from Registry
The CRRP621 program will retrieve the name of the active Field Identifier (within the Encryption Registry) for the specified database field name, file name and library. This program is useful if you know the database field name and you want to programmatically determine its corresponding Field Identifier to use for the Field APIs (such as CRRP620). Parameters for CRRP621:
Name Description Type Length In/Out Required
DbFld Database field name Alpha 30 In Yes
DbFile Database file name Alpha 10 In Yes
DbLib Database library name Alpha 10 In Yes
FldId Field identifier Alpha 30 Out
MsgId Message Id Alpha 7 Out
MsgText Message Text Alpha 80 Out
Errors Errors occurred (Y=Yes) Alpha 1 Out
Example in Fixed format RPG:
C* Get the active Field Identifier for the database field CCNO in
C* the file OELIB/ORDERS
C CALL 'CRRP621'
C PARM 'CCNO' DBFLD 30
C PARM 'ORDERS' DBFILE 10
C PARM 'OELIB' DBLIB 10
C PARM FLDID 30
C PARM MSGID 7
C PARM MSGTEXT 80
C PARM ERRORS 1
C* Success-> The Field Identifier name is in the FLDID variable
C IF ERRORS <> ‘Y’
C … Success logic …
C ELSE
C* Errors-> Display MSGID and MSGTEXT
C … Error logic …
C ENDIF
Crypto Complete
Version 3.50 Linoma Software Page 79
CRRP622 – Get Current Key information for Field Identifier
The CRRP622 program will retrieve the current set of encryption/decryption Key Labels and Key Store names for the specified Field Identifier. This information will be retrieved from the Field Encryption Registry. This program is useful if you want to programmatically determine the Keys to use for other encryption/decryption APIs (such as CRRP604). Parameters for CRRP622 program:
Name Description Type Length In/Out Required
FldId Field identifier Alpha 30 In Yes
EncKeyStrNam Encryption Key Store Name Alpha 10 Out
EncKeyStrLib Encryption Key Store Library Alpha 10 Out
EncKeyLabel Encryption Key Label Alpha 30 Out
DecKeyStrNam Decryption Key Store Name Alpha 10 Out
DecKeyStrLib Decryption Key Store Library Alpha 10 Out
DecKeyLabel Decryption Key Label Alpha 30 Out
MsgId Message Id Alpha 7 Out
MsgText Message Text Alpha 80 Out
Errors Errors occurred (Y=Yes) Alpha 1 Out
Example in Fixed format RPG:
C* Get the current set of Key Labels and Key Stores used for ‘CCFIELD’
C CALL 'CRRP622'
C PARM 'CCFIELD' FLDID 30
C PARM ENCKEYSTRNAM 10
C PARM ENCKEYSTRLIB 10
C PARM ENCKEYLABEL 30
C PARM DECKEYSTRNAM 10
C PARM DECKEYSTRLIB 10
C PARM DECKEYLABEL 30
C PARM MSGID 7
C PARM MSGTEXT 80
C PARM ERRORS 1
C* Success-> Current set of Keys found
C IF ERRORS <> ‘Y’
C … Success logic …
C ELSE
C* Errors-> Display MSGID and MSGTEXT
C … Error logic …
C ENDIF
Crypto Complete
Version 3.50 Linoma Software Page 80
CRRP627 – Get First Key information for Field Identifier
The CRRP627 program will retrieve the first set of encryption/decryption Key Labels and Key Store names used for the specified Field Identifier. This information will be retrieved from the Field Encryption Registry. If field values are still encrypted under older (non-current) Keys, this program is useful if you want to programmatically determine the Keys to use for the decryption program APIs (such as CRRP605). Parameters for CRRP627 program:
Name Description Type Length In/Out Required
FldId Field identifier Alpha 30 In Yes
KeyId Key identifier Packed 5,0 Out
EncKeyStrNam Encryption Key Store Name Alpha 10 Out
EncKeyStrLib Encryption Key Store Library Alpha 10 Out
EncKeyLabel Encryption Key Label Alpha 30 Out
DecKeyStrNam Decryption Key Store Name Alpha 10 Out
DecKeyStrLib Decryption Key Store Library Alpha 10 Out
DecKeyLabel Decryption Key Label Alpha 30 Out
MsgId Message Id Alpha 7 Out
MsgText Message Text Alpha 80 Out
Errors Errors occurred (Y=Yes) Alpha 1 Out
Example in Fixed format RPG:
C* Get the first set of Key Labels and Key Stores used for ‘CCFIELD’
C CALL 'CRRP627'
C PARM 'CCFIELD' FLDID 30
C PARM KEYID 5 0
C PARM ENCKEYSTRNAM 10
C PARM ENCKEYSTRLIB 10
C PARM ENCKEYLABEL 30
C PARM DECKEYSTRNAM 10
C PARM DECKEYSTRLIB 10
C PARM DECKEYLABEL 30
C PARM MSGID 7
C PARM MSGTEXT 80
C PARM ERRORS 1
C* Success-> First set of Keys found
C IF ERRORS <> ‘Y’
C … Success logic …
C ELSE
C* Errors-> Display MSGID and MSGTEXT
C … Error logic …
C ENDIF
Crypto Complete
Version 3.50 Linoma Software Page 81
CRRP628 – Get Next Key information for Field Identifier
After executing the CRRP627 program (to get the first set of Keys), you can execute the CRRP628 program to retrieve the next set of encryption/decryption Key Labels and Key Store names used for the specified Field Identifier. This information will be retrieved from the Field Encryption Registry. If field values are still encrypted under older (non-current) Keys, this program is useful if you want to programmatically determine the Keys to use for the decryption program APIs (such as CRRP605). Parameters for CRRP628 program:
Name Description Type Length In/Out Required
FldId Field identifier Alpha 30 In Yes
InKeyId Previous Key identifier (in) Packed 5,0 In Yes
OutKeyId Next Key identifier (out) Packed 5,0 Out
EncKeyStrNam Encryption Key Store Name Alpha 10 Out
EncKeyStrLib Encryption Key Store Library Alpha 10 Out
EncKeyLabel Encryption Key Label Alpha 30 Out
DecKeyStrNam Decryption Key Store Name Alpha 10 Out
DecKeyStrLib Decryption Key Store Library Alpha 10 Out
DecKeyLabel Decryption Key Label Alpha 30 Out
MsgId Message Id Alpha 7 Out
MsgText Message Text Alpha 80 Out
Errors Errors occurred (Y=Yes) Alpha 1 Out
Example in Fixed format RPG:
C* Get the next set of Key Labels and Key Stores used for ‘CCFIELD’
C CALL 'CRRP628'
C PARM 'CCFIELD' FLDID 30
C PARM INKEYID 5 0
C PARM OUTKEYID 5 0
C PARM ENCKEYSTRNAM 10
C PARM ENCKEYSTRLIB 10
C PARM ENCKEYLABEL 30
C PARM DECKEYSTRNAM 10
C PARM DECKEYSTRLIB 10
C PARM DECKEYLABEL 30
C PARM MSGID 7
C PARM MSGTEXT 80
C PARM ERRORS 1
C* Success-> Next set of Keys found
C IF ERRORS <> ‘Y’
C … Success logic …
C ELSE
C* Errors-> Display MSGID and MSGTEXT
C … Error logic …
C ENDIF
Crypto Complete
Version 3.50 Linoma Software Page 82
CRRP625 – Get External File Information for Field Identifier
The CRRP625 program will return the name and library of the external physical file which contains the encrypted values for the specified Field Identifier. If a logical file is based on the external physical file, then the name and library of this logical file will also be returned. This information will be retrieved from the Field Encryption Registry. Parameters for CRRP625 program:
Name Description Type Length In/Out Required
FldId Field identifier Alpha 30 In Yes
ExtFile External Physical File Name Alpha 10 Out
ExtLib External Physical File Library Alpha 10 Out
ExtFileL External Logical File Name Alpha 10 Out
ExtLibL External Logical File Library Alpha 10 Out
MsgId Message Id Alpha 7 Out
MsgText Message Text Alpha 80 Out
Errors Errors occurred (Y=Yes) Alpha 1 Out
Example in Fixed format RPG:
C* Get the External file name and library used for field id ‘CCFIELD’
C CALL 'CRRP625'
C PARM 'CCFIELD' FLDID 30
C PARM EXTFILE 10
C PARM EXTLIB 10
C PARM EXTFILEL 10
C PARM EXTLIBL 10
C PARM MSGID 7
C PARM MSGTEXT 80
C PARM ERRORS 1
C* Success-> External file information found. The physical file name
C* and library is in EXTFILE and EXTLIB. The logical file name and
C* library is in EXTFILEL and EXTLIBL.
C IF ERRORS <> ‘Y’
C … Success logic …
C ELSE
C* Errors-> Display MSGID and MSGTEXT
C … Error logic …
C ENDIF
Crypto Complete
Version 3.50 Linoma Software Page 83
CRRP642 – Get Index for a Field Value from External File
The CRRP642 program will return the first external Index number found for the plain text value specified. If no record is found, then a 0 will be returned for the Index. This program should only be used if the field is active in the Field Encryption Registry and the encrypted values are stored in an external file. Parameters for CRRP642 program:
Name Description Type Length In/Out Required
FldId Field Identifier Alpha 30 In Yes
PlainText Plain Text Alpha 32624 In Yes
ExtIndex Index of Value Packed 13,0 Out
MsgId Message Id Alpha 7 Out
MsgText Message Text Alpha 80 Out
Errors Errors Occurred (Y=Yes) Alpha 1 Out
Example in Fixed format RPG: C* Get the external index for the CCNO using registry field id CCFIELD
C CALL 'CRRP642'
C PARM 'CCFIELD' FLDID 30
C PARM CCNO PLAINTEXT 32624
C PARM EXTINDEX 13 0
C PARM MSGID 7
C PARM MSGTEXT 80
C PARM ERRORS 1
C* Success-> No errors occurred. Check if External Index was found (not 0)
C IF ERRORS <> ‘Y’
C … Success logic …
C ELSE
C* Errors-> Display MSGID and MSGTEXT
C … Error logic …
C ENDIF
Crypto Complete
Version 3.50 Linoma Software Page 84
CRRP626 – Convert Index Number from Character to Decimal
The CRRP626 program will convert an index number from a character value into a numeric value. This program will additionally strip any padding characters that may be contained in the index number. The CRRP626 program is useful for converting an index number into its numeric format before calling the CRRP620 (Get Decrypted Field Value from External File) program. Parameters for CRRP626 program:
Name Description Type Length In/Out Required
FldId Field identifier Alpha 30 In Yes
ExtIndex External Index Nbr. - Char Alpha 34 In Yes
ExtIndexDec External Index Nbr. - Dec Packed 13,0 Out
MsgId Message Id Alpha 7 Out
MsgText Message Text Alpha 80 Out
Errors Errors occurred (Y=Yes) Alpha 1 Out
Example in Fixed format RPG:
C* Move in the index number from the alphanumeric database field
C EVAL EXTINDEX = CCNO
C* Convert the index number into numeric format for field id ‘CCFIELD’
C CALL 'CRRP626'
C PARM 'CCFIELD' FLDID 30
C PARM EXTINDEX 34
C PARM EXTINDEXDEC 13 0
C PARM MSGID 7
C PARM MSGTEXT 80
C PARM ERRORS 1
C* No errors on conversion
C IF ERRORS <> ‘Y’
C* Using the numeric index specified in EXTINDEXDEC, retrieve the value
C* from the external file, decrypt and return it.
C CALL 'CRRP620'
C PARM 'CCFIELD' FLDID 30
C PARM EXTINDEXDEC 13 0
C PARM 'log comment' LOGCMT 50
C PARM PLAINTEXT 32624
C PARM MSGID 7
C PARM MSGTEXT 80
C PARM ERRORS 1
C* Success-> Decrypted value is in PLAINTEXT variable
C IF ERRORS <> ‘Y’
C … Success logic …
C ELSE
C* Errors-> Display MSGID and MSGTEXT
C … Error logic …
C ENDIF
C ENDIF
Crypto Complete
Version 3.50 Linoma Software Page 85
CRRP600 – Request a token to a Key contained in a Key Store
The CRRP600 program will request a token to a Key contained in a Key Store. This token can then be used in encryption/decryption programs which are token based (i.e. CRRP602 and CRRP603). Using tokens to encrypt and decrypt data is recommended for optimal performance since the key does not need to be retrieved from the Key Store and validated for each decrypt or encrypt operation. Parameters for CRRP600 program:
Name Description Type Length In/Out Required
KeyStrNam Key Store Name 1 Alpha 10 In No
KeyStrLib Key Store Library 2 Alpha 10 In No
KeyLabel Key Label Alpha 30 In Yes
KeyTkn Key Token Alpha 8 Out
MsgId Message Id (if errors) Alpha 7 Out
MsgText Message Text (if errors) Alpha 80 Out
Errors Errors occurred (Y=Yes) Alpha 1 Out
Parameter Notes:
1 Specify the special value of *DEFAULT for the Key Store Name in order to use the default key store
name indicated at the Key Policy level.
2 Specify *LIBL for the Key Store Library to locate the Key Store in the library list.
Example in Fixed format RPG:
C* Request a token to a Key
C CALL 'CRRP600'
C PARM 'OE_KEYS' KEYSTRNAM 10
C PARM '*LIBL' KEYSTRLIB 10
C PARM 'CARD_KEY’ KEYLABEL 30
C PARM KEYTKN 8
C PARM MSGID 7
C PARM MSGTEXT 80
C PARM ERRORS 1
C* Success-> Key token contained in KEYTKN
C IF ERRORS <> ‘Y’
C … Success logic …
C ELSE
C* Errors-> Display MSGID and MSGTEXT
C … Error logic …
C ENDIF
Additional notes for CRRP600:
Each Key token will represent a unique Key Label contained in a Key Store.
Up to 99 Key tokens at a time can be active in memory per job.
When a token is no longer needed, the token can be released with the CRRP601 program.
Crypto Complete
Version 3.50 Linoma Software Page 86
CRRP601 – Release a token to a Key
The CRRP601 program will release a token to a Key. It is recommended to release tokens when they are no longer needed in order to minimize memory usage. Parameters for CRRP601 program:
Name Description Type Length In/Out Required
KeyTkn Key Token Alpha 8 Out
MsgId Message Id (if errors) Alpha 7 Out
MsgText Message Text (if errors) Alpha 80 Out
Errors Errors occurred (Y=Yes) Alpha 1 Out
Example in Fixed format RPG:
C* Release a token to a Key
C CALL 'CRRP601'
C PARM KEYTKN 8
C PARM MSGID 7
C PARM MSGTEXT 80
C PARM ERRORS 1
C* Success-> Key token released
C IF ERRORS <> ‘Y’
C … Success logic …
C ELSE
C* Errors-> Display MSGID and MSGTEXT
C … Error logic …
C ENDIF
Crypto Complete
Version 3.50 Linoma Software Page 87
CRRP602 – Encrypt text with AES256 using Key Token (ECB block mode)
The CRRP602 program will encrypt text using the AES256 algorithm and ECB block mode. This program requires a Key Token, which can be acquired through the CRRP600 program. Parameters for CRRP602 program:
Name Description Type Length In/Out Required
PlainText Plain Text Alpha 32624 In Yes
PlainTextLen Plain Text Length Packed 5,0 In Yes
KeyTkn Key Token Alpha 8 In Yes
LogCmt Audit Log Comment Alpha 50 In No
CipherText Encrypted Text Alpha 32624 Out
CipherTextLen Encrypted Text Length 1 Packed 5,0 Out
MsgId Message Id Alpha 7 Out
MsgText Message Text Alpha 80 Out
Errors Errors occurred (Y=Yes) Alpha 1 Out
Parameter Notes:
1 With AES block mode, the returned Cipher Text length will be a minimum of 16 bytes long. This
returned Cipher text length will be divisible by 16 or 24. For instance:
Plain Text Length Cipher Text Length
10 bytes 16 bytes
16 bytes 16 bytes
17 bytes 24 bytes
24 bytes 24 bytes
32 bytes 32 bytes
Example in Fixed format RPG:
C* Encrypt value in variable PLAINTEXT
C CALL 'CRRP602'
C PARM '123456789' PLAINTEXT 32624
C PARM 9 PLAINLEN 5 0
C PARM KEYTKN 8
C PARM 'log comment' LOGCMT 50
C PARM CIPHERTEXT 32624
C PARM CIPHERLEN 5 0
C PARM MSGID 7
C PARM MSGTEXT 80
C PARM ERRORS 1
C* Success-> The encrypted value is contained in variable CIPHERTEXT
C IF ERRORS <> ‘Y’
C … Success logic …
C ELSE
C* Errors-> Display MSGID and MSGTEXT
C … Error logic …
C ENDIF
Crypto Complete
Version 3.50 Linoma Software Page 88
CRRP603 – Decrypt text with AES256 using Key Token (ECB block mode)
The CRRP603 program will decrypt text using the AES256 algorithm and ECB block mode. This program requires a Key Token, which can be acquired through the CRRP600 program. Parameters for CRRP603 program:
Name Description Type Length In/Out Required
CipherText Encrypted Text Alpha 32624 In Yes
CipherTextLen Encrypted Text Length Packed 5,0 In Yes
KeyTkn Key Token Alpha 8 In Yes
LogCmt Audit Log Comment Alpha 50 In No
PlainText Plain Text Alpha 32624 Out
PlainTextLen Plain Text Length Packed 5,0 Out
MsgId Message Id Alpha 7 Out
MsgText Message Text Alpha 80 Out
Errors Errors occurred (Y=Yes) Alpha 1 Out
Example in Fixed format RPG:
C* Decrypt value in variable CIPHERTEXT
C CALL 'CRRP603'
C PARM CIPHERTEXT 32624
C PARM CIPHERLEN 5 0
C PARM KEYTKN 8
C PARM 'log comment' LOGCMT 50
C PARM PLAINTEXT 32624
C PARM PLAINLEN 5 0
C PARM MSGID 7
C PARM MSGTEXT 80
C PARM ERRORS 1
C* Success-> The decrypted value is contained in variable PLAINTEXT
C IF ERRORS <> ‘Y’
C … Success logic …
C ELSE
C* Errors-> Display MSGID and MSGTEXT
C … Error logic …
C ENDIF
Crypto Complete
Version 3.50 Linoma Software Page 89
CRRP604 – Encrypt text with AES256 using Key Label (ECB block mode)
The CRRP604 program will encrypt text using the AES256 algorithm and ECB block mode. This program requires a Key Label. Parameters for CRRP604 program:
Name Description Type Length In/Out Required
PlainText Plain Text Alpha 32624 In Yes
PlainTextLen Plain Text Length Packed 5,0 In Yes
KeyStrNam Key Store Name 1 Alpha 10 In No
KeyStrLib Key Store Library 2 Alpha 10 In No
KeyLabel Key Label Alpha 30 In Yes
LogCmt Audit Log Comment Alpha 50 In No
CipherText Encrypted Text Alpha 32624 Out
CipherTextLen Encrypted Text Length 3 Packed 5,0 Out
MsgId Message Id Alpha 7 Out
MsgText Message Text Alpha 80 Out
Errors Errors occurred (Y=Yes) Alpha 1 Out
Parameter Notes:
1 Specify the special value of *DEFAULT for the Key Store Name in order to use the default key store
name indicated at the Key Policy level.
2 Specify *LIBL for the Key Store Library to locate the Key Store in the library list.
3 With AES block mode, the returned Cipher Text length will be a minimum of 16 bytes long. This
returned Cipher text length will be divisible by 16 or 24. For instance:
Plain Text Length Cipher Text Length
10 bytes 16 bytes
16 bytes 16 bytes
17 bytes 24 bytes
24 bytes 24 bytes
32 bytes 32 bytes
(view source example on next page)
Crypto Complete
Version 3.50 Linoma Software Page 90
CRRP604 Example in Fixed format RPG:
C* Encrypt value in variable PLAINTEXT using key label CARD_KEY
C CALL 'CRRP604'
C PARM '123456789' PLAINTEXT 32624
C PARM 9 PLAINLEN 5 0
C PARM 'OE_KEYS' KEYSTRNAM 10
C PARM '*LIBL' KEYSTRLIB 10
C PARM 'CARD_KEY’ KEYLABEL 30
C PARM 'log comment' LOGCMT 50
C PARM CIPHERTEXT 32624
C PARM CIPHERLEN 5 0
C PARM MSGID 7
C PARM MSGTEXT 80
C PARM ERRORS 1
C* Success-> The encrypted value is contained in variable CIPHERTEXT
C IF ERRORS <> ‘Y’
C … Success logic …
C ELSE
C* Errors-> Display MSGID and MSGTEXT
C … Error logic …
C ENDIF
Crypto Complete
Version 3.50 Linoma Software Page 91
CRRP605 – Decrypt text with AES256 using Key Label (ECB block mode)
The CRRP605 program will decrypt text using the AES256 algorithm and ECB block mode. This program requires a Key Label. Parameters for CRRP605 program:
Name Description Type Length In/Out Required
CipherText Encrypted Text Alpha 32624 In Yes
CipherTextLen Encrypted Text Length Packed 5,0 In Yes
KeyStrNam Key Store Name 1 Alpha 10 In No
KeyStrLib Key Store Library 2 Alpha 10 In No
KeyLabel Key Store Label Alpha 30 In Yes
LogCmt Audit Log Comment Alpha 50 In No
PlainText Plain Text Alpha 32624 Out
PlainTextLen Plain Text Length Packed 5,0 Out
MsgId Message Id Alpha 7 Out
MsgText Message Text Alpha 80 Out
Errors Errors occurred (Y=Yes) Alpha 1 Out
Parameter notes:
1 Specify the special value of *DEFAULT for the Key Store Name in order to use the default key store
name indicated at the Key Policy level.
2 Specify *LIBL for the Key Store Library to locate the Key Store in the library list.
CRRP605 example in Fixed format RPG:
C* Decrypt value in variable CIPHERTEXT using key label CARD_KEY
C CALL 'CRRP605'
C PARM CIPHERTEXT 32624
C PARM CIPHERLEN 5 0
C PARM 'OE_KEYS' KEYSTRNAM 10
C PARM '*LIBL' KEYSTRLIB 10
C PARM 'CARD_KEY’ KEYLABEL 30
C PARM 'log comment' LOGCMT 50
C PARM PLAINTEXT 32624
C PARM PLAINLEN 5 0
C PARM MSGID 7
C PARM MSGTEXT 80
C PARM ERRORS 1
C* Success-> The decrypted value is contained in variable PLAINTEXT
C IF ERRORS <> ‘Y’
C … Success logic …
C ELSE
C* Errors-> Display MSGID and MSGTEXT
C … Error logic …
C ENDIF
Crypto Complete
Version 3.50 Linoma Software Page 92
CRRP606 – Encrypt text with TDES using Key Token (ECB block mode)
The CRRP606 program will encrypt text using the TDES (Triple DES) algorithm and ECB block mode. This program requires a Key Token, which can be acquired through the CRRP600 program. Parameters for CRRP606 program:
Name Description Type Length In/Out Required
PlainText Plain Text Alpha 32624 In Yes
PlainTextLen Plain Text Length Packed 5,0 In Yes
KeyTkn Key Token Alpha 8 In Yes
LogCmt Audit Log Comment Alpha 50 In No
CipherText Encrypted Text Alpha 32624 Out
CipherTextLen Encrypted Text Length 1 Packed 5,0 Out
MsgId Message Id Alpha 7 Out
MsgText Message Text Alpha 80 Out
Errors Errors occurred (Y=Yes) Alpha 1 Out
Parameter Notes:
1 With TDES block mode, the returned Cipher Text length will be a minimum of 8 bytes long. This
returned Cipher text length will be divisible by 8. For instance:
Plain Text Length Cipher Text Length
5 bytes 8 bytes
8 bytes 8 bytes
9 bytes 16 bytes
16 bytes 16 bytes
Example in Fixed format RPG:
C* Encrypt value in variable PLAINTEXT
C CALL 'CRRP606'
C PARM '123456789' PLAINTEXT 32624
C PARM 9 PLAINLEN 5 0
C PARM KEYTKN 8
C PARM 'log comment' LOGCMT 50
C PARM CIPHERTEXT 32624
C PARM CIPHERLEN 5 0
C PARM MSGID 7
C PARM MSGTEXT 80
C PARM ERRORS 1
C* Success-> The encrypted value is contained in variable CIPHERTEXT
C IF ERRORS <> ‘Y’
C … Success logic …
C ELSE
C* Errors-> Display MSGID and MSGTEXT
C … Error logic …
C ENDIF
Crypto Complete
Version 3.50 Linoma Software Page 93
CRRP607 – Decrypt text with TDES using Key Token (ECB block mode)
The CRRP607 program will decrypt text using the TDES (Triple DES) algorithm and ECB block mode. This program requires a Key Token, which can be acquired through the CRRP600 program. Parameters for CRRP607 program:
Name Description Type Length In/Out Required
CipherText Encrypted Text Alpha 32624 In Yes
CipherTextLen Encrypted Text Length Packed 5,0 In Yes
KeyTkn Key Token Alpha 8 In Yes
LogCmt Audit Log Comment Alpha 50 In No
PlainText Plain Text Alpha 32624 Out
PlainTextLen Plain Text Length Packed 5,0 Out
MsgId Message Id Alpha 7 Out
MsgText Message Text Alpha 80 Out
Errors Errors occurred (Y=Yes) Alpha 1 Out
Example in Fixed format RPG:
C* Decrypt value in variable CIPHERTEXT
C CALL 'CRRP607'
C PARM CIPHERTEXT 32624
C PARM CIPHERLEN 5 0
C PARM KEYTKN 8
C PARM 'log comment' LOGCMT 50
C PARM PLAINTEXT 32624
C PARM PLAINLEN 5 0
C PARM MSGID 7
C PARM MSGTEXT 80
C PARM ERRORS 1
C* Success-> The decrypted value is contained in variable PLAINTEXT
C IF ERRORS <> ‘Y’
C … Success logic …
C ELSE
C* Errors-> Display MSGID and MSGTEXT
C … Error logic …
C ENDIF
Crypto Complete
Version 3.50 Linoma Software Page 94
CRRP608 – Encrypt text with TDES using Key Label (ECB block mode)
The CRRP608 program will encrypt text using the TDES (Triple DES) algorithm and ECB block mode. This program requires a Key Label. Parameters for CRRP608 program:
Name Description Type Length In/Out Required
PlainText Plain Text Alpha 32624 In Yes
PlainTextLen Plain Text Length Packed 5,0 In Yes
KeyStrNam Key Store Name 1 Alpha 10 In No
KeyStrLib Key Store Library 2 Alpha 10 In No
KeyLabel Key Label Alpha 30 In Yes
LogCmt Audit Log Comment Alpha 50 In No
CipherText Encrypted Text Alpha 32624 Out
CipherTextLen Encrypted Text Length 3 Packed 5,0 Out
MsgId Message Id Alpha 7 Out
MsgText Message Text Alpha 80 Out
Errors Errors occurred (Y=Yes) Alpha 1 Out
Parameter Notes:
1 Specify the special value of *DEFAULT for the Key Store Name in order to use the default key store
name indicated at the Key Policy level.
2 Specify *LIBL for the Key Store Library to locate the Key Store in the library list.
3 With TDES block mode, the returned Cipher Text length will be a minimum of 8 bytes long. This
returned Cipher text length will be divisible by 8. For instance:
Plain Text Length Cipher Text Length
5 bytes 8 bytes
8 bytes 8 bytes
9 bytes 16 bytes
16 bytes 16 bytes
(see source example on next page)
Crypto Complete
Version 3.50 Linoma Software Page 95
CRRP608 example in Fixed format RPG:
C* Encrypt value in variable PLAINTEXT using key label CARD_KEY
C CALL 'CRRP608'
C PARM '123456789' PLAINTEXT 32624
C PARM 9 PLAINLEN 5 0
C PARM 'OE_KEYS' KEYSTRNAM 10
C PARM '*LIBL' KEYSTRLIB 10
C PARM 'CARD_KEY’ KEYLABEL 30
C PARM 'log comment' LOGCMT 50
C PARM CIPHERTEXT 32624
C PARM CIPHERLEN 5 0
C PARM MSGID 7
C PARM MSGTEXT 80
C PARM ERRORS 1
C* Success-> The encrypted value is contained in variable CIPHERTEXT
C IF ERRORS <> ‘Y’
C … Success logic …
C ELSE
C* Errors-> Display MSGID and MSGTEXT
C … Error logic …
C ENDIF
Crypto Complete
Version 3.50 Linoma Software Page 96
CRRP609 – Decrypt text with TDES using Key Label (ECB block mode)
The CRRP609 program will decrypt text using the TDES (Triple DES) algorithm and ECB block mode. This program requires a Key Label. Parameters for CRRP609 program:
Name Description Type Length In/Out Required
CipherText Encrypted Text Alpha 32624 In Yes
CipherTextLen Encrypted Text Length Packed 5,0 In Yes
KeyStrNam Key Store Name 1 Alpha 10 In No
KeyStrLib Key Store Library 2 Alpha 10 In No
KeyLabel Key Store Label Alpha 30 In Yes
LogCmt Audit Log Comment Alpha 50 In No
PlainText Plain Text Alpha 32624 Out
PlainTextLen Plain Text Length Packed 5,0 Out
MsgId Message Id Alpha 7 Out
MsgText Message Text Alpha 80 Out
Errors Errors occurred (Y=Yes) Alpha 1 Out
Parameter Notes:
1 Specify the special value of *DEFAULT for the Key Store Name in order to use the default key store
name indicated at the Key Policy level.
2 Specify *LIBL for the Key Store Library to locate the Key Store in the library list.
Example in Fixed format RPG:
C* Decrypt value in variable CIPHERTEXT using key label CARD_KEY
C CALL 'CRRP609'
C PARM CIPHERTEXT 32624
C PARM CIPHERLEN 5 0
C PARM 'OE_KEYS' KEYSTRNAM 10
C PARM '*LIBL' KEYSTRLIB 10
C PARM 'CARD_KEY’ KEYLABEL 30
C PARM 'log comment' LOGCMT 50
C PARM PLAINTEXT 32624
C PARM PLAINLEN 5 0
C PARM MSGID 7
C PARM MSGTEXT 80
C PARM ERRORS 1
C* Success-> The decrypted value is contained in variable PLAINTEXT
C IF ERRORS <> ‘Y’
C … Success logic …
C ELSE
C* Errors-> Display MSGID and MSGTEXT
C … Error logic …
C ENDIF
Crypto Complete
Version 3.50 Linoma Software Page 97
CRRP633 – Encrypt text with Advanced options using Key Token
The CRRP633 program will encrypt text using advanced options. This program requires a Key Token, which can be acquired through the CRRP600 program. Parameters for CRRP633 program:
Name Description Type Length In/Out Required
PlainText Plain Text Alpha 32624 In Yes
PlainTextLen Plain Text Length Packed 5,0 In Yes
KeyTkn Key Token Alpha 8 In Yes
LogCmt Audit Log Comment Alpha 50 In No
Algorithm Algorithm 1 Alpha 10 In Yes
Mode Mode of Algorithm 2 Alpha 1 In No
BlockLen Block Length 3 Packed 5,0 In No
PadOption Pad Option 4 Alpha 1 In No
PadChar Pad Character Alpha 1 In No
OutputType Output Type 5 Alpha 7 In No
OutputFmt Output Format 6 Alpha 7 In No
InitVector Initialization Vector (Salt) 7 Alpha 32 In/Out No
CipherText Encrypted Text Alpha 32624 Out
CipherTextLen Encrypted Text Length Packed 5,0 Out
MsgId Message Id Alpha 7 Out
MsgText Message Text Alpha 80 Out
Errors Errors occurred (Y=Yes) Alpha 1 Out
Parameter Notes:
1 Algorithms supported are *TDES (for Triple DES), *AES128, *AES192 and *AES256
2 Modes supported are ‘0’ for ECB, ‘1’ for CBC and ‘6’ for CUSP
3 Block length:
For *AES128, *AES192 and *AES256 algorithms: either specify a 0 to automatically calculate the block length or specify a block length of 16, 24 or 32.
For *TDES algorithm: specify a 0 to automatically calculate the block length or specify a block length of 8.
4 Valid values for the PadOption are:
‘0’ or blanks = No Padding ‘1’ = Pad using pad character (only valid with the *TDES algorithm) ‘2’ = Pad using pad number
Specifying a PadOption will pad the data in the PlainText out to the next block length multiple. For example, the block length would be 8 for *TDES algorithm. Therefore, a value’s length of 20 is padded to 24, 32 is padded to 40, and so forth. The last byte of data will contain a 1-byte binary counter containing the number of pad characters used (a value from 1 to 8). If PadOption is a ‘1’, the PadChar value is used for the rest of the pad characters. If PadOption is ‘2’, the binary counter is used for the rest of the pad characters.
5 OutputType valid values are *EBCDIC and *ASCII. If none is specified, then the default value of
*EBCDIC will be used. 6 OutputFmt valid values are *CHAR, *HEX and *BASE64. If none is specified, then the default value
of *CHAR will be used.
Crypto Complete
Version 3.50 Linoma Software Page 98
7 Initialization vector (IV): Specify an IV value to manipulate the encryption operation. In other words,
the same Plain Text which is encrypted with different IVs will produce different Cipher text values. For *AES algorithms, the IV length should not exceed the block length. For *TDES, the IV length should not exceed 8. The IV need not be secret, but it should be unique. Upon completion of the operation, an output chaining value will be returned in the IV field. This value can be used as the IV for the next operation when encrypting or decrypting text in multiple blocks. Refer to ANSI X9.52 for an explanation of its use. Allowed for algorithm modes of ‘1’ (CBC) and ‘6’ (CUSP).
Example in Fixed format RPG:
C* Encrypt value in variable PLAINTEXT
C CALL 'CRRP633'
C PARM '123456789' PLAINTEXT 32624
C PARM 9 PLAINLEN 5 0
C PARM KEYTKN 8
C PARM 'log comment' LOGCMT 50
C PARM '*AES256' ALGORITHM 10
C PARM '0' MODE 1
C PARM 16 BLOCKLEN 5 0
C PARM PADOPTION 1
C PARM PADCHAR 1
C PARM ‘*EBCDIC’ OUTPUTTYPE 7
C PARM ‘*CHAR’ OUTPUTFMT 7
C PARM INTVECTOR 32
C PARM CIPHERTEXT 32624
C PARM CIPHERLEN 5 0
C PARM MSGID 7
C PARM MSGTEXT 80
C PARM ERRORS 1
C* Success-> The encrypted value is contained in variable CIPHERTEXT
C IF ERRORS <> ‘Y’
C … Success logic …
C ELSE
C* Errors-> Display MSGID and MSGTEXT
C … Error logic …
C ENDIF
Crypto Complete
Version 3.50 Linoma Software Page 99
Additional Notes for CRRP633:
When using *AES128, *AES192 and *AES256 algorithms with ECB or CBC modes, the returned Cipher Text length will be a minimum of 16 bytes long. This returned Cipher text length will be divisible by 16 or 24. For instance:
Plain Text Length Cipher Text Length
10 bytes 16 bytes
16 bytes 16 bytes
17 bytes 24 bytes
24 bytes 24 bytes
32 bytes 32 bytes
When using *AES128, *AES192 and *AES256 algorithms with CUSP mode, the returned Cipher Text length will be the same as the Plain Text length.
For *TDES algorithm, the returned Cipher Text length will be a minimum of 8 bytes long. This returned Cipher text length will be divisible by 8. For instance:
Plain Text Length Cipher Text Length
5 bytes 8 bytes
8 bytes 8 bytes
9 bytes 16 bytes
16 bytes 16 bytes
Crypto Complete
Version 3.50 Linoma Software Page 100
CRRP634 – Decrypt text with Advanced options using Key Token
The CRRP634 program will decrypt text using advanced options. This program requires a Key Token, which can be acquired through the CRRP600 program. Parameters for CRRP634 program:
Name Description Type Length In/Out Required
CipherText Encrypted Text Alpha 32624 In Yes
CipherTextLen Encrypted Text Length Packed 5,0 In Yes
InputType Input Type 1 Alpha 7 In No
InputFmt Input Format 2 Alpha 7 In No
KeyTkn Key Token Alpha 8 In Yes
LogCmt Audit Log Comment Alpha 50 In No
Algorithm Algorithm 3 Alpha 10 In Yes
Mode Mode of Algorithm 4 Alpha 1 In No
BlockLen Block Length 5 Packed 5,0 In No
PadOption Pad Option 6 Alpha 1 In No
PadChar Pad Character Alpha 1 In No
InitVector Initialization Vector (Salt) 7 Alpha 32 In/Out No
PlainText Plain Text Alpha 32624 Out
PlainTextLen Plain Text Length Packed 5,0 Out
MsgId Message Id Alpha 7 Out
MsgText Message Text Alpha 80 Out
Errors Errors occurred (Y=Yes) Alpha 1 Out
Parameter Notes:
1 InputType valid values are *EBCDIC and *ASCII. If none is specified, then the default value of
*EBCDIC will be used.
2 InputFmt valid values are *CHAR, *HEX and *BASE64. If none is specified, then the default value of
*CHAR will be used.
3 Algorithms supported are *TDES (for Triple DES), *AES128, *AES192 and *AES256
4 Modes supported are ‘0’ for ECB, ‘1’ for CBC and ‘6’ for CUSP
5 Block length:
For *AES128, *AES192 and *AES256 algorithms: either specify a 0 to automatically calculate the block length or specify a block length of 16, 24 or 32.
For *TDES algorithm: specify a 0 to automatically calculate the block length or specify a block length of 8.
Crypto Complete
Version 3.50 Linoma Software Page 101
6 Valid values for the PadOption are:
‘0’ or blanks = Value is not padded ‘1’ = Value is padded with a pad character (only valid with the *TDES algorithm) ‘2’ = Value is padded with a pad number
Specifying a PadOption will strip the pad bytes off the end of the value before returning it in the PlainText.
7 Initialization vector (IV): Specify an IV value to manipulate the decryption operation. In other words,
the same Cipher which is decrypted with different IVs will produce different Plain text values. For *AES algorithms, the IV length should not exceed the block length. For *TDES, the IV length should not exceed 8. The IV need not be secret, but it should be unique. Upon completion of the operation, an output chaining value will be returned in the IV field. This value can be used as the IV for the next operation when encrypting or decrypting text in multiple blocks. Refer to ANSI X9.52 for an explanation of its use. Allowed for algorithm modes of ‘1’ (CBC) and ‘6’ (CUSP).
Example in Fixed format RPG:
C* Decrypt value in variable CIPHERTEXT
C CALL 'CRRP634'
C PARM CIPHERTEXT 32624
C PARM CIPHERLEN 5 0
C PARM ‘*EBCDIC’ INPUTTYPE 7
C PARM ‘*CHAR’ INPUTFMT 7
C PARM KEYTKN 8
C PARM 'log comment' LOGCMT 50
C PARM '*AES256' ALGORITHM 10
C PARM '0' MODE 1
C PARM 16 BLOCKLEN 5 0
C PARM PADOPTION 1
C PARM PADCHAR 1
C PARM INTVECTOR 32
C PARM PLAINTEXT 32624
C PARM PLAINLEN 5 0
C PARM MSGID 7
C PARM MSGTEXT 80
C PARM ERRORS 1
C* Success-> The decrypted value is contained in variable PLAINTEXT
C IF ERRORS <> ‘Y’
C … Success logic …
C ELSE
C* Errors-> Display MSGID and MSGTEXT
C … Error logic …
C ENDIF
Crypto Complete
Version 3.50 Linoma Software Page 102
CRRP635 – Encrypt text with Advanced options using Key Label
The CRRP635 program will encrypt text using advanced options. This program requires a Key Label. Parameters for CRRP635 program:
Name Description Type Length In/Out Required
PlainText Plain Text Alpha 32624 In Yes
PlainTextLen Plain Text Length Packed 5,0 In Yes
KeyStrNam Key Store Name 1 Alpha 10 In No
KeyStrLib Key Store Library 2 Alpha 10 In No
KeyLabel Key Store Label Alpha 30 In Yes
LogCmt Audit Log Comment Alpha 50 In No
Algorithm Algorithm 3 Alpha 10 In Yes
Mode Mode of Algorithm 4 Alpha 1 In No
BlockLen Block Length 5 Packed 5,0 In No
PadOption Pad Option 6 Alpha 1 In No
PadChar Pad Character Alpha 1 In No
OutputType Output Type 7 Alpha 7 In No
OutputFmt Output Format 8 Alpha 7 In No
InitVector Initialization Vector (Salt) 9 Alpha 32 In/Out No
CipherText Encrypted Text Alpha 32624 Out
CipherTextLen Encrypted Text Length Packed 5,0 Out
MsgId Message Id Alpha 7 Out
MsgText Message Text Alpha 80 Out
Errors Errors occurred (Y=Yes) Alpha 1 Out
Parameter Notes:
1 Specify the special value of *DEFAULT for the Key Store Name in order to use the default key store
name indicated at the Key Policy level.
2 Specify *LIBL for the Key Store Library to locate the Key Store in the library list.
3 Algorithms supported are *TDES (for Triple DES), *AES128, *AES192 and *AES256
4 Modes supported are ‘0’ for ECB, ‘1’ for CBC and ‘6’ for CUSP
5 Block length:
For *AES128, *AES192 and *AES256 algorithms: either specify a 0 to automatically calculate the block length or specify a block length of 16, 24 or 32.
For *TDES algorithm: specify a 0 to automatically calculate the block length or specify a block length of 8.
6 Valid values for the PadOption are:
‘0’ or blanks = No Padding ‘1’ = Pad using pad character (only valid with the *TDES algorithm) ‘2’ = Pad using pad number
Specifying a PadOption will pad the data in the PlainText out to the next block length multiple. For example, the block length would be 8 for *TDES algorithm. Therefore, a value’s length of 20 is padded to 24, 32 is padded to 40, and so forth. The last byte of data will contain a 1-byte binary counter containing the number of pad characters used (a value from 1 to 8). If PadOption is a ‘1’, the PadChar value is used for the rest of the pad characters. If PadOption is ‘2’, the binary counter is used for the rest of the pad characters.
Crypto Complete
Version 3.50 Linoma Software Page 103
7 OutputType valid values are *EBCDIC and *ASCII. If none is specified, then the default value of
*EBCDIC will be used. 8 OutputFmt valid values are *CHAR, *HEX and *BASE64. If none is specified, then the default value
of *CHAR will be used. 9 Initialization vector (IV): Specify an IV value to manipulate the encryption operation. In other words,
the same Plain Text which is encrypted with different IVs will produce different Cipher text values. For *AES algorithms, the IV length should not exceed the block length. For *TDES, the IV length should not exceed 8. The IV need not be secret, but it should be unique. Upon completion of the operation, an output chaining value will be returned in the IV field. This value can be used as the IV for the next operation when encrypting or decrypting text in multiple blocks. Refer to ANSI X9.52 for an explanation of its use. Allowed for algorithm modes of ‘1’ (CBC) and ‘6’ (CUSP).
Example in Fixed format RPG:
C* Encrypt value in variable PLAINTEXT using key label CARD_KEY
C CALL 'CRRP635'
C PARM '123456789' PLAINTEXT 32624
C PARM 9 PLAINLEN 5 0
C PARM 'OE_KEYS' KEYSTRNAM 10
C PARM '*LIBL' KEYSTRLIB 10
C PARM 'CARD_KEY’ KEYLABEL 30
C PARM 'log comment' LOGCMT 50
C PARM '*AES256' ALGORITHM 10
C PARM '0' MODE 1
C PARM 16 BLOCKLEN 5 0
C PARM PADOPTION 1
C PARM PADCHAR 1
C PARM ‘*EBCDIC’ OUTPUTTYPE 7
C PARM ‘*CHAR’ OUTPUTFMT 7
C PARM INTVECTOR 32
C PARM CIPHERTEXT 32624
C PARM CIPHERLEN 5 0
C PARM MSGID 7
C PARM MSGTEXT 80
C PARM ERRORS 1
C* Success-> The encrypted value is contained in variable CIPHERTEXT
C IF ERRORS <> ‘Y’
C … Success logic …
C ELSE
C* Errors-> Display MSGID and MSGTEXT
C … Error logic …
C ENDIF
Crypto Complete
Version 3.50 Linoma Software Page 104
Additional Notes for CRRP635:
When using *AES128, *AES192 and *AES256 algorithms with ECB or CBC modes, the returned Cipher Text length will be a minimum of 16 bytes long. This returned Cipher text length will be divisible by 16 or 24. For instance:
Plain Text Length Cipher Text Length
10 bytes 16 bytes
16 bytes 16 bytes
17 bytes 24 bytes
24 bytes 24 bytes
32 bytes 32 bytes
When using *AES128, *AES192 and *AES256 algorithms with CUSP mode, the returned Cipher Text length will be the same as the Plain Text length.
For *TDES algorithm, the returned Cipher Text length will be a minimum of 8 bytes long. This returned Cipher text length will be divisible by 8. For instance:
Plain Text Length Cipher Text Length
5 bytes 8 bytes
8 bytes 8 bytes
9 bytes 16 bytes
16 bytes 16 bytes
Crypto Complete
Version 3.50 Linoma Software Page 105
CRRP636 – Decrypt text with Advanced options using Key Label
The CRRP636 program will decrypt text using advanced options. This program requires a Key Label. Parameters for CRRP636 program:
Name Description Type Length In/Out Required
CipherText Encrypted Text Alpha 32624 In Yes
CipherTextLen Encrypted Text Length Packed 5,0 In Yes
InputType Input Type 1 Alpha 7 In No
InputFmt Input Format 2 Alpha 7 In No
KeyStrNam Key Store Name 3 Alpha 10 In No
KeyStrLib Key Store Library 4 Alpha 10 In No
KeyLabel Key Store Label Alpha 30 In Yes
LogCmt Audit Log Comment Alpha 50 In No
Algorithm Algorithm 5 Alpha 10 In Yes
Mode Mode of Algorithm 6 Alpha 1 In No
BlockLen Block Length 7 Packed 5,0 In No
PadOption Pad Option 8 Alpha 1 In No
PadChar Pad Character Alpha 1 In No
InitVector Initialization Vector (Salt) 9 Alpha 32 In/Out No
PlainText Plain Text Alpha 32624 Out
PlainTextLen Plain Text Length Packed 5,0 Out
MsgId Message Id Alpha 7 Out
MsgText Message Text Alpha 80 Out
Errors Errors occurred (Y=Yes) Alpha 1 Out
Parameter Notes:
1 InputType valid values are *EBCDIC and *ASCII. If none is specified, then the default value of
*EBCDIC will be used.
2 InputFmt valid values are *CHAR, *HEX and *BASE64. If none is specified, then the default value of
*CHAR will be used.
3 Specify the special value of *DEFAULT for the Key Store Name in order to use the default key store
name indicated at the Key Policy level.
4 Specify *LIBL for the Key Store Library to locate the Key Store in the library list.
5 Algorithms supported are *TDES (for Triple DES), *AES128, *AES192 and *AES256
6 Modes supported are ‘0’ for ECB, ‘1’ for CBC and ‘6’ for CUSP
7 Block length:
o For *AES128, *AES192 and *AES256 algorithms: either specify a 0 to automatically calculate the block length or specify a block length of 16, 24 or 32.
o For *TDES algorithm: specify a 0 to automatically calculate the block length or specify a block length of 8.
Crypto Complete
Version 3.50 Linoma Software Page 106
8 Valid values for the PadOption are:
o ‘0’ or blanks – Value is not padded
o ‘1’ = Value is padded with a pad character (only valid for TDES algorithm)
o ‘2’ = Value is padded with a pad number
Specifying a PadOption will strip the pad bytes off the end of the value before returning it in the PlainText.
9 Initialization vector (IV): Specify an IV value to manipulate the decryption operation. In other words,
the same Cipher which is decrypted with different IVs will produce different Plain text values. For *AES algorithms, the IV length should not exceed the block length. For *TDES, the IV length should not exceed 8. The IV need not be secret, but it should be unique. Upon completion of the operation, an output chaining value will be returned in the IV field. This value can be used as the IV for the next operation when encrypting or decrypting text in multiple blocks. Refer to ANSI X9.52 for an explanation of its use. Allowed for algorithm modes of ‘1’ (CBC) and ‘6’ (CUSP).
Example in Fixed format RPG:
C* Decrypt value in variable CIPHERTEXT using key label CARD_KEY
C CALL 'CRRP636'
C PARM CIPHERTEXT 32624
C PARM CIPHERLEN 5 0
C PARM ‘*EBCDIC’ INPUTTYPE 7
C PARM ‘*CHAR’ INPUTFMT 7
C PARM 'OE_KEYS' KEYSTRNAM 10
C PARM '*LIBL' KEYSTRLIB 10
C PARM 'CARD_KEY’ KEYLABEL 30
C PARM 'log comment' LOGCMT 50
C PARM '*AES256' ALGORITHM 10
C PARM '0' MODE 1
C PARM 16 BLOCKLEN 5 0
C PARM PADOPTION 1
C PARM PADCHAR 1
C PARM INTVECTOR 32
C PARM PLAINTEXT 32624
C PARM PLAINLEN 5 0
C PARM MSGID 7
C PARM MSGTEXT 80
C PARM ERRORS 1
C* Success-> The decrypted value is contained in variable PLAINTEXT
C IF ERRORS <> ‘Y’
C … Success logic …
C ELSE
C* Errors-> Display MSGID and MSGTEXT
C … Error logic …
C ENDIF
Crypto Complete
Version 3.50 Linoma Software Page 107
CRRP614 – Generate SHA1 Hash
The CRRP614 program will generate an encrypted hash value using the SHA1 (Secure Hash Algorithm) standard. SHA1 is designed as a one-way encryption algorithm. In other words, the hash value is not intended for decryption. Parameters for CRRP614 program:
Name Description Type Length In/Out Required
InputValue Input Value Alpha 1000 In Yes
InputLen Input Length Packed 5,0 In Yes
HashValue Hash value Alpha 20 Out
MsgId Message Id Alpha 7 Out
MsgText Message Text Alpha 80 Out
Errors Errors occurred (Y=Yes) Alpha 1 Out
Example in Fixed format RPG:
C* Generate hash from variable AppPassword, which is 20 in length
C CALL 'CRRP614'
C PARM AppPassword INPUTVALUE 1000
C PARM 20 INPUTLEN 5 0
C PARM HASHVALUE 20
C PARM MSGID 7
C PARM MSGTEXT 80
C PARM ERRORS 1
C* Success-> The hash value is contained in variable HASHVALUE
C IF ERRORS <> ‘Y’
C … Success logic …
C ELSE
C* Errors-> Display MSGID and MSGTEXT
C … Error logic …
C ENDIF
Notes for CRRP614:
A hash is a good technique for protecting and storing passwords used in an application. For instance, an application setup screen could prompt the user to establish a password they wish to use in that application. You could then generate a hash from that password and store this hash value in a database. When a user attempts to signon to an application with a password, you can hash the password entered and compare it to the hash value stored in the database. If the hash values do not match, then you know the password is not valid.
Crypto Complete
Version 3.50 Linoma Software Page 108
CRRP632 – Verify CRVL001
The CRRP632 program API allows you to verify that the CRVL001 object is valid for your installation. This should generally only need to be executed after a system restore.
The CRVL001 object contains your organization’s key policy settings, key officers and master keys.
If CRRP632 returns a failure message, it is most likely because the CRVL001 object was copied from another machine (with a different serial number).
Parameters for CRRP632 program:
Name Description Type Length In/Out Required
MsgId Message Id Alpha 7 Out
MsgText Message Text Alpha 80 Out
Errors Errors occurred (Y=Yes) Alpha 1 Out
Example in Fixed format RPG:
C* Verify CRVL001
C CALL 'CRRP632'
C PARM MSGID 7
C PARM MSGTEXT 80
C PARM ERRORS 1
C* Success-> The CRVL001 object is valid
C IF ERRORS <> ‘Y’
C … Success logic …
C ELSE
C* Errors-> The CRVL001 object is not valid
C … Error logic …
C ENDIF
Notes for CRVL001 object:
You should NOT copy the CRVL001 *VLDL object between machines with different serial numbers since the settings in CRVL001 are encrypted with the Product Encryption Key (PEK), which is unique per IBM i serial number.
Crypto Complete
Version 3.50 Linoma Software Page 109
CRRP641 – Close External File
The CRRP641 program API will close the external file which was last opened for storing or retrieving encrypted values. This is useful if you want to close the file for commitment control or if you need to perform maintenance on the file.
Parameters for CRRP641 program: *none
Example in Fixed format RPG:
C* Close last external file that was opened
C CALL 'CRRP641'
Crypto Complete
Version 3.50 Linoma Software Page 110
CRRP643 – Generate Hash Value (MD5, SHA-1, SHA-256, SHA-384, SHA-512)
The CRRP643 program will generate an encrypted hash value using either the MD5, SHA-1, SHA-256, SHA-384 or SHA-512 standard. Hashing is designed as a one-way encryption algorithm. In other words, the hash value is not intended for decryption. Parameters for CRRP614 program:
Name Description Type Length In/Out Required
InputValue Input Value Alpha 32768 In Yes
InputLen Input Length Packed 5,0 In Yes
HashType Hash Type 1 Alpha 7 In Yes
OutputTyp Output Type 2 Alpha 7 In Yes
OutputFmt Output Format 3 Alpha 7 In Yes
HashValue Hash value Alpha 256 Out
MsgId Message Id Alpha 7 Out
MsgText Message Text Alpha 80 Out
Errors Errors occurred (Y=Yes) Alpha 1 Out
Example in Fixed format RPG:
C* Generate hash from variable AppPassword, which is 256 in length
C CALL 'CRRP643'
C PARM AppPassword INPUTVALUE 32768
C PARM 20 INPUTLEN 5 0
C PARM ‘SHA-256’ HASHTYPE 7
C PARM ‘*EBCDIC’ OUTPUTTYP 7
C PARM ‘*HEX’ OUTPUTFMT 7
C PARM HASHVALUE 256
C PARM MSGID 7
C PARM MSGTEXT 80
C PARM ERRORS 1
C* Success-> The hash value is contained in variable HASHVALUE
C IF ERRORS <> ‘Y’
C … Success logic …
C ELSE
C* Errors-> Display MSGID and MSGTEXT
C … Error logic …
C ENDIF
Notes for CRRP643:
A hash is a good technique for protecting and storing passwords used in an application. For instance,
an application setup screen could prompt the user to establish a password they wish to use in that application. You could then generate a hash from that password and store this hash value in a database. When a user attempts to signon to an application with a password, you can hash the password entered and compare it to the hash value stored in the database. If the hash values do not match, then you know the password is not valid.
Crypto Complete
Version 3.50 Linoma Software Page 111
Parameter Notes:
1 Valid hash types are MD5, SHA-1, SHA-256, SHA-384 and SHA-512.
2 OutputType valid values are *EBCDIC and *ASCII. If none is specified, then the default value of
*EBCDIC will be used. 3 OutputFmt valid values are *CHAR, *HEX and *BASE64. If none is specified, then the default value
of *CHAR will be used.
Crypto Complete
Version 3.50 Linoma Software Page 112
SQL Function APIs for Encryption/Decryption Crypto Complete includes SQL function APIs which can be called for encrypting and decrypting text and field values from within SQL statements. Listed below is a summary of the SQL function APIs provided. SQL Function APIs if using Field Encryption Registry:
Name Description
F_EncFld Encrypt Field Value
F_DecFld Decrypt Field Value (Full value)
F_DecFldMask Decrypt Field Value (Masked value)
F_DecFldAuth Decrypt Field Value (Authorized value)
F_InsEncFld Encrypt and insert field value into external file - Decimal
F_InsEncFldChr Encrypt and insert field value into external file - Character
F_UpdEncFld Encrypt and update field value in external file - Decimal
F_UpdEncFldChr Encrypt and update field value in external file - Character
F_DltEncFld Delete encrypted field value from external file - Decimal
F_DltEncFldChr Delete encrypted field value from external file - Character
F_GetEncFld Get encrypted field value from external file - Decimal (Full value)
F_GetEncFldMask Get encrypted field value from external file - Decimal (Masked value)
F_GetEncFldAuth Get encrypted field value from external file - Decimal (Authorized value)
F_GetEncFldChr Get encrypted field value from external file - Character (Full value)
F_GetEncFldMaskChr Get encrypted field value from external file - Character (Masked value)
F_GetEncFldAuthChr Get encrypted field value from external file - Character (Authorized value)
Other SQL Function APIs:
Name Description
F_EncAES2 Encrypt text with AES256 (ECB block mode)
F_DecAES2 Decrypt text with AES256 (ECB block mode)
F_EncAdv Encrypt text with Advanced options
F_DecAdv Decrypt text with Advanced options
Crypto Complete
Version 3.50 Linoma Software Page 113
F_EncFld – Encrypt Field Value
The SQL function F_EncFld will encrypt a value using the settings specified in the Field Encryption Registry. This function should only be used if all of the following conditions are met:
The field is registered and *ACTIVE in the Encryption Registry
Triggers are not used to automatically encrypt the field values
The encrypted values are not stored in an external file Parameters for F_EncFld function:
Description Type Length
Field identifier Char 30
Plain Text Char 32624
Return value:
Description Type Length
Encrypted Text Char 32624
SQL Example:
/* Encrypt Credit Card number for Customer 12345 */
UPDATE DataLib/Orders
SET CreditCard = F_EncFld(‘CCFIELD’, CreditCard)
WHERE CustId = 12345
Crypto Complete
Version 3.50 Linoma Software Page 114
F_DecFld – Decrypt Field Value (Full value)
The SQL function F_DecFld will decrypt a value using the settings specified in the Field Encryption Registry.
The user will be authorized to the full decrypted value if they have 1) at least *USE authority to the ‘Full’ Authorization List specified for the field and 2) at least *USE authority to the Key Store which holds the Decryption Key. The names of the Authorization List and Key Store can be found for the field identifier in the Encryption Registry.
This function should only be used if all of the following conditions are met:
The field is registered and *ACTIVE in the Encryption Registry
The encrypted values are not stored in an external file Parameters for F_DecFld function:
Description Type Length
Field identifier Char 30
Cipher Text Char 32624
Return value:
Description Type Length
Plain Text Char 32624
SQL Example:
/* Decrypt the value in CreditCard into the derived field of
Decrypted_CreditCard */
SELECT F_DecFld(‘CCFIELD’, CreditCard)as Decrypted_CreditCard
FROM OrderFile WHERE CustId = 12345
Crypto Complete
Version 3.50 Linoma Software Page 115
F_DecFldMask – Decrypt Field Value (Masked value)
The SQL function F_DecFldMask will decrypt a field value and apply a mask, based on the settings specified in the Field Encryption Registry. For instance, if a mask of ‘************9999’ is specified in the Registry for a credit card number, then a sample of a returned credit card number would be ‘************1234’.
The user will be authorized to the masked value if they have 1) at least *USE authority to the ‘Masked’ Authorization List specified for the field and 2) at least *USE authority to the Key Store which holds the Decryption Key. The names of the Authorization List and Key Store can be found for the field identifier in the Encryption Registry.
This function should only be used if all of the following conditions are met:
The field is registered and *ACTIVE in the Encryption Registry
The field has a mask value specified in the Encryption Registry
The encrypted values are not stored in an external file Parameters for F_DecFldMask function:
Description Type Length
Field identifier Char 30
Cipher Text Char 32624
Return value:
Description Type Length
Plain Text (masked) Char 32624
SQL Example:
/* Decrypt the value in CreditCard and return as a masked value in the
derived field of Masked_CreditCard */
SELECT F_DecFldMask(‘CCFIELD’, CreditCard)as Masked_CreditCard
FROM OrderFile WHERE CustId = 12345
Note: If a mask is not specified for the Field in the Registry, then no value will be returned.
Crypto Complete
Version 3.50 Linoma Software Page 116
F_DecFldAuth – Decrypt Field Value (Authorized value)
Based on the user’s authority to the field, the SQL function F_DecFldAuth will return either 1) the fully decrypted value for the field or 2) the masked value for the field or 3) the not-authorized fill value that is specified for the field in the Registry, which may be blanks. The user’s authority to the field is determined by checking the Authority Lists indicated on the field’s AUTLDEC and AUTLMASK settings that are specified in the Field Encryption Registry. If a masked value is returned, the mask will be based on the field’s FLDMASK setting that is specified in the Field Encryption Registry. This function should only be used if all of the following conditions are met:
The field is registered and *ACTIVE in the Encryption Registry
The encrypted values are not stored in an external file Parameters for F_DecFldAuth function:
Description Type Length
Field identifier Char 30
Cipher Text Char 32624
Return value:
Description Type Length
Output Text Char 32624
SQL Example:
/* Process the value in CreditCard. Based on the user’s authorities, return
either the fully decrypted value, the masked value or a fill/blank value.
The returned value will be placed in the derived field of Auth_CreditCard
*/
SELECT F_DecFldAuth(‘CCFIELD’, CreditCard)as Auth_CreditCard
FROM OrderFile WHERE CustId = 12345
Note: The users (or user groups) which should have access to the decrypted (or masked) values will also need at least *USE authority to the Key Store object which holds the Decryption Key.
Crypto Complete
Version 3.50 Linoma Software Page 117
F_InsEncFld – Insert Encrypted Field Value into External File - Decimal
The SQL function F_InsEncFld will encrypt a value and insert it into the external file specified in the Field Encryption Registry. An index number to the encrypted value will be returned as a Decimal type. This function should only be used if all of the following conditions are met:
The field is registered and *ACTIVE in the Encryption Registry
Triggers are not used to automatically encrypt the field values
The encrypted values are stored in an external file Parameters for F_InsEncFld function:
Description Type Length
Field identifier Char 30
Plain value to encrypt Decimal 30,4
Return value:
Description Type Length
Index number of value Decimal 13,0
SQL Example:
/* Encrypt value in CreditCard and insert into external file. CreditCard
will then contain the index number to the encrypted value */
UPDATE DataLib/Orders
SET CreditCard = F_InsEncFld(‘CCFIELD’, CreditCard)
WHERE CustId = 12345
Crypto Complete
Version 3.50 Linoma Software Page 118
F_InsEncFldChr – Insert Encrypted Field Value into External File - Character
The SQL function F_InsEncFldChr will encrypt a value and insert it into the external file specified in the Field Encryption Registry. An index number to the encrypted value will be returned as a Character type. This function should only be used if all of the following conditions are met:
The field is registered and *ACTIVE in the Encryption Registry
Triggers are not used to automatically encrypt the field values
The encrypted values are stored in an external file Parameters for F_InsEncFldChr function:
Description Type Length
Field identifier Char 30
Plain Text Char 32624
Return value:
Description Type Length
Index number of value Char 13
SQL Example:
/* Encrypt value in CreditCard and insert into external file. CreditCard
will then contain the index number to the encrypted value */
UPDATE DataLib/Orders
SET CreditCard = F_InsEncFld(‘CCFIELD’, CreditCard)
WHERE CustId = 12345
Crypto Complete
Version 3.50 Linoma Software Page 119
F_UpdEncFld – Update Encrypted Field Value in External File - Decimal
The SQL function F_UpdEncFld will encrypt a value and update the record in the external file with this encrypted value. The name of the external file is specified in the Field Encryption Registry. The Index number parameter is passed in as a Decimal type. An index number to the encrypted value will be returned as a Decimal type. This function should only be used if all of the following conditions are met:
The field is registered and *ACTIVE in the Encryption Registry
Triggers are not used to automatically encrypt the field values
The encrypted values are stored in an external file Parameters for F_UpdEncFld function:
Description Type Length
Field identifier Char 30
Index number of value Decimal 13,0
Plain Value to encrypt Decimal 30,4
Return value:
Description Type Length
Index number of value Decimal 13,0
The action performed in the F_UpdEncFld function is dependent on the values passed in the Index number and Plain Text:
If the Index Number is 0 and the Plain Value is not 0, then the encrypted value will be inserted into the external file and an Index Number will be returned.
If the Index Number is not 0 and the Plain Value is not 0, then the encrypted value will be updated in the external file and the Index Number will be returned.
If the Index Number is not 0 and the Plain Value is 0, then the encrypted value will be deleted from the external file and the Index Number of 0 will be returned.
SQL Example:
/* Encrypt value in NewCreditCard and update in external file using index
number in CreditCard */
UPDATE DataLib/Orders
SET CreditCard = F_UpdEncFld(‘CCFIELD’, CreditCard, NewCreditCard)
WHERE CustId = 12345
Crypto Complete
Version 3.50 Linoma Software Page 120
F_UpdEncFldChr – Update Encrypted Field Value in External File - Character
The SQL function F_UpdEncFldChr will encrypt a value and update the record in the external file with this encrypted value. The name of the external file is specified in the Field Encryption Registry. The Index number parameter is passed in as a Character type. An index number to the encrypted value will be returned as a Character type. This function should only be used if all of the following conditions are met:
The field is registered and *ACTIVE in the Encryption Registry
Triggers are not used to automatically encrypt the field values
The encrypted values are stored in an external file Parameters for F_UpdEncFldChr function:
Description Type Length
Field identifier Char 30
Index number of value Char 32624
Plain Text Char 32624
Return value:
Description Type Length
Index number of value Char 13
The action performed in the function F_UpdEncFldChr is dependent on the values passed in the Index number and Plain Text:
If the Index Number is blanks or ‘0’, and if the Plain Text is not blanks, then the encrypted value will be inserted into the external file and an Index Number will be returned.
If the Index Number is not blanks and not ‘0’, and if the Plain Text is not blanks, then the encrypted value will be updated in the external file and the Index Number will be returned.
If the Index Number is not blanks and not ‘0’, and if the Plain Text is blanks, then the encrypted value will be deleted from the external file and the Index Number of blanks will be returned.
SQL Example:
/* Encrypt value in NewCreditCard and update in external file using index
number in CreditCard */
UPDATE DataLib/Orders
SET CreditCard = F_UpdEncFldChr(‘CCFIELD’, CreditCard, NewCreditCard)
WHERE CustId = 12345
Crypto Complete
Version 3.50 Linoma Software Page 121
F_DltEncFld – Delete Encrypted Field Value from External File - Decimal
The SQL function F_DltEncFld will delete the encrypted field value from the external file. The name of the external file is specified in the Field Encryption Registry. The Index number parameter is passed in as a Decimal type. An index number of the deleted encrypted value will be returned as a Decimal type. This function should only be used if all of the following conditions are met:
The field is registered and *ACTIVE in the Encryption Registry
Triggers are not used to automatically encrypt the field values
The encrypted values are stored in an external file Parameters for F_DltEncFld function:
Description Type Length
Field identifier Char 30
Index number of value Decimal 13,0
Return value:
Description Type Length
Index number of value Decimal 13,0
SQL Example:
/* Delete the encrypted value for the index number specified in CreditCard
*/
UPDATE DataLib/Orders
SET OldIndex = F_DltEncFld(‘CCFIELD’, CreditCard)
WHERE CustId = 12345
Crypto Complete
Version 3.50 Linoma Software Page 122
F_DltEncFldChr – Delete Encrypted Field Value from External File - Character
The SQL function F_DltEncFldChr will delete the encrypted field value from the external file. The name of the external file is specified in the Field Encryption Registry. The Index number parameter is passed in as a Character type. An index number of the deleted encrypted value will be returned as a Character type. This function should only be used if all of the following conditions are met:
The field is registered and *ACTIVE in the Encryption Registry
Triggers are not used to automatically encrypt the field values
The encrypted values are stored in an external file Parameters for F_DltEncFldChr function:
Description Type Length
Field identifier Char 30
Index number of value Char 32624
Return value:
Description Type Length
Index number of value Char 13
SQL Example:
/* Delete the encrypted value for the index number specified in CreditCard
*/
UPDATE DataLib/Orders
SET OldIndex = F_DltEncFldChr(‘CCFIELD’, CreditCard)
WHERE CustId = 12345
Crypto Complete
Version 3.50 Linoma Software Page 123
F_GetEncFld – Get Decrypted Field Value from External File – Decimal (Full value)
The SQL function F_GetEncFld will retrieve an encrypted field value from an external file, which will then be decrypted and returned for use in an SQL statement. The name of the external file is specified in the Field Encryption Registry. The Index number parameter is passed in as a Decimal type.
The user will be authorized to the full decrypted value if they have 1) at least *USE authority to the ‘Full’ Authorization List specified for the field and 2) at least *USE authority to the Key Store which holds the Decryption Key. The names of the Authorization List and Key Store can be found for the field identifier in the Encryption Registry.
This function should only be used if all of the following conditions are met:
The field is registered and *ACTIVE in the Encryption Registry
The encrypted values are stored in an external file Parameters for F_GetEncFld function:
Description Type Length
Field identifier Char 30
Index number of value Decimal 13,0
Return value:
Description Type Length
Plain value (decrypted) Decimal 30,4
SQL Example:
/* Fetch the decrypted Credit Card number for the index number specified in
CreditCard and return as the derived field named Decrypted_CreditCard */
SELECT F_GetEncFld(‘CCFIELD’, CreditCard)as Decrypted_CreditCard
FROM OrderFile WHERE CustId = 12345
Crypto Complete
Version 3.50 Linoma Software Page 124
F_GetEncFldChr – Get Decrypted Field Value from External File – Character (Full value)
The SQL function F_GetEncFld will retrieve an encrypted field value from an external file, which will then be decrypted and returned for use in an SQL statement. The name of the external file is specified in the Field Encryption Registry. The Index number parameter is passed in as a Character type.
The user will be authorized to the full decrypted value if they have 1) at least *USE authority to the ‘Full’ Authorization List specified for the field and 2) at least *USE authority to the Key Store which holds the Decryption Key. The names of the Authorization List and Key Store can be found for the field identifier in the Encryption Registry.
This function should only be used if all of the following conditions are met:
The field is registered and *ACTIVE in the Encryption Registry
The encrypted values are stored in an external file Parameters for F_GetEncFldChr function:
Description Type Length
Field identifier Char 30
Index number of value Char 32624
Return value:
Description Type Length
Plain Text Char 32624
SQL Example:
/* Fetch the decrypted Credit Card number for the index number specified in
CreditCard and return as the derived field named Decrypted_CreditCard */
SELECT F_GetEncFldChr(‘CCFIELD’, CreditCard)as Decrypted_CreditCard
FROM OrderFile WHERE CustId = 12345
Crypto Complete
Version 3.50 Linoma Software Page 125
F_GetEncFldMask – Get Decrypted Field Value from External File – Decimal (Masked value)
The SQL function F_GetEncFldMask will retrieve an encrypted field value from an external file, then decrypt it and apply a mask, based on the settings specified in the Field Encryption Registry. For instance, if a mask of ‘************9999’ is specified in the Registry for a credit card number, then a sample of a returned credit card number would be ‘************1234’.
The user will be authorized to the masked value if they have 1) at least *USE authority to the ‘Masked’ Authorization List specified for the field and 2) at least *USE authority to the Key Store which holds the Decryption Key. The names of the Authorization List and Key Store can be found for the field identifier in the Encryption Registry.
The Index number parameter is passed in as a Decimal type.
This function should only be used if all of the following conditions are met:
The field is registered and *ACTIVE in the Encryption Registry
The field has a mask value specified in the Encryption Registry
The encrypted values are stored in an external file Parameters for F_GetEncFldMask function:
Description Type Length
Field identifier Char 30
Index number of value Decimal 13,0
Return value:
Description Type Length
Plain value (masked) VarChar 32
SQL Example:
/* Fetch the value for the index number specified in the CreditCard field.
Return as a masked value in the derived field of Masked_CreditCard */
SELECT F_GetEncFldMask(‘CCFIELD’, CreditCard)as Masked_CreditCard
FROM OrderFile WHERE CustId = 12345
Note: If a mask is not specified for the Field in the Registry, then no value will be returned.
Crypto Complete
Version 3.50 Linoma Software Page 126
F_GetEncFldMaskChr – Get Decrypted Field Value from External File – Character (Masked value)
The SQL function F_GetEncFldMaskChr will retrieve an encrypted field value from an external file, then decrypt it and apply a mask, based on the settings specified in the Field Encryption Registry. For instance, if a mask of ‘************9999’ is specified in the Registry for a credit card number, then a sample of a returned credit card number would be ‘************1234’.
The user will be authorized to the masked value if they have 1) at least *USE authority to the ‘Masked’ Authorization List specified for the field and 2) at least *USE authority to the Key Store which holds the Decryption Key. The names of the Authorization List and Key Store can be found for the field identifier in the Encryption Registry.
The Index number parameter is passed in as a Character type.
This function should only be used if all of the following conditions are met:
The field is registered and *ACTIVE in the Encryption Registry
The field has a mask value specified in the Encryption Registry
The encrypted values are stored in an external file Parameters for F_GetEncFldMaskChr function:
Description Type Length
Field identifier Char 30
Index number of value Char 32624
Return value:
Description Type Length
Plain value (masked) VarChar 32624
SQL Example:
/* Fetch the value for the index number specified in the CreditCard field.
Return as a masked value in the derived field of Masked_CreditCard */
SELECT F_GetEncFldMaskChr(‘CCFIELD’, CreditCard)as Masked_CreditCard
FROM OrderFile WHERE CustId = 12345
Crypto Complete
Version 3.50 Linoma Software Page 127
F_GetEncFldAuth – Get Decrypted Field Value from External File – Decimal (Auth. Value)
The SQL function F_GetEncFldAuth can be used if the encrypted field values are stored in an external file. Based on the user’s authority to the field, the F_GetEncFldAuth procedure will return either 1) the fully decrypted value for the field or 2) the masked value for the field or 3) the not-authorized fill value that is specified for the field in the Registry, which may be blanks. The user’s authority to the field is determined by checking the Authority Lists indicated on the field’s AUTLDEC and AUTLMASK settings that are specified in the Field Encryption Registry. If a masked value is returned, the mask will be based on the field’s FLDMASK setting that is specified in the Field Encryption Registry. The Index number parameter is passed in as a Decimal type. This function should only be used if all of the following conditions are met:
The field is registered and *ACTIVE in the Encryption Registry
The encrypted values are stored in an external file Parameters for F_GetEncFldAuth function:
Description Type Length
Field identifier Char 30
Index number of value Decimal 13,0
Return value:
Description Type Length
Output value VarChar 32
SQL Example:
/* Fetch the value for the index number specified in the CreditCard field.
Based on the user’s authorities, return either the fully decrypted value,
the masked value or a fill/blank value. The returned value will be placed
in the derived field of Auth_CreditCard */
SELECT F_GetEncFldAuth(‘CCFIELD’, CreditCard)as Auth_CreditCard
FROM OrderFile WHERE CustId = 12345
Note: The users (or user groups) which should have access to the decrypted (or masked) values will also need at least *USE authority to the Key Store object which holds the Decryption Key.
Crypto Complete
Version 3.50 Linoma Software Page 128
F_GetEncFldAuthChr – Get Decrypted Field Value from External File – Character (Auth. value)
The SQL function F_GetEncFldAuthChr can be used if the encrypted field values are stored in an external file. Based on the user’s authority to the field, the F_GetEncFldAuthChr procedure will return either 1) the fully decrypted value for the field or 2) the masked value for the field or 3) the not-authorized fill value that is specified for the field in the Registry, which may be blanks. The user’s authority to the field is determined by checking the Authority Lists indicated on the field’s AUTLDEC and AUTLMASK settings that are specified in the Field Encryption Registry. If a masked value is returned, the mask will be based on the field’s FLDMASK setting that is specified in the Field Encryption Registry. The Index number parameter is passed in as a Character type. This function should only be used if all of the following conditions are met:
The field is registered and *ACTIVE in the Encryption Registry
The encrypted values are stored in an external file Parameters for F_GetEncFldAuthChr function:
Description Type Length
Field identifier Char 30
Index number of value Char 32624
Return value:
Description Type Length
Output value Char 32624
SQL Example:
/* Fetch the value for the index number specified in the CreditCard field.
Based on the user’s authorities, return either the fully decrypted value,
the masked value or a fill/blank value. The returned value will be placed
in the derived field of Auth_CreditCard */
SELECT F_GetEncFldAuthChr(‘CCFIELD’, CreditCard)as Auth_CreditCard
FROM OrderFile WHERE CustId = 12345
Note: The users (or user groups) which should have access to the decrypted (or masked) values will also need at least *USE authority to the Key Store object which holds the Decryption Key.
Crypto Complete
Version 3.50 Linoma Software Page 129
F_EncAES2 – Encrypt text with AES256 (ECB block mode)
The SQL function F_EncAES2 will encrypt text using the AES256 algorithm and ECB block mode. This function requires a Key Label. Parameters for F_EncAES2 function:
Description Type Length
Plain Text (decrypted value) Char 32624
Plain Text Length Integer 10,0
Key Store Name 1 Char 10
Key Store Library 2 Char 10
Key Label Char 30
Return value:
Description Type Length
Cipher Text (encrypted value) Char 32624
Parameter Notes:
1 Specify the special value of *DEFAULT for the Key Store Name in order to use the default key store
name indicated at the Key Policy level.
2 Specify *LIBL for the Key Store Library to locate the Key Store in the library list.
SQL Example:
/* Encrypt a credit card number using the Key Label CREDIT_CARD_KEY in the
Key Store of OE_KEYS */
UPDATE OrderFile
SET CreditCard =
F_EncAES2(CreditCard, 16, ‘OE_KEYS’, ‘*LIBL’, ‘CREDIT_CARD_KEY’)
WHERE CustId = 12345
Crypto Complete
Version 3.50 Linoma Software Page 130
F_DecAES2 – Decrypt text with AES256 (ECB block mode)
The SQL function F_DecAES2 will decrypt text using the AES256 algorithm and ECB block mode. This function requires a Key Label. Parameters for F_DecAES2 function:
Description Type Length
Cipher Text (encrypted value) Char 32624
Cipher Text Length Integer 10,0
Key Store Name 1 Char 10
Key Store Library 2 Char 10
Key Label Char 30
Return value:
Description Type Length
Plain Text (decrypted value) Char 32624
Parameter Notes:
1 Specify the special value of *DEFAULT for the Key Store Name in order to use the default key store
name indicated at the Key Policy level.
2 Specify *LIBL for the Key Store Library to locate the Key Store in the library list.
SQL Example:
/* Decrypt a credit card number using the Key Label CREDIT_CARD_KEY in the
Key Store of OE_KEYS */
SELECT F_DecAES2(CreditCard, 16, ‘OE_KEYS’, ‘*LIBL’, ‘CREDIT_CARD_KEY’)
as Decrypted_CreditCard
FROM OrderFile WHERE CustId = 12345
Crypto Complete
Version 3.50 Linoma Software Page 131
F_EncAdv – Encrypt text with Advanced options
The SQL function F_EncAdv will encrypt text using advanced options. This function requires a Key Label. Parameters for F_EncAdv:
Description Type Length
Plain Text Char 32624
Plain Text Length Integer 10,0
Key Store Name 1 Char 10
Key Store Library 2 Char 10
Key Store Label Char 30
Audit Log Comment Char 50
Algorithm 3 Char 10
Mode of Algorithm 4 Char 1
Block Length 5 Integer 10,0
Pad Option 6 Char 1
Pad Character Char 1
Output Type 7 Char 7
Output Format 8 Char 7
Initialization Vector (Salt) 9 Char 32
Return value:
Description Type Length
Encrypted Text Char 32624
Parameter Notes:
1 Specify the special value of *DEFAULT for the Key Store Name in order to use the default key store
name indicated at the Key Policy level.
2 Specify *LIBL for the Key Store Library to locate the Key Store in the library list.
3 Algorithms supported are *TDES (for Triple DES), *AES128, *AES192 and *AES256
4 Modes supported are ‘0’ for ECB, ‘1’ for CBC and ‘6’ for CUSP
5 Block length:
For *AES128, *AES192 and *AES256 algorithms: either specify a 0 to automatically calculate the block length or specify a block length of 16, 24 or 32.
For *TDES algorithm: specify a 0 to automatically calculate the block length or specify a block length of 8.
6 Valid values for the PadOption are:
‘0’ or blanks = No Padding ‘1’ = Pad using pad character (only valid with the *TDES algorithm) ‘2’ = Pad using pad number
Specifying a PadOption will pad the data in the PlainText out to the next block length multiple. For example, the block length would be 8 for *TDES algorithm. Therefore, a value’s length of 20 is padded to 24, 32 is padded to 40, and so forth. The last byte of data will contain a 1-byte binary counter containing the number of pad characters used (a value from 1 to 8). If PadOption is a ‘1’, the PadChar value is used for the rest of the pad characters. If PadOption is ‘2’, the binary counter is used for the rest of the pad characters.
Crypto Complete
Version 3.50 Linoma Software Page 132
7 Output Type valid values are *EBCDIC and *ASCII. If none is specified, then the default value of
*EBCDIC will be used.
8 Output Format valid values are *CHAR, *HEX and *BASE64. If none is specified, then the default
value of *CHAR will be used.
9 Initialization vector (IV): Specify an IV value to manipulate the encryption operation. In other words,
the same Plain Text which is encrypted with different IVs will produce different Cipher text values. For *AES algorithms, the IV length should not exceed the block length. For *TDES, the IV length should not exceed 8. Refer to ANSI X9.52 for an explanation of its use. Allowed for algorithm modes of ‘1’ (CBC) and ‘6’ (CUSP).
SQL Example:
/* Encrypt a credit card number using the Key Label CREDIT_CARD_KEY in the
Key Store of OE_KEYS */
UPDATE OrderFile
SET CreditCard =
F_EncAdv(CreditCard, 16, ‘OE_KEYS’, ‘*LIBL’, ‘CREDIT_CARD_KEY’,
‘Log Comment’, ‘*AES256’, ‘0’, 16, ‘0’, ‘’,
‘*EBCDIC’, ‘*CHAR’, ‘’)
WHERE CustId = 12345
Crypto Complete
Version 3.50 Linoma Software Page 133
F_DecAdv – Decrypt text with Advanced options
The SQL function F_DecAdv will decrypt text using advanced options. This procedure requires a Key Label. Parameters for F_DecAdv:
Description Type Length
Encrypted Text Char 32624
Encrypted Text Length Integer 10,0
Input Type 1 Char 7
Input Format 2 Char 7
Key Store Name 3 Char 10
Key Store Library 4 Char 10
Key Store Label Char 30
Audit Log Comment Char 50
Algorithm 5 Char 10
Mode of Algorithm 6 Char 1
Block Length 7 Integer 10,0
Pad Option 8 Char 1
Pad Character Char 1
Initialization Vector (Salt) 9 Char 32
Return value:
Description Type Length
Plain Text (decrypted value) Char 32624
Parameter Notes:
1 Input Type valid values are *EBCDIC and *ASCII. If none is specified, then the default value of
*EBCDIC will be used.
2 Input Format valid values are *CHAR, *HEX and *BASE64. If none is specified, then the default
value of *CHAR will be used.
3 Specify the special value of *DEFAULT for the Key Store Name in order to use the default key store
name indicated at the Key Policy level.
4 Specify *LIBL for the Key Store Library to locate the Key Store in the library list.
5 Algorithms supported are *TDES (for Triple DES), *AES128, *AES192 and *AES256
6 Modes supported are ‘0’ for ECB, ‘1’ for CBC and ‘6’ for CUSP
7 Block length:
o For *AES128, *AES192 and *AES256 algorithms: either specify a 0 to automatically calculate the block length or specify a block length of 16, 24 or 32.
o For *TDES algorithm: specify a 0 to automatically calculate the block length or specify a block length of 8.
Crypto Complete
Version 3.50 Linoma Software Page 134
8 Valid values for the PadOption are:
‘0’ or blanks = Value is not padded ‘1’ = Value is padded with a pad character (only valid with the *TDES algorithm) ‘2’ = Value is padded with a pad number
Specifying a PadOption will strip the pad bytes off the end of the value before returning it in the PlainText.
9 Initialization vector (IV): Specify an IV value to manipulate the decryption operation. In other words,
the same Cipher which is decrypted with different IVs will produce different Plain text values. For *AES algorithms, the IV length should not exceed the block length. For *TDES, the IV length should not exceed 8. The IV need not be secret, but it should be unique. Refer to ANSI X9.52 for an explanation of its use. Allowed for algorithm modes of ‘1’ (CBC) and ‘6’ (CUSP).
SQL Example:
/* Decrypt a credit card number using the Key Label CREDIT_CARD_KEY in the
Key Store of OE_KEYS */
SELECT F_DecAdv(CreditCard, 16, ‘*EBCDIC’, ‘*CHAR’, ‘OE_KEYS’, ‘*LIBL’,
‘CREDIT_CARD_KEY’, ‘Log Comment’, ‘*AES256’, ‘0’, 16,
‘0’, ‘’, ‘’)
as Decrypted_CreditCard
FROM OrderFile WHERE CustId = 12345
Crypto Complete
Version 3.50 Linoma Software Page 135
Stored Procedure APIs for Encryption/Decryption Crypto Complete includes Stored Procedure APIs which can be called for encrypting and decrypting text and field values from within SQL CALL statements. Listed below is a summary of the Stored Procedure APIs provided. Stored Procedures APIs if using Field Encryption Registry:
Name Description
P_EncFld Encrypt Field Value
P_DecFld Decrypt Field Value (Full value)
P_DecFldMask Decrypt Field Value (Masked value)
P_DecFldAuth Decrypt Field Value (Authorized value)
P_InsEncFld Encrypt and insert field value into external file
P_UpdEncFld Encrypt and update field value in external file
P_DltEncFld Delete encrypted field value from external file
P_GetEncFld Get encrypted field value from external file (Full value)
P_GetEncFldMask Get encrypted field value from external file (Masked value)
P_GetEncFldAuth Get encrypted field value from external file (Authorized value)
P_GetFldIdx Get Index for a Field Value from External File
Other Stored Procedures:
Name Description
P_EncAES2 Encrypt text with AES256 using Key label (ECB block mode)
P_DecAES2 Decrypt text with AES256 using Key label (ECB block mode)
P_EncAdv Encrypt text with Advanced options
P_DecAdv Decrypt text with Advanced options
Crypto Complete
Version 3.50 Linoma Software Page 136
P_EncFld – Encrypt Field Value
The P_EncFld stored procedure will encrypt a field value using the settings specified in the Field Encryption Registry. This stored procedure should only be used if all of the following conditions are met:
The field is registered and *ACTIVE in the Encryption Registry
Triggers are not used to automatically encrypt the field values
The encrypted values are not stored in an external file Parameters for P_EncFld stored procedure:
Name Description Type Length In/Out Required
FldId Field identifier Char 30 In Yes
PlainText Plain Text Char 32624 In Yes
LogCmt Audit Log Comment Char 50 In No
CipherText Encrypted Text Char 32624 Out
MsgId Message Id Char 7 Out
MsgText Message Text Char 80 Out
Errors Errors occurred (Y=Yes) Char 1 Out
Crypto Complete
Version 3.50 Linoma Software Page 137
P_DecFld – Decrypt Field Value (Full value)
The P_DecFld stored procedure will decrypt a field value using the settings specified in the Field Encryption Registry.
The user will be authorized to the full decrypted value if they have 1) at least *USE authority to the ‘Full’ Authorization List specified for the field and 2) at least *USE authority to the Key Store which holds the Decryption Key. The names of the Authorization List and Key Store can be found for the field identifier in the Encryption Registry.
This stored procedure should only be used if all of the following conditions are met:
The field is registered and *ACTIVE in the Encryption Registry
The encrypted values are not stored in an external file Parameters for P_DecFld stored procedure:
Name Description Type Length In/Out Required
FldId Field identifier Char 30 In Yes
CipherText Encrypted Text Char 32624 In Yes
LogCmt Audit Log Comment Char 50 In No
PlainText Plain Text Char 32624 Out
MsgId Message Id Char 7 Out
MsgText Message Text Char 80 Out
Errors Errors occurred (Y=Yes) Char 1 Out
Crypto Complete
Version 3.50 Linoma Software Page 138
P_DecFldMask – Decrypt Field Value (Masked value)
The P_DecFldMask stored procedure will decrypt a field value and apply a mask, based on the settings specified in the Field Encryption Registry. For instance, if a mask of ‘************9999’ is specified in the Registry for a credit card number, then a sample of a returned credit card number would be ‘************1234’.
The user will be authorized to the masked value if they have 1) at least *USE authority to the ‘Masked’ Authorization List specified for the field and 2) at least *USE authority to the Key Store which holds the Decryption Key. The names of the Authorization List and Key Store can be found for the field identifier in the Encryption Registry.
This stored procedure should only be used if all of the following conditions are met:
The field is registered and *ACTIVE in the Encryption Registry
The field has a mask value specified in the Encryption Registry
The encrypted values are not stored in an external file Parameters for P_DecFldMask stored procedure:
Name Description Type Length In/Out Required
FldId Field identifier Char 30 In Yes
CipherText Encrypted Text Char 32624 In Yes
LogCmt Audit Log Comment Char 50 In No
PlainText Plain Text (masked) Char 32624 Out
MsgId Message Id Char 7 Out
MsgText Message Text Char 80 Out
Errors Errors occurred (Y=Yes) Char 1 Out
Note: If a mask is not specified for the Field in the Registry, then no value will be returned.
Crypto Complete
Version 3.50 Linoma Software Page 139
P_DecFldAuth – Decrypt Field Value (Authorized value)
Based on the user’s authority to the field, the P_DecFldAuth stored procedure will return either 1) the fully decrypted value for the field or 2) the masked value for the field or 3) the not-authorized fill value that is specified for the field in the Registry, which may be blanks. The user’s authority to the field is determined by checking the Authority Lists indicated on the field’s AUTLDEC and AUTLMASK settings that are specified in the Field Encryption Registry. If a masked value is returned, the mask will be based on the field’s FLDMASK setting that is specified in the Field Encryption Registry. This stored procedure should only be used if all of the following conditions are met:
The field is registered and *ACTIVE in the Encryption Registry
The encrypted values are not stored in an external file Parameters for P_DecFldAuth stored procedure:
Name Description Type Length In/Out Required
FldId Field identifier Char 30 In Yes
CipherText Encrypted Text Char 32624 In Yes
LogCmt Audit Log Comment Char 50 In No
OutputText Output Text Char 32624 Out
MsgId Message Id Char 7 Out
MsgText Message Text Char 80 Out
Errors Errors occurred (Y=Yes) Char 1 Out
Note: The users (or user groups) which should have access to the decrypted (or masked) values will also need at least *USE authority to the Key Store object which holds the Decryption Key.
Crypto Complete
Version 3.50 Linoma Software Page 140
P_InsEncFld – Insert Encrypted Field Value into External File
The P_InsEncFld stored procedure will encrypt a field value and insert it into the external file specified in the Field Encryption Registry. This stored procedure should only be used if all of the following conditions are met:
The field is registered and *ACTIVE in the Encryption Registry
Triggers are not used to automatically encrypt the field values
The encrypted values are stored in an external file Parameters for P_InsEncFld stored procedure:
Name Description Type Length In/Out Required
FldId Field identifier Char 30 In Yes
PlainText Plain Text Char 32624 In Yes
LogCmt Audit Log Comment Char 50 In No
ExtIndex Index number of value Decimal 13,0 Out
MsgId Message Id Char 7 Out
MsgText Message Text Char 80 Out
Errors Errors occurred (Y=Yes) Char 1 Out
Crypto Complete
Version 3.50 Linoma Software Page 141
P_UpdEncFld – Update Encrypted Field Value in External File
The P_UpdEncFld stored procedure will encrypt a field value and update the record in the external file with this encrypted value. The name of the external file is specified in the Field Encryption Registry. This stored procedure should only be used if all of the following conditions are met:
The field is registered and *ACTIVE in the Encryption Registry
Triggers are not used to automatically encrypt the field values
The encrypted values are stored in an external file Parameters for P_UpdEncFld stored procedure:
Name Description Type Length In/Out Required
FldId Field identifier Char 30 In Yes
ExtIndex Index number of value Decimal 13,0 In Yes
PlainText Plain Text Char 32624 In Yes
LogCmt Audit Log Comment Char 50 In No
RtnIndex Return Index number Decimal 13,0 Out
MsgId Message Id Char 7 Out
MsgText Message Text Char 80 Out
Errors Errors occurred (Y=Yes) Char 1 Out
The action performed in the P_UpdEncFld stored procedure is dependent on the values passed in the ExtIndex and PlainText:
If the ExtIndex is 0 and the PlainText is not blanks, then the encrypted value will be inserted into the external file and an Index Number will be returned in RtnIndex.
If the ExtIndex is not 0 and the PlainText is not blanks, then the encrypted value will be updated in the external file and the Index Number will be returned in RtnIndex.
If the ExtIndex is not 0 and the PlainText is blanks, then the encrypted value will be deleted from the external file and the Index Number of 0 will be returned in RtnIndex.
If the ExtIndex is 0 and the PlainText is blanks, then an error will be returned.
Crypto Complete
Version 3.50 Linoma Software Page 142
P_DltEncFld – Delete Encrypted Field Value from External File
The P_DltEncFld stored procedure will remove the encrypted field value from the external file. The name of the external file is specified in the Field Encryption Registry. This stored procedure should only be used if all of the following conditions are met:
The field is registered and *ACTIVE in the Encryption Registry
Triggers are not used to automatically encrypt the field values
The encrypted values are stored in an external file Parameters for P_DltEncFld stored procedure:
Name Description Type Length In/Out Required
FldId Field identifier Char 30 In Yes
ExtIndex Index number of value Decimal 13,0 In Yes
MsgId Message Id Char 7 Out
MsgText Message Text Char 80 Out
Errors Errors occurred (Y=Yes) Char 1 Out
Crypto Complete
Version 3.50 Linoma Software Page 143
P_GetEncFld – Get Decrypted Field Value from External File (Full value)
The P_GetEncFld stored procedure will retrieve an encrypted field value from an external file and decrypt it for use in the application. The name of the external file is specified in the Field Encryption Registry.
The user will be authorized to the full decrypted value if they have 1) at least *USE authority to the ‘Full’ Authorization List specified for the field and 2) at least *USE authority to the Key Store which holds the Decryption Key. The names of the Authorization List and Key Store can be found for the field identifier in the Encryption Registry.
This stored procedure should only be used if all of the following conditions are met:
The field is registered and *ACTIVE in the Encryption Registry
The encrypted values are stored in an external file Parameters for P_GetEncFld stored procedure:
Name Description Type Length In/Out Required
FldId Field identifier Char 30 In Yes
ExtIndex Index number of value Decimal 13,0 In Yes
LogCmt Audit Log Comment Char 50 In No
PlainText Plain Text Char 32624 Out
MsgId Message Id Char 7 Out
MsgText Message Text Char 80 Out
Errors Errors occurred (Y=Yes) Char 1 Out
Crypto Complete
Version 3.50 Linoma Software Page 144
P_GetEncFldMask – Get Decrypted Field Value from External File (Masked value)
The P_GetEncFldMask stored procedure will retrieve an encrypted field value from an external file, then decrypt it and apply a mask, based on the settings specified in the Field Encryption Registry. For instance, if a mask of ‘************9999’ is specified in the Registry for a credit card number, then a sample of a returned credit card number would be ‘************1234’.
The user will be authorized to the masked value if they have 1) at least *USE authority to the ‘Masked’ Authorization List specified for the field and 2) at least *USE authority to the Key Store which holds the Decryption Key. The names of the Authorization List and Key Store can be found for the field identifier in the Encryption Registry.
This stored procedure should only be used if all of the following conditions are met:
The field is registered and *ACTIVE in the Encryption Registry
The field has a mask value specified in the Encryption Registry
The encrypted values are stored in an external file Parameters for P_GetEncFldMask stored procedure:
Name Description Type Length In/Out Required
FldId Field identifier Char 30 In Yes
ExtIndex Index number of value Decimal 13,0 In Yes
LogCmt Audit Log Comment Char 50 In No
PlainText Plain Text (masked value) Char 32624 Out
MsgId Message Id Char 7 Out
MsgText Message Text Char 80 Out
Errors Errors occurred (Y=Yes) Char 1 Out
Note: If a mask is not specified for the Field in the Registry, then no value will be returned.
Crypto Complete
Version 3.50 Linoma Software Page 145
P_GetEncFldAuth – Get Decrypted Field Value from External File (Authorized value)
The P_GetEncFldAuth stored procedure can be used if the encrypted field values are stored in an external file. Based on the user’s authority to the field, the P_GetEncFldAuth stored procedure will return either 1) the fully decrypted value for the field or 2) the masked value for the field or 3) the not-authorized fill value that is specified for the field in the Registry, which may be blanks. The user’s authority to the field is determined by checking the Authority Lists indicated on the field’s AUTLDEC and AUTLMASK settings that are specified in the Field Encryption Registry. If a masked value is returned, the mask will be based on the field’s FLDMASK setting that is specified in the Field Encryption Registry. Parameters for P_GetEncFldAuth stored procedure:
Name Description Type Length In/Out Required
FldId Field identifier Char 30 In Yes
ExtIndex Index number of value Decimal 13,0 In Yes
LogCmt Audit Log Comment Char 50 In No
OutputText Output Text Char 32624 Out
MsgId Message Id Char 7 Out
MsgText Message Text Char 80 Out
Errors Errors occurred (Y=Yes) Char 1 Out
Note: The users (or user groups) which should have access to the decrypted (or masked) values will also need at least *USE authority to the Key Store object which holds the Decryption Key.
Crypto Complete
Version 3.50 Linoma Software Page 146
P_GetFldIdx – Get Index for a Field Value from External File
The P_GetFldIdx stored procedure will return the first external Index number found for the plain text value specified. If no record is found, then a 0 will be returned for the Index. This stored procedure should only be used if the field is active in the Field Encryption Registry and the encrypted values are stored in an external file. Parameters for P_GetFldIdx stored procedure:
Name Description Type Length In/Out Required
FldId Field Identifier Char 30 In Yes
PlainText Plain Text Char 32624 In Yes
ExtIndex Index of Value Decimal 13,0 Out
MsgId Message Id Char 7 Out
MsgText Message Text Char 80 Out
Errors Errors Char 1 Out
Crypto Complete
Version 3.50 Linoma Software Page 147
P_EncAES2 – Encrypt text with AES256 using Key Label (ECB block mode)
The P_EncAES2 stored procedure will encrypt text using the AES256 algorithm and ECB block mode. This procedure requires a Key Label. Parameters for P_EncAES2 procedure:
Name Description Type Length In/Out Required
PlainText Plain Text Char 32624 In Yes
PlainTextLen Plain Text Length Decimal 5,0 In Yes
KeyStrNam Key Store Name 1 Char 10 In No
KeyStrLib Key Store Library 2 Char 10 In No
KeyLabel Key Label Char 30 In Yes
LogCmt Audit Log Comment Char 50 In No
CipherText Encrypted Text Char 32624 Out
CipherTextLen Encrypted Text Length 3 Decimal 5,0 Out
MsgId Message Id Char 7 Out
MsgText Message Text Char 80 Out
Errors Errors occurred (Y=Yes) Char 1 Out
Parameter Notes:
1 Specify the special value of *DEFAULT for the Key Store Name in order to use the default key store
name indicated at the Key Policy level.
2 Specify *LIBL for the Key Store Library to locate the Key Store in the library list.
3 With AES block mode, the returned Cipher Text length will be a minimum of 16 bytes long. This
returned Cipher text length will be divisible by 16 or 24. For instance:
Plain Text Length Cipher Text Length
10 bytes 16 bytes
16 bytes 16 bytes
17 bytes 24 bytes
24 bytes 24 bytes
32 bytes 32 bytes
Crypto Complete
Version 3.50 Linoma Software Page 148
P_DecAES2 – Decrypt text with AES256 using Key Label (ECB block mode)
The P_DecAES2 stored procedure will decrypt text using the AES256 algorithm and ECB block mode. This procedure requires a Key Label. Parameters for P_DecAES2 procedure:
Name Description Type Length In/Out Required
CipherText Encrypted Text Char 32624 In Yes
CipherTextLen Encrypted Text Length Decimal 5,0 In Yes
KeyStrNam Key Store Name 1 Char 10 In No
KeyStrLib Key Store Library 2 Char 10 In No
KeyLabel Key Label Char 30 In Yes
LogCmt Audit Log Comment Char 50 In No
PlainText Plain Text Char 32624 Out
PlainTextLen Plain Text Length Decimal 5,0 Out
MsgId Message Id Char 7 Out
MsgText Message Text Char 80 Out
Errors Errors occurred (Y=Yes) Char 1 Out
Parameter Notes:
1 Specify the special value of *DEFAULT for the Key Store Name in order to use the default key store
name indicated at the Key Policy level.
2 Specify *LIBL for the Key Store Library to locate the Key Store in the library list.
Crypto Complete
Version 3.50 Linoma Software Page 149
P_EncAdv – Encrypt text with Advanced options using Key Label
The P_EncAdv stored procedure will encrypt text using advanced options. This program requires a Key Label. Parameters for P_EncAdv procedure:
Name Description Type Length In/Out Required
PlainText Plain Text Char 32624 In Yes
PlainTextLen Plain Text Length Decimal 5,0 In Yes
KeyStrNam Key Store Name 1 Char 10 In No
KeyStrLib Key Store Library 2 Char 10 In No
KeyLabel Key Store Label Char 30 In Yes
LogCmt Audit Log Comment Char 50 In No
Algorithm Algorithm 3 Char 10 In Yes
Mode Mode of Algorithm 4 Char 1 In No
BlockLen Block Length 5 Decimal 5,0 In No
PadOption Pad Option 6 Char 1 In No
PadChar Pad Character Char 1 In No
OutputType Output Type 7 Char 7 In No
OutputFmt Output Format 8 Char 7 In No
InitVector Initialization Vector (Salt) 9 Char 32 In/Out No
CipherText Encrypted Text Char 32624 Out
CipherTextLen Encrypted Text Length Decimal 5,0 Out
MsgId Message Id Char 7 Out
MsgText Message Text Char 80 Out
Errors Errors occurred (Y=Yes) Char 1 Out
Parameter Notes:
1 Specify the special value of *DEFAULT for the Key Store Name in order to use the default key store
name indicated at the Key Policy level.
2 Specify *LIBL for the Key Store Library to locate the Key Store in the library list.
3 Algorithms supported are *TDES (for Triple DES), *AES128, *AES192 and *AES256
4 Modes supported are ‘0’ for ECB, ‘1’ for CBC and ‘6’ for CUSP
5 Block length:
For *AES128, *AES192 and *AES256 algorithms: either specify a 0 to automatically calculate the block length or specify a block length of 16, 24 or 32.
For *TDES algorithm: specify a 0 to automatically calculate the block length or specify a block length of 8.
6 Valid values for the PadOption are:
‘0’ or blanks = No Padding ‘1’ = Pad using pad character (only valid with the *TDES algorithm) ‘2’ = Pad using pad number
Specifying a PadOption will pad the data in the PlainText out to the next block length multiple. For example, the block length would be 8 for *TDES algorithm. Therefore, a value’s length of 20 is padded to 24, 32 is padded to 40, and so forth. The last byte of data will contain a 1-byte binary counter containing the number of pad characters used (a value from 1 to 8). If PadOption is a ‘1’, the
Crypto Complete
Version 3.50 Linoma Software Page 150
PadChar value is used for the rest of the pad characters. If PadOption is ‘2’, the binary counter is used for the rest of the pad characters.
7 OutputType valid values are *EBCDIC and *ASCII. If none is specified, then the default value of
*EBCDIC will be used. 8 OutputFmt valid values are *CHAR, *HEX and *BASE64. If none is specified, then the default value
of *CHAR will be used. 9 Initialization vector (IV): Specify an IV value to manipulate the encryption operation. In other words,
the same Plain Text which is encrypted with different IVs will produce different Cipher text values. For *AES algorithms, the IV length should not exceed the block length. For *TDES, the IV length should not exceed 8. The IV need not be secret, but it should be unique. Upon completion of the operation, an output chaining value will be returned in the IV field. This value can be used as the IV for the next operation when encrypting or decrypting text in multiple blocks. Refer to ANSI X9.52 for an explanation of its use. Allowed for algorithm modes of ‘1’ (CBC) and ‘6’ (CUSP).
Additional Notes for P_EncAdv:
When using *AES128, *AES192 and *AES256 algorithms with ECB or CBC modes, the returned Cipher Text length will be a minimum of 16 bytes long. This returned Cipher text length will be divisible by 16 or 24. For instance:
Plain Text Length Cipher Text Length
10 bytes 16 bytes
16 bytes 16 bytes
17 bytes 24 bytes
24 bytes 24 bytes
32 bytes 32 bytes
When using *AES128, *AES192 and *AES256 algorithms with CUSP mode, the returned Cipher Text length will be the same as the Plain Text length.
For *TDES algorithm, the returned Cipher Text length will be a minimum of 8 bytes long. This returned Cipher text length will be divisible by 8. For instance:
Plain Text Length Cipher Text Length
5 bytes 8 bytes
8 bytes 8 bytes
9 bytes 16 bytes
16 bytes 16 bytes
Crypto Complete
Version 3.50 Linoma Software Page 151
P_DecAdv – Decrypt text with Advanced options using Key Label
The P_DecAdv stored procedure will decrypt text using advanced options. This program requires a Key Label. Parameters for P_DecAdv procedure:
Name Description Type Length In/Out Required
CipherText Encrypted Text Char 32624 In Yes
CipherTextLen Encrypted Text Length Decimal 5,0 In Yes
InputType Input Type 1 Char 7 In No
InputFmt Input Format 2 Char 7 In No
KeyStrNam Key Store Name 3 Char 10 In No
KeyStrLib Key Store Library 4 Char 10 In No
KeyLabel Key Store Label Char 30 In Yes
LogCmt Audit Log Comment Char 50 In No
Algorithm Algorithm 5 Char 10 In Yes
Mode Mode of Algorithm 6 Char 1 In No
BlockLen Block Length 7 Decimal 5,0 In No
PadOption Pad Option 8 Char 1 In No
PadChar Pad Character Char 1 In No
InitVector Initialization Vector (Salt) 9 Char 32 In/Out No
PlainText Plain Text Char 32624 Out
PlainTextLen Plain Text Length Decimal 5,0 Out
MsgId Message Id Char 7 Out
MsgText Message Text Char 80 Out
Errors Errors occurred (Y=Yes) Char 1 Out
Parameter Notes:
1 InputType valid values are *EBCDIC and *ASCII. If none is specified, then the default value of
*EBCDIC will be used.
2 InputFmt valid values are *CHAR, *HEX and *BASE64. If none is specified, then the default value of
*CHAR will be used.
3 Specify the special value of *DEFAULT for the Key Store Name in order to use the default key store
name indicated at the Key Policy level.
4 Specify *LIBL for the Key Store Library to locate the Key Store in the library list.
5 Algorithms supported are *TDES (for Triple DES), *AES128, *AES192 and *AES256
6 Modes supported are ‘0’ for ECB, ‘1’ for CBC and ‘6’ for CUSP
7 Block length:
o For *AES128, *AES192 and *AES256 algorithms: either specify a 0 to automatically calculate the block length or specify a block length of 16, 24 or 32.
o For *TDES algorithm: specify a 0 to automatically calculate the block length or specify a block length of 8.
Crypto Complete
Version 3.50 Linoma Software Page 152
8 Valid values for the PadOption are:
‘0’ or blanks = Value is not padded ‘1’ = Value is padded with a pad character (only valid with the *TDES algorithm) ‘2’ = Value is padded with a pad number
Specifying a PadOption will strip the pad bytes off the end of the value before returning it in the PlainText.
9 Initialization vector (IV): Specify an IV value to manipulate the decryption operation. In other words,
the same Cipher which is decrypted with different IVs will produce different Plain text values. For *AES algorithms, the IV length should not exceed the block length. For *TDES, the IV length should not exceed 8. The IV need not be secret, but it should be unique. Upon completion of the operation, an output chaining value will be returned in the IV field. This value can be used as the IV for the next operation when encrypting or decrypting text in multiple blocks. Refer to ANSI X9.52 for an explanation of its use. Allowed for algorithm modes of ‘1’ (CBC) and ‘6’ (CUSP). 6
Crypto Complete
Version 3.50 Linoma Software Page 153
Deprecated APIs
As new releases of Crypto Complete are introduced, certain APIs may be replaced (deprecated) by other APIs for to add new functionality and parameters or correct issues. You can continue to use the deprecated APIs in your applications, although they will no longer be supported by Linoma Software. If you want to use any of the replacement APIs in your applications, please be sure to read the documentation on these APIs to learn about any new parameters or enhancements/changes in functionality. After modifying your applications to use the replacement APIs, you should test your applications thoroughly to ensure that their program behavior does not produce undesirable results by using the replacement APIs. Deprecated ILE Procedure APIs:
Crypto Complete Version
Deprecated API Name
Replacement API Name
2.0 DecFld2 DecFldMask
2.0 GetEncFld2 GetEncFldMask
2.0 EncAdv1 EncAdv3
2.0 EncAdv2 EncAdv4
2.0 DecAdv1 DecAdv3
2.0 DecAdv2 DecAdv4
Deprecated Program APIs:
Crypto Complete Version
Deprecated API Name
Replacement API Name
2.0 CRRP610 CRRP633
2.0 CRRP611 CRRP634
2.0 CRRP612 CRRP635
2.0 CRRP613 CRRP636
2.0 CRRP623 CRRP639
2.0 CRRP624 CRRP640
Crypto Complete
Version 3.50 Linoma Software Page 154
License agreement and limited warranty
READ CAREFULLY BEFORE USING The Crypto Complete software ('CRYPTO COMPLETE') is a proprietary product of Linoma Software ('LINOMA SOFTWARE') and is protected by this Agreement, copyright laws and international treaties. This is a legal agreement (the 'Agreement') between you, the user, and LINOMA SOFTWARE. Clicking on the license agreement acceptance button (if you are downloading CRYPTO COMPLETE), opening the package (if you have acquired a copy of CRYPTO COMPLETE on physical media) or loading or using CRYPTO COMPLETE on your system indicates your acceptance of the terms of this Agreement. If you do not wish to agree to the terms of this Agreement, you should promptly notify LINOMA SOFTWARE and immediately remove CRYPTO COMPLETE from your system and cease use of CRYPTO COMPLETE. A. LINOMA SOFTWARE grants you the right to use CRYPTO COMPLETE on your computer system. If you have a trial version
of CRYPTO COMPLETE, your license is limited to use only during the trial period and only for evaluation purposes. B. You may not alter, modify, decompile, disassemble or reverse engineer CRYPTO COMPLETE, or otherwise attempt to
reproduce the source code thereof. C. You acknowledge that CRYPTO COMPLETE is provided pursuant to a license and all title and ownership to CRYPTO
COMPLETE shall remain with LINOMA SOFTWARE or its licensors. D. You may use CRYPTO COMPLETE only for your own internal business purposes and may not use CRYPTO COMPLETE in a
service bureau (or similar) environment unless your customers have also purchased a license to CRYPTO COMPLETE or a special licensing arrangement has been arranged with LINOMA SOFTWARE.
TERM This license is effective until terminated. You may terminate it at any time by destroying CRYPTO COMPLETE together with all copies and merged portions in any form. It will also terminate upon conditions set forth elsewhere in this Agreement, or if you fail to comply with any term or condition of this Agreement. LIMITED WARRANTY YOU HEREBY ACKNOWLEDGE AND AGREE THAT CRYPTO COMPLETE IS PROVIDED BY LINOMA SOFTWARE ON AN "AS IS" BASIS, AND YOUR ACCESS TO AND/OR USE OF CRYPTO COMPLETE IS AT YOUR SOLE RISK. LINOMA SOFTWARE EXPRESSLY DISCLAIMS ALL WARRANTIES OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THOSE OF MERCHANTABILITY, SATISFACTORY QUALITY, TITLE, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT. LINOMA SOFTWARE MAKES NO WARRANTY THAT CRYPTO COMPLETE WILL MEET YOUR REQUIREMENTS OR THAT YOUR USE OF CRYPTO COMPLETE WILL BE UNINTERRUPTED, TIMELY OR ERROR-FREE, NOR DOES LINOMA SOFTWARE MAKE ANY WARRANTY AS TO THE RESULTS THAT MAY BE OBTAINED FROM THE USE OF CRYPTO COMPLETE OR THAT ANY DEFECTS WILL BE CORRECTED. YOU UNDERSTAND AND AGREE THAT THE USE OF CRYPTO COMPLETE IS DONE AT YOUR SOLE RISK AND THAT YOU WILL BE SOLELY RESPONSIBLE FOR ANY DAMAGE TO YOUR SYSTEM OR LOSS OF DATA. NO INFORMATION OR ADVICE, WHETHER ORAL OR WRITTEN, OBTAINED BY YOU FROM LINOMA SOFTWARE OR THROUGH CRYPTO COMPLETE SHALL CREATE ANY WARRANTY NOT EXPRESSLY MADE HEREIN. SOME JURISDICTIONS DO NOT ALLOW THE EXCLUSION OF CERTAIN WARRANTIES, SO SOME OF THE ABOVE EXCLUSIONS MAY NOT APPLY TO YOU. IN NO EVENT WILL LINOMA SOFTWARE BE LIABLE TO YOU FOR ANY SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES, INCLUDING BUT NOT LIMITED TO ANY LOST PROFITS, LOST SAVINGS, LOST DATA OR LOST BUSINESS OPPORTUNITIES ARISING OUT OF THE USE OR INABILITY TO USE CRYPTO COMPLETE EVEN IF LINOMA SOFTWARE HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. Circumstances may arise where, because of a default on LINOMA SOFTWARE's part or other liability, you are entitled to recover damages from LINOMA SOFTWARE. In each such instance, regardless of the basis on which you may be entitled to claim damages from LINOMA SOFTWARE, (including fundamental breach, negligence, misrepresentation, or other contract or tort claim), LINOMA SOFTWARE is liable for no more than the amount you paid for CRYPTO COMPLETE. This limited warranty gives you specific legal rights. Some states provide other rights, and some states do not allow excluding or limiting implied warranties or limiting liability for incidental or consequential damages. As a result, the above limitations and or exclusions may not apply to you. Furthermore, some jurisdictions have statutory consumer product provisions which may supersede these provisions of the Agreement. GENERAL If any provision of this Agreement shall be unlawful, void or for any reason unenforceable, then that provision shall be deemed severable from this Agreement and shall not affect the validity and enforceability of the remaining provisions of this Agreement. This Agreement will be governed by the laws of the State of Nebraska including the applicable provisions of the Uniform Electronic Transactions Act, as adopted in the State of Nebraska.
Crypto Complete
Version 3.50 Linoma Software Page 155
Contacting Linoma Software
The Company Founded in 1994, Linoma Software provides innovative technologies for protecting sensitive data and automating data movement. Linoma Software has a diverse install base of over 3,000 customers around the world including Fortune 500 companies, non-profit organizations and government entities. Linoma’s success has been built on being very responsive to our customer’s requirements. So if you have suggestions on how we can improve our products to better serve your organization, please let us know.
How to Contact Linoma Software
Electronic
Sales [email protected] Support [email protected] Website Hwww.linomasoftware.com
Phone Numbers
Toll-free: 1-800-949-4696 Outside USA: (402) 944-4242 Fax: (402) 944-4243
Address
Linoma Software 103 South 14
th Street
Ashland, NE 68003 USA