Migrating from 57xx-CR1

IBM plans to drop support of IBM Cryptographic Support for AS/400 (5722-CR1) in the release after V5R4. This article will help you migrate your CR1 applications to the Cryptographic Services APIs.

Prior to reading this article, you may want to review the information in the following articles:

• Cryptography Concepts
• Cryptographic Services Master Keys
• Cryptographic Services Key Store

General Functional Differences

• PIN functions
  The Cryptographic Services APIs do not support the CR1 PIN functions. CR1 supports the 3624 PIN calculation method. It is possible to code the 3624 PIN calculation method using the Cryptographic Services APIs. To do so, implement the "PIN Generation Algorithm" described in Chapter 4 of the Cryptographic User's Guide, replacing the CR1 APIs with Cryptographic Services APIs as described below. However, a better solution would be to use a cryptographic coprocessor and the Common Cryptographic Architecture API set, which supports many PIN calculation methods and PIN block formats. For more information, see 4764 and 4758 Cryptographic Coprocessors.
  
  
• Key management
  Both CR1 and the Cryptographic Services APIs implement key management using a key hierarchy. At the top, a clear master key is securely stored. Other keys can be stored in a database file where the key values are encrypted under the master key. However, note the following differences in key management between CR1 and the Cryptographic Services APIs:
  
  
  • CR1 supports one master key.

    The Cryptographic Services APIs support eight master keys.

  • CR1 supports one key store file, QCRP/QACRKTBL, also known as the cross-domain key table.

    With the Cryptographic Services APIs, the user can create any number of key store files.

  • CR1 defines key-encrypting keys (KEKs) as those keys stored within the cross-domain key table as sending and receiving cross-domain key types. They are limited to export (encrypting keys to send to another system) and import (decrypting keys received from another system) operations. The user is responsible for storing data-encrypting keys.

    The Cryptographic Services APIs do not distinguish between key-encrypting keys and data-encrypting keys. It is up to the user to define what keys are used as key-encrypting keys and as data-encrypting keys.

  • Only keys for export, import, and PIN protection operations can be stored in the CR1 cross-domain key table.

    Any type of key can be stored in a Cryptographic Services APIs key store file.

  
  
• Master key variants
  Master key variants are values that are exclusive-OR'd into the master key value prior to encrypting or decrypting a key. Master key variants are used to limit how the encrypted key can be used. Both CR1 and the Cryptographic Services APIs use master key variants. However, the values of the variants and how they are used are completely different.

  CR1 uses master key variants to limit cross-domain keys to either export, import, or PIN protection operations. The CR1 master key variants are the following:

  Sending cross-domain key	Eight bytes of hexadecimal 88.
  Receiving cross-domain key	Eight bytes of hexadecimal 22.
  PIN cross-domain key	Eight bytes of hexadecimal 44.

  Cryptographic Services APIs use master key variants to limit master key encrypted keys to any combination of encrypt, decrypt, MAC, and sign operations.

Migrating Keys

If you have not already established a Cryptographic Services APIs master key, do so using the Load Master Key Part and Set Master Key APIs.

Write a program that performs the following steps to migrate your keys from the CR1 cross-domain key table to a Cryptographic Services APIs key store file.

1. Create a key store file using the Create Key Store API.
   
   
2. Get the CR1 master key value.
   • You should not hard-code the CR1 master key value in your program, but instead request the input interactively.
   • If the CR1 master key was established using multiple key parts, you should maintain multiple responsibility and request input of multiple key parts. Your program would then exclusive-OR those parts together to obtain the master key value.
   
   
