programmers guide - att.esatt.es/archivos/cryptocomplete_programmersguide_3_50.pdf · this...

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.

Polaris

Att_contacto

Crypto Complete

Version 3.50 Linoma Software

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


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


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


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


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:


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:


ILE Procedures

Programs

Comments

Yes GetEncFld GetEncFldMask GetEncFldAuth


Returns full decrypted value Returns masked value Returns authorized value (full or masked)

No DecFld DecFldMask DecFldAuth


Returns full decrypted value Returns masked value Returns authorized value (full or masked)

SQL Functions and Stored Procedures:


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


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


ILE Procedures

Programs

Key Token ReqKeyTkn RlsKeyTkn EncTDES1 DecTDES1


Key Label EncTDES2 DecTDES2

CRRP608 CRRP609

AES or TDES with Advanced Options


ILE Procedures

Programs

SQL Functions

Stored Procedures

Key Token ReqKeyTkn RlsKeyTkn EncAdv3 DecAdv3


Key Label EncAdv4 DecAdv4

CRRP635 CRRP636

F_EncAdv F_DecAdv

P_EncAdv P_DecAdv

Protegrity compatible format


ILE Procedures

Key Label PtgEnc PtgDec

Crypto Complete


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


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


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


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 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:



CipherText Encrypted Text Alpha 32624 In Yes


PlainText Plain Text Alpha 32624 Out






/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;


… logic …

Endif;

/END-FREE

Crypto Complete


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.



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:





PlainText Plain Text (masked) Alpha 32624 Out






/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;


… 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


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 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:





OutputText Output Text Alpha 32624 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


DecFldAuth example in /Free form RPG:



/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;


… logic …

Endif;

/END-FREE

Crypto Complete


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 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:





ExtIndex Index number of value Packed 13,0 Out






/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;


… logic …

Endif;

/END-FREE

Crypto Complete


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 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:



ExtIndex Index number of value Packed 13,0 In Yes








/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;


… logic …

Endif;

/END-FREE

Crypto Complete


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 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:









/FREE



// 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;


… logic …

Endif;

/END-FREE

Crypto Complete


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 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:











/FREE



// Using the index specified in ExtIndex, retrieve the value from

// external file, decrypt and return it.

If GetEncFld (‘CCFIELD’

:ExtIndex

:LogCmt

:CreditCardValue

:MsgId

:MsgText);


… logic …

Else;


… logic …

Endif;

/END-FREE

Crypto Complete


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 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:











/FREE // Convert the index number (stored in ccno) from alphanumeric to decimal


// 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;


… logic …

Endif;

/END-FREE

Crypto Complete


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 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:








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


GetEncFldAuth example in /Free form RPG:



/FREE



// 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;


… logic …

Endif;

/END-FREE

Crypto Complete


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:



Attribute Attribute name 1 Alpha 30 In Yes

Value Value 2 Alpha 30 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


GetFldAttr example in /Free form RPG:



/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;


… logic …

Endif;

/END-FREE

Crypto Complete


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:


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






/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;


… logic …

Endif;

/END-FREE

Crypto Complete


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:



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






/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;


… logic …

Endif;

/END-FREE

Crypto Complete


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:



KeyId Key identifier Signed 5,0 Out












/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;


… logic …

Endif;

/END-FREE

Crypto Complete


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:



InKeyId Previous Key identifier (in) Signed 5,0 In Yes

OutKeyId Next Key identifier (out) Signed 5,0 Out









Return value: *ON if successful, *OFF if errors

Example in /Free form RPG:



/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;


… logic …

Endif;

/END-FREE

Crypto Complete


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:



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






/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;


… logic …

Endif;

/END-FREE

Crypto Complete


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:


FldId Field Identifier Alpha 30 In Yes


ExtIndex Index of Value Packed 13,0 Out




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


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:



ExtIndex External Index Nbr. - Char Alpha 34 In Yes

ExtIndexDec External Index Nbr. - Dec Packed 13,0 Out






