IBM dropped support of IBM® Cryptographic Support for AS/400® (5722-CR1)
in V6R1. This topic helps you migrate your CR1 applications
to the Cryptographic Services APIs.
Before reading this topic, you might want to review the information in
the following topics:
This topic contains many references to Cryptographic Services APIs. Note that in V6R1 all the key management functions can be accomplished not only through the Cryptographic Services APIs, but also through the Cryptographic Services set of CL commands, and through the Cryptographic Services Key Management function in IBM Systems Director Navigator for IBM i.
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 Support/400 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 Cryptographic Coprocessor.
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 general-purpose master keys.
CR1 supports one keystore file, QCRP/QACRKTBL, also known as the cross-domain
key table.
With the Cryptographic
Services APIs, the user can create any number of keystore 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 keystore 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 keystore file.
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.
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 keystore 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 keystore file, you would specify
the Create Key Context parameters as follows:
The key string parameter would contain the keystore label structure as
described in the API.
The length of key string parameter would specify 56, which is the length
of the keystore label structure.
The key format parameter would specify a value of 4 to indicate it is a
keystore label structure.
The key type and key form parameters would not change.
Follow the API instructions for the remaining parameters.
Erase the master key value, the three new key values, and any key part values
from program storage.
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.
Read each record of the cross-domain key table and import the key value
to your keystore 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 keystore 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 keystore 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.
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.
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 keystore 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 keystore file, you would specify
the Create Key Context parameters as follows:
The key string parameter would contain the keystore label structure as
described in the API.
The length of key string parameter would specify 56, which is the length
of the keystore label structure.
The key format parameter would specify a value of 4 to indicate it is a
keystore label structure.
The key type and key form parameters would not change.
Follow the API instructions for the remaining parameters.
Erase the master key value and any key part values from program storage.
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.
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.
Whereas CR1 supports one keystore file which is shipped with the product,
the Cryptographic Services APIs user must create a keystore file.
Cryptographic Services APIs keystore 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.
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 keystore 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.
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.
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.
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 keystore 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)
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 keystore 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.
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.
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 keystore 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.
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.
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
Cryptographic Coprocessors.
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 keystore files are created with no capabilities.
You can not modify a keystore file using other APIs. To remove all records from
the keystore file, you must delete the file and then recreate it.
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
Cryptographic Coprocessors.
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.
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
Cryptographic Coprocessors.