3. Create a key context token for each variant of the CR1 master key.
   • Create three new key values by exclusive-ORing the master key value with each variant value (as described above). For example, a master key value of hex 3BA93722AF8D0526 exclusive-OR'd with the sending cross-domain key variant (hex 8888888888888888) would be hex B321BFAA27058DAE.
   • If you will be migrating more CR1 cross-domain keys in the future, save all three key values to your key store file. Do this using the Write Key Record API.
     • The key string parameter should contain the key value (for example, hex B321BFAA27058DAE).
     • The length of key string parameter should specify a value of 8.
     • The key format parameter should specify a value of 0 to indicate it is a binary value.
     • The key type parameter should specify a value of 20 to indicate it is a DES key.
     • The key form parameter should specify a value of 0 to indicate the key value is not encrypted.
     • Follow the API instructions for the remaining parameters.
   • Create a key context for each of the three values using the Create Key Context API. The key string, length of key string, key format, key type, and key form parameters should all match what was specified above for the Write Key Record API. If in the future you retrieve these key values from the key store file, you would specify the Create Key Context parameters as follows:
     • The key string parameter would contain the key store label structure as described in the API.
     • The length of key string parameter would specify 56, which is the length of the key store label structure.
     • The key format parameter would specify a value of 4 to indicate it is a key store label structure.
     • The key type and key form parameters would not change.
     • Follow the API instructions for the remaining parameters.
   
   
4. Erase the master key value, the three new key values, and any key part values from program storage.
   
   
5. Create a DES algorithm context token using the Create Algorithm Context API.
   • The algorithm description format name parameter should specify a value of "ALGD0200".
   • The algorithm description parameter should contain the ALGD0200 structure. The entire ALGD0200 structure should be set to null. The fields should then be specified as follows:
     • The block cipher algorithm field should specify a value of 20 to indicate the DES algorithm.
     • The block length field should specify a value of 8.
   • Follow the API instructions for the remaining parameters.
   
   
6. Read each record of the cross-domain key table and import the key value to your key store file.
   • The format of a cross-domain key table record is as follows:

     Field	Length
     Key Label	10
     Key Type	1
     Encrypted Key Value	8

     A key type of "S" indicates the key is a sending cross-domain key. A key type of "R" indicates the key is a receiving cross-domain key. A key type of "P" indicates the key is a PIN key.

   • Use the Write Key Record API to import the key value to the key store file.
     • For the record label parameter, you should be able to use the same value as the label from the cross-domain key table record unless a key record by that label already exists in the key store file.
     • The key string parameter should contain the encrypted key value.
     • The length of key string parameter should specify a value of 8.
     • The key format parameter should specify a value of 0 to indicate it is a binary value.
     • The key type parameter should specify a value of 20 to indicate it is a DES key.
     • The key form parameter should specify a value of 1 to indicate the key value is encrypted.
     • The key-encrypting key context token parameter should specify the appropriate key context token created in step 3 above. Use the key type field of the cross-domain key record to determine which token to use.
     • The key-encrypting algorithm context token should specify the algorithm context token created in step 5 above.
     • Follow the API instructions for the remaining parameters.

To migrate CR1 master key encrypted keys not stored in the cross-domain key table, your program should perform the following steps.

1. Get the CR1 master key value.
   • You should not hard-code the CR1 master key value in your program, but instead request the input interactively.
   • If the CR1 master key was established using multiple key parts, you should maintain multiple responsibility and request input of multiple key parts. Your program would then exclusive-OR those parts together to obtain the master key value.
   
   
2. Create a key context token for the CR1 master key.
   • If you will be migrating more CR1 keys in the future, save the master key to a key store file. Do this using the Write Key Record API.
     • The key string parameter should contain the master key value.
     • The length of key string parameter should specify a value of 8.
     • The key format parameter should specify a value of 0 to indicate it is a binary value.
     • The key type parameter should specify a value of 20 to indicate it is a DES key.
     • The key form parameter should specify a value of 0 to indicate the key value is not encrypted.
     • Follow the API instructions for the remaining parameters.
   • Create a key context for the CR1 master key value using the Create Key Context API. The key string, length of key string, key format, key type, and key form parameters should all match what was specified above for the Write Key Record API. If in the future you retrieve the CR1 master key value from the key store file, you would specify the Create Key Context parameters as follows:
     • The key string parameter would contain the key store label structure as described in the API.
     • The length of key string parameter would specify 56, which is the length of the key store label structure.
     • The key format parameter would specify a value of 4 to indicate it is a key store label structure.
     • The key type and key form parameters would not change.
     • Follow the API instructions for the remaining parameters.
   
   