/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);


… logic …

Endif;

Endif;

/END-FREE

Crypto Complete


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:


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




/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;


… 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


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:








/FREE

// Release token

If RlsKeyTkn (KeyTkn

:MsgId

:MsgText);

// Success

… logic …

Else;


… logic …

Endif;

/END-FREE

Crypto Complete


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:



PlainTextLen Plain Text Length Integer 10,0 In Yes

KeyTkn Key Token Alpha 8 In Yes



CipherTextLen Encrypted Text Length Integer 10,0 Out






/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;


… logic …

Endif;

/END-FREE

Crypto Complete


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


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:



CipherTextLen Encrypted Text Length Integer 10,0 In Yes




PlainTextLen Plain Text Length Integer 10,0 Out






/FREE

// Decrypt the value contained in CipherText variable

If DecAES1 (CipherText

:CipherTextLength

:KeyTkn


:CreditCard

:ReturnedLength

:MsgId

:MsgText);

// Success-> The decrypted value is in CreditCard variable

… logic …

Else;


… logic …

Endif;

/END-FREE

Crypto Complete


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:















/FREE

// Encrypt value contained in CreditCard variable

If EncAES2 (CreditCard

:CreditCardLength

:‘OE_KEYS’

:‘*LIBL’



:CipherText

:CipherTextLen

:MsgId

:MsgText);


… logic …

Else;


… logic …

Endif;

/END-FREE

Crypto Complete


Notes for EncAES2:


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:


10 bytes 16 bytes

16 bytes 16 bytes

17 bytes 24 bytes

24 bytes 24 bytes

32 bytes 32 bytes

Crypto Complete


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:






KeyLabel Key Store Label Alpha 30 In Yes









/FREE

// Decrypt value in CipherText variable

If DecAES2 (CipherText

:CipherTextLength

:‘OE_KEYS’

:‘*LIBL’



:CreditCard

:CreditCardLen

:MsgId

:MsgText);


… logic …

Else;


… logic …

Endif;

/END-FREE

Crypto Complete


Notes for DecAES2:



Crypto Complete


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:













/FREE

// Encrypt value in CreditCard variable

If EncTDES1(CreditCard

:CreditCardLength

:KeyTkn


:CipherText

:CipherTextLen

:MsgId

:MsgText);


… logic …

Else;


… logic …

Endif;

/END-FREE

Crypto Complete


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:


5 bytes 8 bytes

8 bytes 8 bytes

9 bytes 16 bytes

16 bytes 16 bytes

Crypto Complete


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:













/FREE


If DecTDES1(CipherText

:CipherTextLength

:KeyTkn


:CreditCard

:ReturnedLength

:MsgId

:MsgText);


… logic …

Else;


… logic …

Endif;

/END-FREE

Crypto Complete


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:















/FREE

// Encrypt value in CreditCard variable

If EncTDES2(CreditCard

:CreditCardLength

:‘OE_KEYS’

:‘*LIBL’



:CipherText

:CipherTextLen

:MsgId

:MsgText);


… logic …

Else;


… logic …

Endif;

/END-FREE

Crypto Complete


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.


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:


5 bytes 8 bytes

8 bytes 8 bytes

9 bytes 16 bytes

16 bytes 16 bytes

Crypto Complete


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:















/FREE


If DecTDES2(CipherText

:CipherTextLength

:‘OE_KEYS’

:‘*LIBL’



:CreditCard

:CreditCardLen

:MsgId

:MsgText);


… logic …

Else;


… logic …

Endif;

/END-FREE

Crypto Complete


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.


Crypto Complete


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:






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






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


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).




/FREE

// Encrypt value in CreditCard variable using AES256

If EncAdv3 (CreditCard

:CreditCardLength

:KeyTkn


:‘*AES256’

:‘0’

:16

:PadOption

:PadChar

:‘*EBCDIC’

:‘*CHAR’

:InitVector

:CipherText

:CipherTextLen

:MsgId

:MsgText);


