You can run the conversion program only after you initialize the master key and CKDS for ICSF. The CKDS you specify at ICSF startup must be initialized to contain NOCV-enablement keys. For information about defining keys on ICSF, see z/OS Cryptographic Services ICSF Administrator’s Guide.

If the PCF master key and the ICSF master key are not the same, you must define the PCF master key in the input ICSF CKDS. Define the PCF master key as an importer key-encrypting key in the input ICSF CKDS. You define the key by entering the key through the key entry hardware, or by importing the key using the ICSF key generator utility program. For information about direct key entry through the key entry hardware and the key generator utility program, see z/OS Cryptographic Services ICSF Administrator’s Guide.

You run the conversion program by submitting a batch job. On the EXEC statement, specify PGM=CSFCONV. If the PCF master key and ICSF master key are not the same in the PARM= field on the EXEC statement, specify the label of the PCF master key entry in the input ICSF CKDS. If you do not specify the parameter, the conversion program assumes that the PCF master key and ICSF master key are the same.

This example is a JCL that runs the conversion program:

   //CKDSCONV EXEC PGM=CSFCONV,PARM='CUSPMKEY'
   //CSFVSRC  DD   DSN=PROD.CUSP.CKDS,DISP=SHR
   //CSFVINP  DD   DSN=TEST.CSF.CKDS,DISP=SHR
   //CSFVOVR  DD   DSN=OVERRIDE.DATA,DISP=OLD
   //CSFVNEW  DD   DSN=MERGED.CSF.CKDS,DISP=OLD
   //CSFVRPT  DD   SYSOUT=A
   //

In the example, CUSPMKEY is the label of the entry in the input ICSF CKDS for the PCF master key in importer key-encrypting key form. All the data sets necessary to run the conversion program are specified using DD statements.

The conversion program uses these data sets:

CSFVSRC

The PCF CKDS containing entries that you want to convert into ICSF format and place in the output ICSF CKDS. This is the source CKDS for the conversion. For a description of the PCF CKDS record format, see OS/VS1 and OS/VS2 MVS Programmed Cryptographic Facility.

CSFVINP

A disk copy of the input ICSF CKDS. The input CKDS should already contain the header record and the ICSF system keys and can contain other ICSF key entries. If the CKDS does not contain NOCV-enablement keys, the output ICSF CKDS will not contain NOCV-enablement keys. For more information about NOCV-enablement keys, see z/OS Cryptographic Services ICSF Administrator’s Guide.

Note:

The input ICSF CKDS does not have to be the CKDS you specify when you start ICSF.

CSFVOVR

The override file with information specifying how you want the conversion program to process PCF key entries. If no override data is required, this data set is optional. However, you must code a dummy DD statement in the JCL.

This JCL is an example of a dummy DD statement for an override file:

   //CSFVOVR DD DUMMY,DCB=(RECFM=FB,LRECL=90,BLKSIZE=3600)

See Using the conversion program override file for a description of when and how to use the override file.

CSFVNEW

An empty disk copy of an ICSF CKDS. This is the ICSF CKDS into which the conversion program places key entries. The conversion program places key entries from the input ICSF CKDS and the PCF CKDS into the output ICSF CKDS. The data set must be defined and empty before you run the conversion program.

CSFVRPT

The activity report that the conversion program creates. The report describes any override records and gives a summary of CKDS entries that were affected by the conversion program.

When you run the conversion program, the program produces information about the conversion in an activity report. The activity report lists each override entry, the action each override entry applies to the input PCF CKDS, and any error messages. The activity report also lists the data sets that were used in the conversion and a summary of processing. The summary of processing contains totals that apply to CKDS entries in the conversion program job.

Example of a Conversion Initial Activity Report

Figure 11 is an example of an activity report with five explicit override records and no global override records.