3. Erase the master key value and any key part values from program storage.
   
   
4. Create a DES algorithm context token using the Create Algorithm Context API.
   • The algorithm description format name parameter should specify a value of "ALGD0200".
   • The algorithm description parameter should contain the ALGD0200 structure. The entire ALGD0200 structure should be set to null. The fields should then be specified as follows:
     • The block cipher algorithm field should specify a value of 20 to indicate the DES algorithm.
     • The block length field should specify a value of 8.
   • Follow the API instructions for the remaining parameters.
   
   
5. Import the CR1 master key encrypted keys.

   For each CR1 master key encrypted key, use the Import Key API to re-encrypt the key under a Cryptographic Services APIs master key.

   • The key string parameter should contain the encrypted key value.
   • The length of key string parameter should specify a value of 8.
   • The key form parameter should specify a value of 1 to indicate the key value is encrypted.
   • The key-encrypting key context token parameter should specify the key context token created in step 2 above.
   • The key-encrypting algorithm context token should specify the algorithm context token created in step 4 above.
   • Follow the API instructions for the remaining parameters.

Migrating Programs

Use the following list to determine how to replace CR1 APIs with Cryptographic Services APIs.

Add Cross-Domain Key (CL, ADDCRSDMNK)

Replace with

• Create Key Store (OPM, QC3CRTKS; ILE, Qc3CreateKeyStore)
• Write Key Record (OPM, QC3WRTKR; ILE, Qc3WriteKeyRecord)

Notes:

• Whereas CR1 supports one key store file which is shipped with the product, the Cryptographic Services APIs user must create a key store file.
• Cryptographic Services APIs key store keys can not be restricted to export, import, and PIN protection functions as is done with CR1. However, they can be restricted to any combination of encrypt, decrypt, MAC, and sign operations.

Change Cross-Domain Key (CL, CHGCRSDMNK)

Replace with

• Delete Key Record (OPM, QC3DLTKR; ILE, Qc3DeleteKeyRecord)
• Write Key Record (OPM, QC3WRTKR; ILE, Qc3WriteKeyRecord)

Notes:

• There is no Cryptographic Services API to change a key record. The application must first delete the record and then re-create it.
• Cryptographic Services APIs key store keys can not be restricted to export, import, and PIN protection functions as is done with CR1. However, they can be restricted to any combination of encrypt, decrypt, MAC, and sign operations.

Change Master Key (CL, CHGMSTKK)

Replace with

• Test Master Key (OPM, QC3TSTMK; ILE, Qc3TestMasterKey)
• Load Master Key Part (OPM, QC3LDMKP; ILE, Qc3LoadMasterKeyPart)
• Set Master Key (OPM, QC3SETMK; ILE, Qc3SetMasterKey)

Notes:

• The CR1 Change Master Key API requires knowledge of the master key verification code. The Cryptographic Services APIs application program can implement this function using the Test Master Key API.

Cipher Data (CL, CPHDTA; OPM, QCRCIPHR)

Replace with

• Encrypt Data (OPM, QC3ENCDT; ILE, Qc3EncryptData)

Notes:

• OPTION(*SCPH) is not supported by the Cryptographic Services APIs. Your application program must convert the 16 hexadecimal characters to the 8-byte binary value prior to calling the Encrypt Data API. Similarly, if a 16 hexadecimal character output is desired, the application program must do the conversion.
• To duplicate the function of Cipher Data, the Encrypt Data API should specify an algorithm description for DES. However, it is recommended that you upgrade the security of your application by moving to a newer algorithm such as TDES or the better performing AES.