… logic …

Else;


… logic …

Endif;

/END-FREE

Crypto Complete


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:


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:


5 bytes 8 bytes

8 bytes 8 bytes

9 bytes 16 bytes

16 bytes 16 bytes

Crypto Complete


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:




InputType Input Type 1 Alpha 7 In No

InputFmt Input Format 2 Alpha 7 In No














1 InputType valid values are *EBCDIC and *ASCII. If none is specified, then the default value of


2 InputFmt valid values are *CHAR, *HEX and *BASE64. If none is specified, then the default value of

*CHAR will be used.



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



‘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).




/FREE

// Decrypt value in CipherText variable using AES256 algorithm

If DecAdv3 (CipherText

:CipherTextLen

:‘*EBCDIC’

:‘*CHAR’

:KeyTkn


:‘*AES256’

:‘0’

:16

:PadOption

:PadChar

:InitVector

:CreditCard

:CreditCardLength

:MsgId

:MsgText);


… logic …

Else;


… logic …

Endif;

/END-FREE

Crypto Complete


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:




KeyStrNam Key Store Name 1 Alpha 10 In No

KeyStrLib Key Store Library 2 Alpha 10 In No
















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.



5 Block length:



Crypto Complete






*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,





/FREE

// Encrypt value in CreditCard variable using AES256 algorithm

If EncAdv4 (CreditCard

:CreditCardLength

:‘OE_KEYS’

:‘*LIBL’



:‘*AES256’

:‘0’

:16

:PadOption

:PadChar

:‘*EBCDIC’

:‘*CHAR’

:InitVector

:CipherText

:CipherTextLen

:MsgId

:MsgText);


… logic …

Else;


… logic …

Endif;

/END-FREE

Crypto Complete


Additional notes for EncAdv4:



10 bytes 16 bytes

16 bytes 16 bytes

17 bytes 24 bytes

24 bytes 24 bytes

32 bytes 32 bytes




5 bytes 8 bytes

8 bytes 8 bytes

9 bytes 16 bytes

16 bytes 16 bytes

Crypto Complete


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:
























*CHAR will be used.






7 Block length:



Crypto Complete



‘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







/FREE

// Decrypt value in CipherText variable using AES256 algorithm

If DecAdv4 (CipherText

:CipherTextLen

:‘*EBCDIC’

:‘*CHAR’

:‘OE_KEYS’

:‘*LIBL’



:‘*AES256’

:‘0’

:16

:PadOption

:PadChar

:InitVector

:CreditCard

:CreditCardLength

:MsgId

:MsgText);


… logic …

Else;


… logic …

Endif;

/END-FREE

Crypto Complete


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:


InputValue Input Value Alpha 1000 In Yes

InputLen Input Length Integer 10,0 In Yes

HashValue Hash value Alpha 20 Out






/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;


… 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


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:



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







/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;


… 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


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.




Crypto Complete


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






/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


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:









Mode Mode 4 Alpha 5 In Yes



CRC Use CRC checksum 7 Alpha 4 In No

InitVector Initialization Vector (Salt) 8 Alpha 4 In Yes










4 Mode supported is *CRC



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





/FREE

// Encrypt the value in CreditCard variable using AES256 algorithm

If PtgEnc (CreditCard

:CreditCardLength

:‘OE_KEYS’

:‘*LIBL’



:‘*AES256’

:‘*CRC’

:‘*EBCDIC’

:‘*CHAR’

:‘*YES’

:‘*YES’

:CipherText

:CipherTextLen

:MsgId

:MsgText);


… logic …

Else;


… 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:


10 bytes 16 bytes

16 bytes 16 bytes

17 bytes 24 bytes

24 bytes 24 bytes

32 bytes 32 bytes



5 bytes 8 bytes

8 bytes 8 bytes

9 bytes 16 bytes

16 bytes 16 bytes

Crypto Complete


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:











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









*CHAR will be used.





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





/FREE

// Decrypt the value in CipherText variable using AES256 algorithm