CRYPTOGRAPHIC CONVERSION ACTIVITY REPORT                 DATE: 2001/06/01 (YYYY/MM/DD) TIME: 10:13:09 PAGE: 1
 OVERRIDE--> CRLABEL3 LOCAL    OPINENC             Used in transfers to Main Office.
 >>>CSFV0192 TYPE FOR KEY ENTRY CRLABEL3 LOCAL CONVERTED TO OPINENC.
 >>>CSFV0232 INSTALLATION DATA FOR KEY ENTRY CRLABEL3 OPINENC SET TO Used in transfers to Main Office

 OVERRIDE--> CRLABEL3 REMOTE   IPINENC             Used in receiving from the Main Office
 >>>CSFV0192 TYPE FOR KEY ENTRY CRLABEL3 REMOTE CONVERTED TO IPINENC.
 >>>CSFV0232 INSTALLATION DATA FOR KEY ENTRY CRLABEL3 IPINENC SET TO Used in receiving from the Main Office.

 OVERRIDE--> KGLABEL1 LOCAL    OPINENC             Used for sending encrypted PINs
 >>>CSFV0292 NO KEY ENTRY FOUND FOR KGLABEL1 LOCAL.


 OVERRIDE--> LOLABEL2                             Valid for January 2001
 >>>CSFV0232 INSTALLATION DATA FOR KEY ENTRY LOLABEL2 EXPORTER SET TO Valid for January 2001.

 OVERRIDE--> ZZZZ1    LOCAL                      Y Eliminate Key from output CKDS
 >>>CSFV0382 ADD/CHANGE SPECIFICATIONS IGNORED ON OVERRIDE ENTRY. BYPASS_FLAG VALUE IS "Y".
 >>>CSFV0292 NO KEY ENTRY FOUND FOR ZZZZ1 LOCAL.


 >>>CSFV0012 CONVERSION PROCESSING COMPLETED. RETURN CODE = 4.
 

CRYPTOGRAPHIC CONVERSION ACTIVITY REPORT                 DATE: 2001/06/01 (YYYY/MM/DD) TIME: 10:13:09 PAGE: 2

    CKDS DDNAME     Data Set Name
    ------------    --------------
    CSFVSRC         PROD.CUSP.CKDS
    CSFVINP         TEST.CSF.CKDS
    CSFVNEW         MERGED.CSF.CKDS

    PROCESSING SUMMARY

             Source CKDS Entries               Converted Entries                    ICSF Entries
             --------------------------------  -----------------------------------  -----------------------------------
                LOCAL                      4    * Candidates                   16    + Changed Input Entries         2
                REMOTE                     4      Bypassed by Overrides       ( 0)     Unchanged Input Entries      13
                CROSS                      4                                           --------------------------------
                -----------------------------     --------------------------------     TOTAL ICSF Input Entries     15
              * TOTAL Source Entries      12      TOTAL Converted Entries      16    + Entries Added from Source    14
                                                                                       Entries Bypassed by Exit    ( 0)
                                                                                       --------------------------------
                                                                                       TOTAL Output ICSF Entries    29


  * One Source CKDS CROSS entry converts to two Candidates.
  + Total Converted Entries = Changed Input Entries + Entries Added from Source.
 

In the report, the first override record specifies that when the conversion program converts a PCF entry labeled CRLABEL3 with a key type of local, the program should convert the entry into an output PIN-encrypting key. The conversion program also places the information Used in transfers to Main Office in the installation data field of the output ICSF CKDS entry.

The second override record specifies that when the conversion program converts a PCF entry labeled CRLABEL3 with a key type of remote, the program should convert the key into an input PIN-encrypting key. The conversion program places the information Used in receiving from the Main Office in the installation data field of the output ICSF CKDS entry.

The label specified by the third override record does not exist in the PCF CKDS. Therefore, the conversion program ignores this override record.

The fourth override record specifies that when the conversion program converts a PCF entry labelled LOLABEL2, the program should place the information Valid for January 2001 in the installation data field of the output ICSF CKDS record.

The label specified by the fifth override record does not exist on the PCF CKDS that the conversion program is converting. Therefore, the conversion program ignores this override record.

The message that the conversion processing has been completed is followed by a return code. Return codes are listed under message CSFV0026 in z/OS Cryptographic Services ICSF Messages.

After describing the five override records, the conversion report lists the data sets the conversion program used in the conversion. PROD.CUSP.CKDS is the PCF CKDS that the program converted. TEST.CSF.CKDS is the input ICSF CKDS containing the ICSF entries input during the conversion. MERGED.CSF.CKDS is the output ICSF CKDS where the conversion program placed the converted entries.

Then the activity report lists totals pertaining to the conversion. The PCF CKDS has a total of 12 entries: four with a key type of local, four with a key type of remote, and four with a key type of cross. Because the conversion of each cross key entry results in two ICSF entries, the total ICSF entries that are candidates for conversion from the PCF is 16. None of these candidates was bypassed because of an override record, so 16 PCF entries were converted.