Encrypt Cipher Key (CL, ENCCPHK; OPM, QCRENCKY)

Replace with

• Import Key (OPM, QC3IMPKY; ILE, Qc3ImportKey)

Encipher From Master Key (CL, ENCFRMMSTK; OPM, QCRENCFR)

Replace with

• Create Key Context (OPM, QC3CRTKX; ILE, Qc3CreateKeyContext)
• Create Algorithm Context (OPM, QC3CRTAX; ILE, Qc3CreateAlgorithmContext)
• Export Key (OPM, QC3EXPKY; ILE, Qc3ExportKey)

Notes:

• The Export Key API requires a key context be created for the key-encrypting key. It is on the Create Key Context API that you specify the key store file and label.
• The Export Key API also requires an algorithm context. To duplicate the function of Encipher From Master Key, create a DES algorithm context. The algorithm description should specify ECB mode and no padding.
• The Export Key API does not support the output of two encrypted key values as does Encipher From Master Key. To obtain a second encrypted key value, create another key context and issue the Export Key API again. You may reuse the same algorithm context.

Encipher To Master Key (CL, ENCTOMSTK; OPM, QCRENCTO)

Replace with

• Create Key Context (OPM, QC3CRTKX; ILE, Qc3CreateKeyContext)
• Create Algorithm Context (OPM, QC3CRTAX; ILE, Qc3CreateAlgorithmContext)
• Import Key (OPM, QC3IMPKY; ILE, Qc3ImportKey)

Notes:

• When importing an encrypted key, the Import Key API requires a key context be created for the key-encrypting key. It is on the Create Key Context API that you specify the key store file and label.
• Importing an encrypted key also requires an algorithm context. To duplicate the function of Encipher To Master Key, create a DES algorithm context. The algorithm description should specify ECB mode and no padding.

Generate Cipher Key (CL, GENCPHK; OPM, QCRGENKY)

Replace with

• Generate Symmetric Key (OPM, QC3GENSK; ILE, Qc3GenSymmetricKey)
• Create Key Context (OPM, QC3CRTKX; ILE, Qc3CreateKeyContext)
• Create Algorithm Context (OPM, QC3CRTAX; ILE, Qc3CreateAlgorithmContext)
• Export Key (OPM, QC3EXPKY; ILE, Qc3ExportKey)

Notes:

• The Generate Symmetric Key API will generate a random key value and return it in the clear, encrypted under a master key, or encrypted under a key-encrypting key. If both a master key encrypted form and a KEK encrypted form is required, first use Generate Symmetric Key API to generate a key encrypted under a master key. Then follow the same procedures outlined for Encipher From Master Key.

Generate Cross-Domain Key (CL, GENCRSDMNK)

Replace with

• Add Seed for Pseudorandom Number Generator (OPM, QC3ADDSD; ILE, Qc3AddPRNGSeed)
• Generate Key Record (OPM, QC3GENKR; ILE, Qc3GenKeyRecord)

Notes:

• The Generate Key Record API does not require a seed value because it uses the system's pseudorandom number generator which automatically seeds. However, if your security practices require the input of seed data, first use the Add Seed for Pseudorandom Number Generator API.
• The Generate Key Record API generates a single key record. To generate multiple key records, invoke this API multiple times.
• Cryptographic Services APIs key store keys can not be restricted to export, import, and PIN protection functions as is done with CR1. However, they can be restricted to any combination of encrypt, decrypt, MAC, and sign operations.

Generate Message Authentication Code (CL, GENMAC; OPM, QCRGENMA)

Replace with

• Calculate MAC (OPM, QC3CALMA; ILE, Qc3CalculateMAC)

Notes:

• To duplicate the function of Generate Message Authentication Code, the Calculate MAC API should specify an algorithm description for DES. However, it is recommended that you upgrade the security of your application by moving to a newer algorithm such as TDES or the better performing AES.

Generate PIN (CL, GENPIN; OPM, QCRGENPN)

Replace with