If PtgDec (CipherText

:CipherTextLength

:‘*EBCDIC’

:‘*CHAR’

:‘OE_KEYS’

:‘*LIBL’



:‘*AES256’

:‘*CRC ’

:‘*YES’

:‘*YES’

:CreditCard

:CreditCardLength

:MsgId

:MsgText);


… logic …

Else;


… logic …

Endif;

/END-FREE

Crypto Complete


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


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


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 encrypted values are not stored in an external file Parameters for CRRP615 program:








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


CRRP616 – Decrypt Field Value (Full value)

The CRRP616 program will decrypt 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:












C* Decrypt value in CIPHERTEXT variable using registry field id CCFIELD

C CALL 'CRRP616'




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 ELSE



C ENDIF

Crypto Complete


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’.















C* Process value in CIPHERTEXT variable using registry field id CCFIELD

C CALL 'CRRP639'




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 ELSE



C ENDIF


Crypto Complete


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:












C* Decrypt value in CIPHERTEXT variable using registry field id CCFIELD

C CALL 'CRRP637'




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 ELSE



C ENDIF


Crypto Complete


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 encrypted values are stored in an external file Parameters for CRRP617 program:





ExtIndex Index number of value Packed 13,0 Out





C* Encrypt value in PLAINTEXT variable and insert into external file

C CALL 'CRRP617'




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 ELSE



C ENDIF

Crypto Complete


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:













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 MSGID 7

C PARM MSGTEXT 80

C PARM ERRORS 1

C* Success-> Encrypted value was stored



C ELSE



C ENDIF

Crypto Complete


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:













C* Using the index specified in EXTINDEX, remove the encrypted value

C* from the external file

C CALL 'CRRP619'



C PARM MSGID 7

C PARM MSGTEXT 80

C PARM ERRORS 1

C* Success-> Encrypted value was removed



C ELSE



C ENDIF

Crypto Complete


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.
















C* Using the index specified in EXTINDEX, retrieve the value from the

C* external file, decrypt and return it.

C CALL 'CRRP620'





C PARM MSGID 7

C PARM MSGTEXT 80

C PARM ERRORS 1

C* Success-> Decrypted value is in PLAINTEXT variable



C ELSE



C ENDIF

Crypto Complete


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’.

















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 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 ELSE



C ENDIF


Crypto Complete


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:














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 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 ELSE



C ENDIF


Crypto Complete


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:



Attribute Attribute name 1 Alpha 30 In Yes

Value Value 2 Alpha 30 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


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 ELSE



C ENDIF

Crypto Complete


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:


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





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 ELSE



C ENDIF

Crypto Complete


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:













C* Get the current set of Key Labels and Key Stores used for ‘CCFIELD’

C CALL 'CRRP622'


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 ELSE



C ENDIF

Crypto Complete


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:



KeyId Key identifier Packed 5,0 Out











C* Get the first set of Key Labels and Key Stores used for ‘CCFIELD’

C CALL 'CRRP627'


C PARM KEYID 5 0







C PARM MSGID 7

C PARM MSGTEXT 80

C PARM ERRORS 1

C* Success-> First set of Keys found



C ELSE



C ENDIF

Crypto Complete


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:



InKeyId Previous Key identifier (in) Packed 5,0 In Yes

OutKeyId Next Key identifier (out) Packed 5,0 Out











C* Get the next set of Key Labels and Key Stores used for ‘CCFIELD’

C CALL 'CRRP628'


C PARM INKEYID 5 0

C PARM OUTKEYID 5 0







C PARM MSGID 7

C PARM MSGTEXT 80

C PARM ERRORS 1

C* Success-> Next set of Keys found



C ELSE



C ENDIF

Crypto Complete


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:



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





C* Get the External file name and library used for field id ‘CCFIELD’

C CALL 'CRRP625'


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 ELSE



C ENDIF

Crypto Complete


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:


FldId Field Identifier Alpha 30 In Yes


