Rewrapping DES key token values in the CKDS using the utility program CSFCNV2

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

Note: You can also use the CSFCNV2 utility to convert a fixed-length record format CKDS to a variable-length record format. For more information on this capability of the CSFCNV2 utility, refer to z/OS Cryptographic Services ICSF System Programmer's Guide.

As described in DES key wrapping, there are three methods for wrapping the key value in a DES key token. The original method encrypts DES tokens using triple DES encryption. The enhanced wrapping method is ANSI X9.24 compliant, bundles the keys with other token data and encrypts the keys and associated data using triple DES encryption.

The third method is similar to the enhanced method, but uses SHA-256 hashing instead of SHA-1 and was introduced in HCR77C1 by APAR OA55184. Triple-length DES keys are always wrapped with the SHA-256 enhanced wrapping method. When CKDS is processed to change the wrapping method, triple-length keys are not affected except triple-length DATA keys with a zero control vector.

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 or new server.

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 SHA-1 based 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 cannot 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
36020
Input CKDS is empty or not initialized (authentication pattern in the control record is invalid).
36068
The input KDS is not enciphered under the current master key.
36104
Option not available. There were no Cryptographic Coprocessors available to perform the service that was attempted.
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.
Note: It is possible that you will receive MVS reason codes rather than ICSF reason codes, for example, if the reason code indicates a dynamic allocation failure. For an explanation of Dynamic Allocation reason codes, see z/OS MVS Programming: Authorized Assembler Services Guide