• Encrypt Data (OPM, QC3ENCDT; ILE, Qc3EncryptData)

Notes:

• Although the Cryptographic Services APIs do not support PIN functions, it is possible for your application to implement the 3624 PIN generation algorithm. The Encrypt Data API would be used for encrypting the PIN validation data.
• The PIN validation data must be presented to the Encrypt Data API as an 8-byte value. Your application program may need to convert the 8-byte encrypted value to 16 hexadecimal characters prior to decimalization. Refer to the "PIN Generation Algorithm" described in Chapter 4 of the Cryptographic User's Guide.
• There are a number of security issues involved in supporting PIN functions with the Cryptographic Services APIs. A better solution would be to use a cryptographic coprocessor and the Common Cryptographic Architecture API set. For more information, see 4764 and 4758 Cryptographic Coprocessors.

Remove Cross-Domain Key (CL, RMVCRSDMNK)

Replace with

• Delete Key Record (OPM, QC3DLTKR; ILE, Qc3DeleteKeyRecord)

Notes:

• The Delete Key Record API deletes a single key record. To delete multiple key records, you must invoke this API multiple times.
• Cryptographic Services APIs key store files are created with no capabilities. You can not modify a key store file using other APIs. To remove all records from the key store file, you must delete the file and then recreate it.

Set Master Key (CL, SETMSTK)

Replace with

• Load Master Key Part (OPM, QC3LDMKP; ILE, Qc3LoadMasterKeyPart)
• Set Master Key (OPM, QC3SETMK; ILE, Qc3SetMasterKey)

Translate PIN (CL, TRNPIN; OPM, QCRTRNPN)

Replace with

• Create Key Context (OPM, QC3CRTKX; ILE, Qc3CreateKeyContext)
• Create Algorithm Context (OPM, QC3CRTAX; ILE, Qc3CreateAlgorithmContext)
• Translate Data (OPM, QC3TRNDT; ILE, Qc3TranslateData)

Notes:

• Although the Cryptographic Services APIs do not support PIN functions, it is possible to translate a PIN using the Translate Data API.
• The Translate Data API does not support the specification of 16 hexadecimal characters for the encrypted PIN number. You must supply it as an 8-byte value.
• There are a number of security issues involved in supporting PIN functions with the Cryptographic Services APIs. A better solution would be to use a cryptographic coprocessor and the Common Cryptographic Architecture API set. For more information, see 4764 and 4758 Cryptographic Coprocessors.

Verify Master Key (CL, VFYMSTK)

Replace with

• Test Master Key (OPM, QC3TSTMK; ILE, Qc3TestMasterKey)

Notes:

• The Verify Master Key CL command compares the input verification code against the master key verification code. The Test Master Key API just returns the master key verification code. Therefore, your application program must do the comparison.

Verify PIN (CL, VFYPIN; OPM, QCRVFYPN)

Replace with

• Encrypt Data (OPM, QC3ENCDT; ILE, Qc3EncryptData)
• Decrypt Data (OPM, QC3DECDT; ILE, Qc3DecryptData)

Notes:

• Although the Cryptographic Services APIs do not support PIN functions, it is possible for your application to implement the 3624 PIN generation algorithm. The Encrypt Data API would be used for encrypting the PIN validation data. The Decrypt Data API would be used to decrypt the PIN prior to the comparison.
• The encrypted PIN value must be presented to the Decrypt Data API as an 8-byte value. The PIN validation data must be presented to the Encrypt Data API as an 8-byte value. Your application program may need to convert the output from Encrypt Data to 16 hexadecimal characters prior to decimalization. Refer to the "PIN Generation Algorithm" described in Chapter 4 of the Cryptographic User's Guide.
• There are a number of security issues involved in supporting PIN functions with the Cryptographic Services APIs. A better solution would be to use a cryptographic coprocessor and the Common Cryptographic Architecture API set. For more information, see 4764 and 4758 Cryptographic Coprocessors.