ExtIndex Index of Value Packed 13,0 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 CCNO PLAINTEXT 32624


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 ELSE



C ENDIF

Crypto Complete


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:



ExtIndex External Index Nbr. - Char Alpha 34 In Yes

ExtIndexDec External Index Nbr. - Dec Packed 13,0 Out





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 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* Using the numeric index specified in EXTINDEXDEC, retrieve the value

C* from the external file, decrypt and return it.

C CALL 'CRRP620'


C PARM EXTINDEXDEC 13 0



C PARM MSGID 7

C PARM MSGTEXT 80

C PARM ERRORS 1

C* Success-> Decrypted value is in PLAINTEXT variable



C ELSE



C ENDIF

C ENDIF

Crypto Complete


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:









Parameter Notes:





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 ELSE



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


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:







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 ELSE



C ENDIF

Crypto Complete


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:



PlainTextLen Plain Text Length Packed 5,0 In Yes




CipherTextLen Encrypted Text Length 1 Packed 5,0 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:


10 bytes 16 bytes

16 bytes 16 bytes

17 bytes 24 bytes

24 bytes 24 bytes

32 bytes 32 bytes


C* Encrypt value in variable PLAINTEXT

C CALL 'CRRP602'


C PARM 9 PLAINLEN 5 0

C PARM KEYTKN 8



C PARM CIPHERLEN 5 0

C PARM MSGID 7

C PARM MSGTEXT 80

C PARM ERRORS 1




C ELSE



C ENDIF

Crypto Complete


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:



CipherTextLen Encrypted Text Length Packed 5,0 In Yes




PlainTextLen Plain Text Length Packed 5,0 Out





C* Decrypt value in variable CIPHERTEXT

C CALL 'CRRP603'



C PARM KEYTKN 8



C PARM PLAINLEN 5 0

C PARM MSGID 7

C PARM MSGTEXT 80

C PARM ERRORS 1




C ELSE



C ENDIF

Crypto Complete


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:













Parameter Notes:







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


CRRP604 Example in Fixed format RPG:

C* Encrypt value in variable PLAINTEXT using key label CARD_KEY

C CALL 'CRRP604'









C PARM MSGID 7

C PARM MSGTEXT 80

C PARM ERRORS 1




C ELSE



C ENDIF

Crypto Complete


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:













Parameter notes:




CRRP605 example in Fixed format RPG:

C* Decrypt value in variable CIPHERTEXT using key label CARD_KEY

C CALL 'CRRP605'








C PARM PLAINLEN 5 0

C PARM MSGID 7

C PARM MSGTEXT 80

C PARM ERRORS 1




C ELSE



C ENDIF

Crypto Complete


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:











Parameter Notes:

1 With TDES block mode, the returned Cipher Text length will be a minimum of 8 bytes long. This



5 bytes 8 bytes

8 bytes 8 bytes

9 bytes 16 bytes

16 bytes 16 bytes



C CALL 'CRRP606'



C PARM KEYTKN 8




C PARM MSGID 7

C PARM MSGTEXT 80

C PARM ERRORS 1




C ELSE



C ENDIF

Crypto Complete


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:













C CALL 'CRRP607'



C PARM KEYTKN 8



C PARM PLAINLEN 5 0

C PARM MSGID 7

C PARM MSGTEXT 80

C PARM ERRORS 1




C ELSE



C ENDIF

Crypto Complete


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:













Parameter Notes:




3 With TDES block mode, the returned Cipher Text length will be a minimum of 8 bytes long. This



5 bytes 8 bytes

8 bytes 8 bytes

9 bytes 16 bytes

16 bytes 16 bytes

(see source example on next page)

Crypto Complete


CRRP608 example in Fixed format RPG:


C CALL 'CRRP608'









C PARM MSGID 7

C PARM MSGTEXT 80

C PARM ERRORS 1




C ELSE



C ENDIF

Crypto Complete


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:













Parameter Notes:






C CALL 'CRRP609'