There were 15 entries in the input ICSF CKDS, and two of these entries were updated because they had identical key labels in the PCF CKDS. Fourteen new output ICSF CKDS entries were added from the PCF CKDS. The total number of entries in the output ICSF CKDS is 29. This includes the 15 entries in the input ICSF CKDS and the 14 entries added from the PCF CKDSN. No entries were bypassed because of the conversion program exit.

Example of a Conversion Update Activity Report

Figure 12 is an example of an activity report with a global override record that has the conversion program bypass all the entries in the PCF CKDS. Then two override records are used to convert specific entries.

CRYPTOGRAPHIC CONVERSION ACTIVITY REPORT                 DATE: 2001/06/01 (YYYY/MM/DD) TIME: 10:13:09 PAGE: 1
OVERRIDE-->                                     Y
 >>>CSFV0172 ALL  ENTRIES BYPASSED.

 OVERRIDE--> CRLABEL3 LOCAL    OPINENC             Used in transfers to Main Office
 >>>CSFV0222 KEY ENTRY CRLABEL3 LOCAL NOT BYPASSED.
 >>>CSFV0192 TYPE FOR KEY ENTRY CRLABEL3 LOCAL CONVERTED TO OPINENC.
 >>>CSFV0232 INSTALLATION DATA FOR KEY ENTRY CRLABEL3 OPINENC SET TO Used in transfers to Main Office.

OVERRIDE--> LOLABEL2                             Valid for January 2001
 >>>CSFV0222 KEY ENTRY LOLABEL2 LOCAL NOT BYPASSED.
 >>>CSFV0232 INSTALLATION DATA FOR KEY ENTRY LOLABEL2 EXPORTER SET TO Valid for January 2001.


 >>>CSFV0012 CONVERSION PROCESSING COMPLETED.  RETURN CODE = 0.

 

CRYPTOGRAPHIC CONVERSION ACTIVITY REPORT                 DATE: 2001/06/01 (YYYY/MM/DD) TIME: 10:13:09 PAGE: 2

    CKDS DDNAME     Data Set Name
    ------------    --------------
    CSFVSRC         PROD.PCF.CKDS
    CSFVINP         INTEST.CSF.CKDS
    CSFVNEW         NEWTEST.CSF.CKDS

    PROCESSING SUMMARY

             Source CKDS Entries               Converted Entries                    ICSF Entries
             --------------------------------  -----------------------------------  -----------------------------------
                LOCAL                      4    * Candidates                   16    + Changed Input Entries         1
                REMOTE                     4      Bypassed by Overrides       (14)     Unchanged Input Entries      27
                CROSS                      4                                           --------------------------------
                -----------------------------     --------------------------------     TOTAL ICSF Input Entries     28
              * TOTAL Source Entries      12      TOTAL Converted Entries       2    + Entries Added from Source     1
                                                                                       Entries Bypassed by Exit    ( 0)
                                                                                       --------------------------------
                                                                                       TOTAL Output ICSF Entries    29


  * One Source CKDS CROSS entry converts to two Candidates.
  + Total Converted Entries = Changed Input Entries + Entries Added from Source.
 

The first override record specifies that the conversion program bypass all the entries in the PCF CKDS. The second override record specifies that the conversion program convert a PCF entry labeled CRLABEL3 with a key type of local into an output PIN-encrypting key. This second override record also instructs the conversion program to place the phrase Used in transfers to Main Office in the installation data field of the output ICSF CKDS entry. The third override record specifies that the conversion program convert a PCF entry labeled LOLABEL2 and place Valid for January 2001 in the installation data field of the output ICSF CKDS entry.

After describing the three override records, the conversion report lists the data sets the conversion program used in the conversion. PROD.PCF.CKDS is the PCF CKDS that the program converted. INTEST.CSF.CKDS is the input ICSF CKDS that contains the ICSF entries input containing the ICSF entries input during the conversion. NEWTEST.CSF.CKDS is the output ICSF CKDS where the conversion program placed the converted entries.

Then the activity report lists totals pertaining to the conversion. The PCF CKDS has a total of 12 entries: four with a key type of local, four with a key type of remote, and four with a key type of cross. Because the conversion of each cross key entry results in two ICSF entries, the total ICSF records that are candidates for conversion from PCF is 16. Fourteen of those 16 entries were bypassed because of the global override record.

There were 28 entries in the input ICSF CKDS, and one of these entries was updated because it had an identical key label in the PCF CKDS. The total number of entries in the output ICSF CKDS is 29. This includes the 28 entries in the input ICSF CKDS plus the one added from the PCF CKDS. No entries were bypassed because of the conversion program exit.