ICSF provides a utility program, CSFCNV2, that will rewrap all encrypted DES tokens in the CKDS.

As described in DES key wrapping, there are two methods for wrapping the key value in a DES key token. The original method encrypts DES tokens using triple DES encryption. An enhanced wrapping method, introduced in FMID HCR7780 and designed to be ANSI X9.24 compliant, bundles the keys with other token data and encrypts the keys and associated data using triple DES encryption.

Using the CSFCNV2 utility, you can rewrap all encrypted key tokens in the CKDS using the enhanced or the original method. The results will be written to a new CKDS.

There is no panel interface for this utility. It can be invoked as a batch job and requires a z196 with a CEX3C.

To rewrap encrypted key tokens in an existing CKDS and write the results to a new CKDS, use the following JCL code as an example:

//STEP EXEC PGM=CSFCNV2,PARM='WRAP-xxx,OLD.CKDS,NEW.CKDS'

Where:

WRAP-xxx

Specifies the wrapping method to use.

WRAP-ECB

The original wrapping method. If you specify this option, be aware that the access control point “CKDS Conversion2 utility - Convert from enhanced to original” must be enabled. This access control point is not enabled in the ICSF coprocessor role. It can only be enabled using TKE.

WRAP-ENH

The enhanced wrapping method.

ENH-ONLY

The enhanced wrapping method will be used and the control vector in tokens will be updated to indicate that token can not be rewrapped to the original method.

OLD.CKDS

The name of the disk copy of the CKDS to process.

NEW.CKDS

The name of an empty disk copy of the CKDS to contain the rewrapped keys.

The CSFV0560 message in the joblog will indicate the results of processing.

Return Code

Meaning

0

Process successful.

4

Minor error occurred.

8

RACF authorization check failed.

12

Process unsuccessful.

60 or 92

CKDS processing has failed. A return code 60 indicates the error was detected in the new KDS. A return code 92 indicates the error was detected with the old KDS.

When the program is invoked from another program, the invoking program receives the reason code in General Register 0 along with the return code in General Register 15. The following list describes the meaning of the reason codes. If a particular reason code is not listed, refer to the listing of ICSF and TSS return and reason codes in the z/OS Cryptographic Services ICSF Application Programmer’s Guide.

Return code 0 has this reason code:

Reason Code

Meaning

36132

CKDS reencipher/Change MK processed only tokens encrypted under the DES master key.

Return code 4 has these reason codes:

Reason Code

Meaning

0

Parameters are incorrect.

4004

Rewrapping is not allowed for one or more keys.

36112

CKDS conversion completed successfully but some tokens could not be rewrapped because the control vector prohibited rewrapping from the enhanced wrapping method.

36164

Input CKDS is already in the variable-length record format. No conversion is necessary.

Return code 8 has this reason code:

Reason Code

Meaning

16000

Invoker has insufficient RACF access authority to perform function.

Return code 12 has these reason codes:

Reason Code

Meaning

0

ICSF has not been started

11060

The required cryptographic coprocessor was not active or the master key has not been set

36000

Unable to change master key. Check hardware status.

36008

Crypto master key register(s) in improper state.

36020

Input CKDS is empty or not initialized (authentication pattern in the control record is invalid).

36036

The new master key register for Coprocessor 1 (C1) is not full, but C0 is ready and the current master key is valid.

36040

The new master key register for C0 is not full, but C1 is ready and the current master key is valid.

36044

The master key authentication pattern for the CKDS does not match the authentication pattern of the coprocessors, which are not equal.

36048

The master key authentication pattern for the CKDS does not match the authentication pattern of either of the coprocessors, which are not equal.

36052

A valid new master key is present in C0, but its authentication pattern does not match that of C1 or the CKDS, which are equal.

36056

A valid new master key is present in C1, but its authentication pattern does not match that of C0 or the CKDS, which are equal.

36060

The new master key register(s) is/are not full.

36064

Both new master key registers are full but not equal.

36068

The input KDS is not enciphered under the current master key.

36076

The new master key register for C0 is not full, but the CPUs are online.

36080

The new master key register for C1 is not full, but the CPUs are online.

36084

The master key register cannot be changed since ICSF is running in compatibility mode.

36104

Option not available. There were no Cryptographic Coprocessors available to perform the service that was attempted.

36108

PKA callable services are enabled, and the PKDS is the active PKDS as specified in the options data set.

36120

The CKDS is unusable. The CKDS does not support record level authentication.

36124

The CKDS is unusable. The CKDS only supports encrypted AES keys and encrypted DES support is required.

36128

The CKDS is unusable. The CKDS does not support encrypted DES keys which is required.

36160

The attempt to reencipher the CKDS failed because there is an enhanced token in the CKDS.

36168

A CKDS has an invalid LRECL value for the requested function. For wrapping, the input and output CKDS LRECLs must be the same.

36172

The level of hardware required to perform the operation is not available.

Return code 60 or 92 has these reason codes:

Reason Code

Meaning

3078

The CKDS was created with an unsupported LRECL.

5896

The CKDS does not exist.

6008

A service routine has failed.

The service routines that may be called are:

CSFMGN

MAC generation

CSFMVR

MAC verification

CSFMKVR

Master key verification

6012

The single-record, read-write installation exit (CSFSRRW) returned a return code greater than 4.

6016

An I/O error occurred reading or writing the CKDS.

6020

The CSFSRRW installation exit abended and the installation options EXIT keyword specifies that the invoking service should end.

6024

The CSFSRRW installation exit abended and the installation options EXIT keyword specifies that ICSF should end.

6028

The CKDS access routine could not establish the ESTAE environment.

6040

The CSFSRRW installation exit could not be loaded and is required.

6044

Information necessary to set up CSFSRRW installation exit processing could not be obtained.

6048

The system keys cannot be found while attempting to write a complete CKDS data set.

6052

For a write CKDS record request, the current master key verification pattern (MKVP) does not match the CKDS header record MKVP.

6056

The output CKDS is not empty.