C PARM PLAINLEN 5 0

C PARM MSGID 7

C PARM MSGTEXT 80

C PARM ERRORS 1




C ELSE



C ENDIF

Crypto Complete


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:








BlockLen Block Length 3 Packed 5,0 In No







CipherTextLen Encrypted Text Length Packed 5,0 Out




Parameter Notes:



3 Block length:









Crypto Complete






C CALL 'CRRP633'



C PARM KEYTKN 8


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 MSGID 7

C PARM MSGTEXT 80

C PARM ERRORS 1




C ELSE



C ENDIF

Crypto Complete


Additional Notes for CRRP633:



10 bytes 16 bytes

16 bytes 16 bytes

17 bytes 24 bytes

24 bytes 24 bytes

32 bytes 32 bytes




5 bytes 8 bytes

8 bytes 8 bytes

9 bytes 16 bytes

16 bytes 16 bytes

Crypto Complete


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:



















Parameter Notes:




*CHAR will be used.



5 Block length:



Crypto Complete









C CALL 'CRRP634'



C PARM ‘*EBCDIC’ INPUTTYPE 7

C PARM ‘*CHAR’ INPUTFMT 7

C PARM KEYTKN 8



C PARM '0' MODE 1


C PARM PADOPTION 1

C PARM PADCHAR 1

C PARM INTVECTOR 32


C PARM PLAINLEN 5 0

C PARM MSGID 7

C PARM MSGTEXT 80

C PARM ERRORS 1




C ELSE



C ENDIF

Crypto Complete


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:

















CipherTextLen Encrypted Text Length Packed 5,0 Out




Parameter Notes:






5 Block length:






Crypto Complete








C CALL 'CRRP635'








C PARM '0' MODE 1


C PARM PADOPTION 1

C PARM PADCHAR 1

C PARM ‘*EBCDIC’ OUTPUTTYPE 7

C PARM ‘*CHAR’ OUTPUTFMT 7

C PARM INTVECTOR 32



C PARM MSGID 7

C PARM MSGTEXT 80

C PARM ERRORS 1




C ELSE



C ENDIF

Crypto Complete


Additional Notes for CRRP635:



10 bytes 16 bytes

16 bytes 16 bytes

17 bytes 24 bytes

24 bytes 24 bytes

32 bytes 32 bytes




5 bytes 8 bytes

8 bytes 8 bytes

9 bytes 16 bytes

16 bytes 16 bytes

Crypto Complete


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:





















Parameter Notes:




*CHAR will be used.






7 Block length:



Crypto Complete



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






C CALL 'CRRP636'



C PARM ‘*EBCDIC’ INPUTTYPE 7

C PARM ‘*CHAR’ INPUTFMT 7






C PARM '0' MODE 1


C PARM PADOPTION 1

C PARM PADCHAR 1

C PARM INTVECTOR 32


C PARM PLAINLEN 5 0

C PARM MSGID 7

C PARM MSGTEXT 80

C PARM ERRORS 1




C ELSE



C ENDIF

Crypto Complete


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:



InputLen Input Length Packed 5,0 In Yes






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 ELSE



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


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:






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 ELSE

C* Errors-> The CRVL001 object is not valid


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


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


C* Close last external file that was opened

C CALL 'CRRP641'

Crypto Complete


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:



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






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 ELSE



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


Parameter Notes:

1 Valid hash types are MD5, SHA-1, SHA-256, SHA-384 and SHA-512.




Crypto Complete


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


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 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:


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


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.


This function should only be used if all of the following conditions are met:


The encrypted values are not stored in an external file Parameters for F_DecFld function:



Cipher Text Char 32624

Return value:



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


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 encrypted values are not stored in an external file Parameters for F_DecFldMask function:




Return value:


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



Crypto Complete


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 encrypted values are not stored in an external file Parameters for F_DecFldAuth function:




Return value:


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



Crypto Complete


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 encrypted values are stored in an external file Parameters for F_InsEncFld function:



