Specifications

Chapter 13. Cryptographic adapter 139
$ ap_create -a n
This command creates a new (emulated) cryptographic coprocessor.
$ ap_destroy -a n
This command removes the indicated coprocessor process if it is not connected to a
CP process.
$ ap_von -a n
$ ap_von -a n -d y
$ ap_voff -a n
$ ap_voff -a n -d y
These commands vary online or vary offline connections between coprocessors and
their processing queues. The optional y operand specifies a domain number.
$ ap_vpd -a n
This command lists vital product data for the indicated coprocessor.
When a zPDT instance is started (while processing the devmap) an ap_create is issued for
that instance. If this is a stand-alone zPDT instance, ap_von commands are issued for all
domains. (It is not issued for a controller instance.) If this is a zPDT instance using shared
coprocessor resources, ap_von commands are issued for the coprocessors and domains
specified in the devmap.
The “real” cryptographic coprocessors on large System z machines have similar control
functions, but they are performed in different ways. Do not attempt to use these commands,
as listed here, on larger machines.
13.4.3 New z/OS releases
The coprocessor master keys, stored in the Linux srdis subdirectory, must be consistent with
the data in the CSF.CSFCKDS and CSF.CSFPKDS data sets in z/OS. If you install a new
z/OS release and create new z/OS data sets (while keeping older master keys for the
coprocessor functions) then CSF initialization will fail.
For long-term cryptographic usage, you should place the CSF.CSFCKDS and CSF.CSFPKDS
data sets on local volumes that will be used with all the releases of z/OS that you might want
to invoke.
If you have mismatched master keys and z/OS data sets, you need to zeroize the appropriate
coprocessor and domains and then enter a new pass phrase to start over. This, of course,
invalidates any existing lower-level keys. If you plan to work with encrypted data (as opposed
to simply developing programs that use encryption functions) you need to carefully plan
backups for the coprocessor data (in the srdis subdirectory) and the z/OS data sets used by
CSF. The 1090 functions have no special way to recover lost encryption keys.
13.4.4 Programming with ICSF
Following is a trivial program that uses the cryptographic coprocessor (via an ICSF
programming interface) to obtain random numbers:
//OGDENYZ JOB 1,OGDEN,MSGCLASS=X