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