Plain value to encrypt Decimal 30,4

Return value:


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 */


SET CreditCard = F_InsEncFld(‘CCFIELD’, CreditCard)


Crypto Complete


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 encrypted values are stored in an external file Parameters for F_InsEncFldChr function:




Return value:


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 */


SET CreditCard = F_InsEncFld(‘CCFIELD’, CreditCard)


Crypto Complete


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 encrypted values are stored in an external file Parameters for F_UpdEncFld function:




Plain Value to encrypt Decimal 30,4

Return value:



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 */


SET CreditCard = F_UpdEncFld(‘CCFIELD’, CreditCard, NewCreditCard)


Crypto Complete


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 encrypted values are stored in an external file Parameters for F_UpdEncFldChr function:





Return value:



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 */


SET CreditCard = F_UpdEncFldChr(‘CCFIELD’, CreditCard, NewCreditCard)


Crypto Complete


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 encrypted values are stored in an external file Parameters for F_DltEncFld function:




Return value:



SQL Example:

/* Delete the encrypted value for the index number specified in CreditCard

*/


SET OldIndex = F_DltEncFld(‘CCFIELD’, CreditCard)


Crypto Complete


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 encrypted values are stored in an external file Parameters for F_DltEncFldChr function:




Return value:



SQL Example:

/* Delete the encrypted value for the index number specified in CreditCard

*/


SET OldIndex = F_DltEncFldChr(‘CCFIELD’, CreditCard)


Crypto Complete


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 encrypted values are stored in an external file Parameters for F_GetEncFld function:




Return value:


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


Crypto Complete


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 encrypted values are stored in an external file Parameters for F_GetEncFldChr function:




Return value:



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


Crypto Complete


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 Index number parameter is passed in as a Decimal type.




The encrypted values are stored in an external file Parameters for F_GetEncFldMask function:




Return value:


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



Crypto Complete


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 Index number parameter is passed in as a Character type.




The encrypted values are stored in an external file Parameters for F_GetEncFldMaskChr function:




Return value:


Plain value (masked) VarChar 32624

SQL Example:


Return as a masked value in the derived field of Masked_CreditCard */

SELECT F_GetEncFldMaskChr(‘CCFIELD’, CreditCard)as Masked_CreditCard


Crypto Complete


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 encrypted values are stored in an external file Parameters for F_GetEncFldAuth function:




Return value:


Output value VarChar 32

SQL Example:


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



Crypto Complete


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 encrypted values are stored in an external file Parameters for F_GetEncFldAuthChr function:




Return value:


Output value Char 32624

SQL Example:


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



Crypto Complete


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:


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:


Cipher Text (encrypted value) Char 32624

Parameter Notes:




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’)


Crypto Complete


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:


Cipher Text (encrypted value) Char 32624

Cipher Text Length Integer 10,0



Key Label Char 30

Return value:



Parameter Notes:




SQL Example:

/* Decrypt a credit card number using the Key Label CREDIT_CARD_KEY in the


SELECT F_DecAES2(CreditCard, 16, ‘OE_KEYS’, ‘*LIBL’, ‘CREDIT_CARD_KEY’)

as Decrypted_CreditCard


Crypto Complete


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:



Plain Text Length Integer 10,0



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:



Parameter Notes:






5 Block length:






Crypto Complete


7 Output Type valid values are *EBCDIC and *ASCII. If none is specified, then the default value of


8 Output Format valid values are *CHAR, *HEX and *BASE64. If none is specified, then the default

value of *CHAR will be used.


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


UPDATE OrderFile

SET CreditCard =

F_EncAdv(CreditCard, 16, ‘OE_KEYS’, ‘*LIBL’, ‘CREDIT_CARD_KEY’,

‘Log Comment’, ‘*AES256’, ‘0’, 16, ‘0’, ‘’,

‘*EBCDIC’, ‘*CHAR’, ‘’)


Crypto Complete


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:



Encrypted Text Length Integer 10,0

Input Type 1 Char 7

Input Format 2 Char 7



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:



Parameter Notes:

1 Input Type valid values are *EBCDIC and *ASCII. If none is specified, then the default value of


2 Input Format valid values are *CHAR, *HEX and *BASE64. If none is specified, then the default

value of *CHAR will be used.






7 Block length:



Crypto Complete






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


SELECT F_DecAdv(CreditCard, 16, ‘*EBCDIC’, ‘*CHAR’, ‘OE_KEYS’, ‘*LIBL’,

‘CREDIT_CARD_KEY’, ‘Log Comment’, ‘*AES256’, ‘0’, 16,

‘0’, ‘’, ‘’)

as Decrypted_CreditCard


Crypto Complete


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


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 encrypted values are not stored in an external file Parameters for P_EncFld stored procedure:


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


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.


This stored procedure should only be used if all of the following conditions are met:


The encrypted values are not stored in an external file Parameters for P_DecFld stored procedure:



CipherText Encrypted Text Char 32624 In Yes


PlainText Plain Text Char 32624 Out




Crypto Complete


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 encrypted values are not stored in an external file Parameters for P_DecFldMask stored procedure:





PlainText Plain Text (masked) Char 32624 Out





Crypto Complete


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 encrypted values are not stored in an external file Parameters for P_DecFldAuth stored procedure:





OutputText Output Text Char 32624 Out





Crypto Complete


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 encrypted values are stored in an external file Parameters for P_InsEncFld stored procedure:





ExtIndex Index number of value Decimal 13,0 Out




Crypto Complete


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 encrypted values are stored in an external file Parameters for P_UpdEncFld stored procedure:



ExtIndex Index number of value Decimal 13,0 In Yes



RtnIndex Return Index number Decimal 13,0 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


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 encrypted values are stored in an external file Parameters for P_DltEncFld stored procedure:







Crypto Complete


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 encrypted values are stored in an external file Parameters for P_GetEncFld stored procedure:









Crypto Complete


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 encrypted values are stored in an external file Parameters for P_GetEncFldMask stored procedure:





PlainText Plain Text (masked value) Char 32624 Out





Crypto Complete


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:





OutputText Output Text Char 32624 Out





Crypto Complete


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:


FldId Field Identifier Char 30 In Yes


ExtIndex Index of Value Decimal 13,0 Out



Errors Errors Char 1 Out

Crypto Complete


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:



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



CipherTextLen Encrypted Text Length 3 Decimal 5,0 Out




Parameter Notes:







10 bytes 16 bytes

16 bytes 16 bytes

17 bytes 24 bytes

24 bytes 24 bytes

32 bytes 32 bytes

Crypto Complete


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:



CipherTextLen Encrypted Text Length Decimal 5,0 In Yes



KeyLabel Key Label Char 30 In Yes



PlainTextLen Plain Text Length Decimal 5,0 Out




Parameter Notes:




Crypto Complete


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:



PlainTextLen Plain Text Length Decimal 5,0 In Yes



KeyLabel Key Store Label Char 30 In Yes


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


CipherTextLen Encrypted Text Length Decimal 5,0 Out




Parameter Notes:






5 Block length:





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


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.





Additional Notes for P_EncAdv:



10 bytes 16 bytes

16 bytes 16 bytes

17 bytes 24 bytes

24 bytes 24 bytes

32 bytes 32 bytes




5 bytes 8 bytes

8 bytes 8 bytes

9 bytes 16 bytes

16 bytes 16 bytes

Crypto Complete


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:



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



KeyLabel Key Store Label Char 30 In Yes


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


PlainTextLen Plain Text Length Decimal 5,0 Out




Parameter Notes:




*CHAR will be used.






7 Block length:



Crypto Complete






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


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


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


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

mailto:[email protected]

mailto:[email protected]

http://www.linomasoftware.com/

Polaris

Att_contacto

programmers guide - att.esatt.es/archivos/cryptocomplete_programmersguide_3_50.pdf · this...

Documents