Cryptographic usage
An Independent Software Vendor (ISV) IBM Z Program Development Tool (IBM zPDT)
(ISV zPDT) system can emulate multiple cryptographic adapters as CEX8S devices.1 Each CEX8S emulated adapter runs as separate Linux processes. If sufficient base processor cores are available so that these threads can be dispatched in parallel by Linux, the emulated adapters can run asynchronously with the ISV zPDT CPs.
(ISV zPDT) system can emulate multiple cryptographic adapters as CEX8S devices.1 Each CEX8S emulated adapter runs as separate Linux processes. If sufficient base processor cores are available so that these threads can be dispatched in parallel by Linux, the emulated adapters can run asynchronously with the ISV zPDT CPs.
Do not confuse a cryptographic adapter (often known as a co-processor) with the cryptographic instructions that are always available with an ISV zPDT system. These instructions are the KM, KMC, KIMD, KLMD, KMAC, and associated instructions (known as the CP Assist for Cryptographic Functions (CPACF) instructions) that provide several fundamental cryptographic operations.
The cryptographic instructions can be coded directly in a program or used through Integrated Cryptographic Service Facility (ICSF) programming interfaces. For practical purposes, the cryptographic co-processor facilities are available only through ICSF programming interfaces.
|
Important: The cryptographic adapter emulation that is used with ISV zPDT GA11 uses a new format for storing master keys. ISV zPDT GA11 does not automatically convert an earlier format to the current format. You must initialize the GA11 cryptographic adapter with the same master keys previously used if you need to access previously (before GA11) encrypted data.
When attempting to initialize ISV zPDT GA11 emulated cryptographic adapter master keys with the same keys that were used with earlier versions (by typing them into the z/SO @ICSF program), it is important to enter the master key exactly as it was entered for the previous system.
For ISV zPDT GA11, do not copy the previous ~/z1090/srdis files to the new GA11 system because they are not compatible with GA11. Furthermore, if you might use your older ISV zPDT version again, be certain to save the older srdis file (under a different name) before creating one with ISV zPDT GA11.
|
17.1 Background information
A cryptographic co-processor is represented by an adjunct processor (AP) process in
ISV zPDT. An IBM zSystems CP sends and receives work entries through co-processor queues that are known as domains.
ISV zPDT. An IBM zSystems CP sends and receives work entries through co-processor queues that are known as domains.
The accelerator mode and customized (user-defined extensions (UDXs)) functions of a cryptographic co-processor are not provided for ISV zPDT. Trusted Key Entry (TKE) systems, which are personal computers (PCs) with unique software and an appropriate cryptographic adapter, are not used with ISV zPDT. PKCS#11 is not available with ISV zPDT emulation.
Each emulated cryptographic co-processor has 16 domains.2 Each z/OS instance uses a different domain (as specified in the ICSF parameters). If multiple co-processors are defined, then z/OS uses the same domain number in each co-processor. If multiple co-processors are defined, z/OS can dispatch requests to all of them (by using the same domain number in each processor).
With ISV zPDT, the cryptographic co-processor keys (and other state information) are stored in the ~/z1090/srdis directory. There is a separate subdirectory for each defined co-processor. These directories are created automatically by ISV zPDT if they do not exist. Any tampering with this information can produce unpredictable results. However, a complete co-processor subdirectory can be deleted as a way of reinitializing (zeroing) that co-processor. (The ap_zeroize command, described later, is another way to re-initialize a co-processor.)
ISV zPDT cryptographic functions are intended for development purposes and not for security. Although the format of the key data in ~/z1090/srdis is not documented, it is not secure in any cryptographic sense.
The provided ISV zPDT cryptographic functions should be functional for normal, basic uses. ISV zPDT is not intended for more exotic cryptographic enhancements.
17.2 Device map specification
The ISV zPDT specification for emulated cryptographic adapters is part of the device map (devmap) and consists only of a simple adjunct-processors stanza:
[system]
memory 8000m
3270port 3270
processors 2
[adjunct-processors]
crypto 0
crypto 1 #(More than one cryptographic adapter is possible.)
[manager]
name .........
With the ISV zPDT architecture, you can have up to 16 or 64 cryptographic co-processors, depending on the overall configuration.3 z/OS allows a maximum of 16.
17.3 Initial ICSF startup
For practical purposes, the ICSF software functions are needed to initialize cryptographic adapters. Here is a brief outline of the steps that we took to customize and use the ICSF panels on a z/OS Application Development Controlled Distribution (ADCD) 2.4 system. The usage of the ADCD system PARMLIB and PROCLIB is not required, so adjust these names for your needs.
Recent ADCD z/OS releases automatically start Cryptographic Service Facility (CSF) and have the basic customization to use both the CPACF instructions (which are always enabled) and CEX8S functions (if defined in your devmap). The most recent z/OS ADCD (at the time of writing) uses ICSF level HCR77D2.
We found that we needed to specify a domain number in the PARMLIB member that is associated with ISCF:
•For PARMLIB member CSFPRM00 (this example is from a recent ADCD):
CKDSN(CSF.CSFCKDS) <-- You might want to change these data set names.
PKDSN(CSF.CSFPKDS) (Perhaps with an “S” before the “CSF...”)
COMPAT(NO)
DOMAIN(0) <-- Add this parameter to specify a domain number.
SSM(NO)
CHECKAUTH(NO)
CTRACE(CTICSF00)
USERPARM(USERPARM)
REASONCODES(ICSF)
•For PARMLIB member IKJTSO00:
AUTHPGM NAMES( /* AUTHORIZED PROGRAM NAMES */ +
...
CSFDAUTH /*THIS WAS ALREADY IN OUR ADCD SYSTEM */ +
CSFDPKDS /*WE ADDED THIS ONE */ +
AUTHTSF NAMES /*PROGRAMS...... */ +
....
CSFDAUTH /*THIS WAS ALREADY IN OUR ADCD SYSTEM */ +
CSFDPKDS /*WE ADDED THIS ONE */ +
Be certain to copy the plus signs (+) at the end of each line. These additions should prevent 047 ABEND errors when customizing the cryptographic co-processor.4 After making the PARMLIB changes, stop CSF (P CSF) and restart it (S CSF).
If you added names to the IKJTSO00 member, you might want to perform an initial program load (IPL) of your z/OS system to prevent an 047 ABEND when initializing ICSF.5 An alternative is to try a set ikjtso00 command (assuming that you used member “00.”)
Complete the following steps:
1. To begin customization of a cryptographic co-processor, go to IBM Interactive System Productivity Facility (ISPF) option 6 and enter the command @ICSF. This command should produce the first ICSF panel, as shown in Figure 17-1. (The panel examples are from an older z/OS system.)
Figure 17-1 First ICSF panel
2. On this panel, select option 1. This action should produce a display like Figure 17-2. This panel verifies that the co-processor is active. The “7C00” nomenclature varies with releases.
Figure 17-2 Verifying that the cryptographic co-processor is online
3. Press F3 to return to the first ICSF panel and select option 6. With this option, you can enter a passphrase that is automatically used to initialize the basic co-processor master keys. (An alternative method for initializing master keys is to use multiple other functions on the ICSF panels. Unless you are familiar with cryptographic co-processor management, use the simple passphrase initialization process.)
4. Complete the passphrase panel, as shown in Figure 17-3 (using your own passphrase). You must enter your passphrase and two data set names; specify the no KDSR format; and enter a character to select the Initialize system option. The two data set names that shown in the example (CSF.SCSFCKDS and CSF.SCSFPKDS) are preallocated but empty in the current ADCD z/OS system. (This situation might change in newer z/OS ADCD releases. Prototype jobs to create these data sets can be found in SYS1.SAMPLIB members CSFCKDS and CSFPKDS.) These data set names should match whatever you specified in PARMLIB.
Note the passphrase that you selected, including uppercase and lowercase, spaces that you entered (including at the end of the phrase), and any special characters that are involved. If you have encrypted data involving the adapter functions and want to reinitialize the adapter controls, re-enter the same passphrase.
The sample jobs to allocate these data sets use the names CSF.CSFCKDS and CSF.CSFPKDS while other jobs use CSF.SCSFCKDS and CSF.SCSFPKDS. Note the additional “S” in these names. We changed the sample allocation jobs to use the “S” versions of the names. There is no requirement to use particular names if you are consistent.
Figure 17-3 Passphrase panel
5. Start ICSF again and select option 1. Enter the letter S in front of the 7C00 co-processor name and press Enter. This action should produce a display showing some of the master key initialization.
The basic cryptographic co-processor setup is complete. Do not experiment with option 2 (MASTER KEY MGMT) functions unless you are certain that you know what you are doing.
|
Tip: The instructions that provided here are intended for customers with little or no experience with the IBM zSystems cryptographic adapters. Experienced customers might handle the emulated cryptographic adapter initialization differently.
|
17.4 Operational notes
CSF must be started (as a started task) to use it. At the time of writing, this task is automatically done in the latest ADCD z/OS releases. You can easily verify the CSF operation by going to omvs and issuing the following command:
od -An -N4 -td /dev/random
If CSF is not working, the result is an internal error message. If these functions are working, a random number is displayed.
The ISV zPDT cryptographic co-processor emulation functions are intended for use by developers who require these functions. It should be clearly understood that while using
ISV zPDT that these emulated functions are not intended to produce a secure system or function as a secure peer when dealing with private data.
ISV zPDT that these emulated functions are not intended to produce a secure system or function as a secure peer when dealing with private data.
17.4.1 Multiple ISV zPDT instances
ISV zPDT can have multiple instances in operation. These instances can share facilities, such as shared direct access storage device. If shared facilities are used, then an ISV zPDT controller instance6 must be present, as described in Chapter 10, “Multiple instances and guests” on page 215. Co-processors that are defined in the controller instance can be shared by all ISV zPDT instances. A maximum of 16 co-processors may be present in a “normal”
ISV zPDT instance. A maximum of 64 co-processors may be defined for a controller instance. (Any ISV zPDT configuration that involves so many crypto co-processors is unusual.)
ISV zPDT instance. A maximum of 64 co-processors may be defined for a controller instance. (Any ISV zPDT configuration that involves so many crypto co-processors is unusual.)
An additional devmap statement is used in the devmap of an ISV zPDT instance that is using co-processors that are defined in the controller instance:
domain <member name> a y #(“a” is a coprocessor number, and y is a domain number.)
The member name is required if the domain statement appears in the controller instance. The name is used if the domain statement is in an operational instance devmap. The domain number (y in the statement above) can be a single number, a list of numbers that are separated by commas, or a range of numbers that are separated by a dash. The angle brackets around the member name are not part of the syntax. They indicate an optional parameter. The domain numbers must be specified in the ICSF startup parameters and are different for each z/OS instance.
Three shared cryptographic co-processors, which are used by three ISV zPDT instances, might be defined as follows:
#-------------- controller instance ----------------------
[system] #No processor is defined for the controller.
...
...
[adjunct-processors]
crypto 0
crypto 1
crypto 2
#------------- ISV zPDT instance 1 ---------------------------
[system]
processors 1
...
[adjunct-processors]
domain 0 1
domain 1 1
domain 2 1
#------------- ISV zPDT instance 2 ---------------------------
[system]
processors 1
...
[adjunct-processors]
domain 0 2 #All the domain statements
domain 1 2 #could be in the controller
domain 2 2 #devmap instead. Your choice.
#------------- ISV zPDT instance 3 ---------------------------
[system]
processors 1
...
[adjunct-processors]
domain 0 3 #If the domain statements are in the
domain 1 3 #controller devmap, they need the relevant
domain 2 3 #member name as the first parameter.
Each ISV zPDT instance has a different domain number that is specified in the domain statements. In this example, the domain numbers are the same as the instance numbers, but this situation is a coincidence. ISV zPDT supports a maximum of 16 domains for each emulated co-processor.
17.4.2 Co-processor control commands
A number of commands are included for specialized management of the ISV zPDT cryptographic co-processors. These commands are issued from a Linux terminal window.
ISV zPDT must be operational for these commands to be used. They are not needed for normal system use, and as a best practice, do not experiment with them unless you have a good understanding of what you are doing. In the following commands, the n variable is the cryptographic co-processor number and the y variable is a domain number.
ISV zPDT must be operational for these commands to be used. They are not needed for normal system use, and as a best practice, do not experiment with them unless you have a good understanding of what you are doing. In the following commands, the n variable is the cryptographic co-processor number and the y variable is a domain number.
Briefly, the commands are as follows:
•This command reinitializes (zeros) all the data, such as keys, that is retained by the co-processor. The first version of the command affects only the specified domain. The second version (with the -i operand) zeros the whole adapter. Either -i or -d y must be specified (with an appropriate domain number for y).
$ ap_zeroize -a n -d y
$ ap_zeroize -a n -i
•This command queries basic status and domain information. With no operand, it lists all the co-processors that are available. With an operand, it lists which domains are used by the indicated co-processor.
$ ap_query
$ ap_query -a n
•This command creates an (emulated) cryptographic co-processor:
$ ap_create -a n
•This command removes the indicated co-processor process if it is not connected to a CP process:
$ ap_destroy -a n
•These commands vary online or vary offline connections between co-processors and their processing queues. The optional y operand specifies a domain number.
$ ap_von -a n
$ ap_von -a n -d y
$ ap_voff -a n
$ ap_voff -a n -d y
•This command lists Vital Product Data (VPD) for the indicated co-processor:
$ ap_vpd -a n
When an ISV zPDT instance is started (while processing the devmap), an ap_create command is automatically issued for that instance. If this instance is a stand-alone ISV zPDT instance, ap_von commands are issued for all domains. (It is not issued for a controller instance.) If this instance is an ISV zPDT instance that uses shared co-processor resources, ap_von commands are issued for the co-processors and domains that are specified in the devmap.
The “real” cryptographic co-processors on large IBM zSystems 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.
17.4.3 New z/OS releases
The co-processor master keys, which are stored in the Linux srdis subdirectory, must be consistent with the data in the CSF.SCSFCKDS and CSF.SCSFPKDS data sets in z/OS.7 If you install a new z/OS release and create z/OS data sets, you must initialize the new data sets or copy the contents of the old data sets to the new data sets. Unfortunately, these data sets are Virtual Storage Access Method (VSAM) data sets, which makes moving them or copying them more complicated.
If you plan to work with encrypted data (as opposed to developing programs that use encryption functions), you must carefully plan backups for the co-processor data (in the srdis subdirectory) and the z/OS data sets that are used by CSF. The ISV zPDT functions have no special way to recover lost encryption keys.
17.4.4 Programming with CSF
Here are the core elements of a trivial program that uses the cryptographic co-processor (through a CSF programming interface) to obtain random numbers:
*
* GET RANDOM NUMBERS AND PRINT THEM
*
LA 7,20 GET 20 RANDOM NUMBERS
LOOP1 CALL CSNBRNG,(RETC,REASC,EXDL,EXD,FORM,RANNUM)
CLC RETC(4),SZEROS
BNE ERROR2
LA 1,RANNUM WHERE TO START HEX CONVERSION
BAL 10,AHEXLINE
MVC PRINTLNE(80),SBLANKS
MVC PRINTLNE(21),=C’RANDOM NUMBER (HEX) =’
MVC PRINTLNE+22(16),SWOUT
PUT PRINTD,PRINTLNE
BCT 7,LOOP1
...
* VARIOUS WORK AREAS AND CONSTANTS
PRINTLNE DC CL80’ ‘
RETC DC F’0’ RETURN CODE (ICSF)
REASC DC F’0’ REASON CODE (ICSF)
EXDL DC F’0’ EXIT DATA LENGTH (ICSF)
EXD DC CL4’ ‘ EXIT DATA (ICSF)
FORM DC CL8’RANDOM ‘ RULE FORM
RANNUM DC 2F’0’ RANDON NUMBER
...
//L.SYSLIB DD DISP=SHR,DSN=SYS1.MACLIB
// DD DISP=SHR,DSN=CSF.SCSFMOD0
//G.SYSPRINT DD SYSOUT=*
17.5 Basic data set encryption example
|
Attention: The examples that are shown in this section were created under an older z/OS system than what is current when ISV zPDT GA11 was released. You might need to make minor changes in the following outlines.
|
Many ISV zPDT customers also use the ADCD z/OS package. The following instructions provide two options for basic implementations of data set encryption.8 One option uses RACF and a specific High-Level Qualifier (HLQ) to select data sets for encryption, and the other option uses JCL parameters to control encryption. The setup is essentially the same for both options.
These examples ignore all the planning and controls that are used in a production environment and concentrates only on a basic setup for data set encryption. There are many ways to accomplish the various steps that are needed, and the following instructions outline one of these ways. Some details might be different for later ADCD releases.
This example assumes a basic systems programming familiarity with z/OS and the z/OS ADCD systems. The following names are used in the example:
•PROT is an arbitrary choice, and it is used both as a HLQ and as a Storage Class name, but there is no need to use the same name for both in your own work.
•PROTECT is used as a Storage Group name.
•SYS1.S0W1.SCDS and SYS1.SMS.CNTL exist in the current z/OS ADCD.
•DB2STORG and DB2STORC are member names that are used in the current z/OS ADCD.
•ADCDA and ADCDB are user IDs (in the current ADCD) with no privileges.
•The address (AB0) that is used for a new volume is arbitrary within ADCD input/output definition file (IODF) constraints.
•The new volume volser (SMS001) is arbitrary.
•MYPROT.KEY1 is an arbitrary label for an encryption key.
•PROT.TRY1 is an arbitrary data set name with HLQ PROT.
•OGDEN.TRY2 is an arbitrary data set name without a special HLQ.
•The Linux directory /z/zos23 represents the working directory for running ISV zPDT, but users might have their ISV zPDT startup in any directory.
One goal in our example is to use RACF controls to automatically encrypt any data set with the HLQ of PROT. The other goal is to specify encryption by using additional JCL parameters. In both cases, an encryption key with the label MYPROT.KEY1 is used. IBMUSER is the administrator (with RACF SPECIAL authority). User ID ADCDA is allowed access to the key and the data sets. User ID ADCDB is allowed access to the data sets but not the key.
Volume setup
Complete the following steps:
1. You need a DFSMS-managed volume for extended data sets. Create this volume before starting ISV zPDT with the following command:
$ alcckd /z/zos23/SMS001 -d3390-1 (choice of a 3390-1 is arbitrary)
2. Add this volume to your ISV zPDT devmap, and also add a crypto adapter to the devmap:
[system]
memory 8G
3270port 3270
processors 3
[adjunct-processors]
crypto 0
...
[manager]
name awsckd 0001
...
device AB0 3390 3990 /z/zos24/SMS001 # (The AB0 address is not special.)
...
3. After starting z/OS, initialize the new volume as SMS-managed:
//INITVOL JOB 1,OGDEN,MSGCLASS=X,REGION=40M
// EXEC PGM=ICKDSF
//SYSPRINT DD SYSOUT=*
//SYSIN DD *
INIT UNIT(AB0) NOVALIDATE NVFY VOLID(SMS001) PURGE -
VTOC(0,1,14) STORAGEGROUP
/*
4. Vary the new volume online.
SMS setup
You must make the new SMS-managed volume usable, which involves defining a Storage Group (containing the new volume) and a Storage Class for the target data sets. These controls are the minimum SMS controls that are required. While working with ISMF, complete the following steps:
1. Start ISMF. If you cannot see option 6, select option 0 (ISMP Profile), then option 0 (User Mode), and then option 2 (Storage Administrator). Exit from ISMF and start it again.
2. Create a Storage Group that is named PROTECT. Select option 6 (Storage Group) and enter 'SYS1.S0W1.SCDS' as the CDS Name. Enter PROTECT as the Storage Group Name and POOL as the type, and then select option 3 (Define). Change any of the characteristics that you want. In our example, we changed only Guaranteed Backup Frequency to NOLIMIT because ISMF needed an entry for this parameter. Select option 5 (Volume) and then option 2 (Define). Enter your selected volser (SMS001 in this example) in a prefix line.
3. Create a Storage Class named PROT. Select option 5 (Storage Class) and enter 'SYS1.S0W1.SCDS' as the CDS Name. Enter PROT as the Storage Class Name, and select option 3 (Define). We changed the Guaranteed Space parameter to Y.
4. Update the Storage Class and Storage Group ACS routines.9 Select option 7 (Automatic Class Selection). Enter 'SYS1.S0W1.SCDS' as the CDS Name and select option 1 (Edit). This action opens the ISPF edit panel. Enter the name 'SYS1.SMS.CNTL(DB2STORG)' as the data set name and press Enter. Add the following lines at the beginning of the WHEN section:
WHEN (&HLQ = 'PROT')
DO
SET &STORGRP = 'PROTECT'
EXIT
END
WHEN (&STORCLAS = 'PROT')
DO
SET &STORGRP = 'PROTECT'
EXIT
END
5. Press PF3 and then edit 'SYS1.SMS.CNTL(DB2STORC)' by adding the following lines:
WHEN (&HLQ = 'PROT')
DO
SET &STORCLAS = 'PROT'
EXIT
END
6. Go to the end of the DB2STORC member and look for an OTHERWISE statement:
OTHERWISE
DO
SET &STORCLAS = &STORCLAS (it was &STORCLAS = ’’)
EXIT
END
7. Exit the edit panel and select 2 (Translate) in the ACS Application panel. Set the SCDS name to 'SYS1.S0W1.SCDS', the ACS Source to 'SYS1.SMS.CNTL', and Member to DB2STORG. Place any name for the Listing Data Set, and press Enter. If the results are good, repeat the process for member DB2STORC. (The statements after OTHERWISE in DB2STORC are odd, but they are needed to accept a storage class that is entered in a JCL DD statement.)
8. Update the Control Data Set. Select ISMF option 8 (Control Data Set). The CDS name is 'SYS1.S0W1.SCDS'. Select option 5 (Activate). Place a '/' character as indicated and press Enter.
9. Exit ISMF.
RACF work
While working as IBMUSER, complete the following steps for RACF:
1. Using ISPF option 6, verify that classes CSFKEYS and CSFSERV are active, generic, and RACLISTed:
SETROPTS LIST (Look through the output to verify the details.)
2. Check access to RACF class CSFSERV by using ISPF option 6:
RLIST CSFSERV *
On some older systems, we found that the access was UACC(READ), which is not a good idea. If the UACC needs changing, try the following commands:
RALTER CSFSERV * UACC(NONE)
SETROPTS RACLIST(CSFSERV) REFRESH
3. User IDs ADCDA and ADCDB might need their passwords reset. To do so, use the following commands:
ALU adcda PASS(xxxxxx) NOEXPIRED (Use the appropriate passwords.)
ALU adcdb PASS(yyyyyy) NOEXPIRED
4. Data set encryption requires the user to have read access to the following profile in the FACILITY class:
STGADMIN.SMS.ALLOW.DATASET.ENCRYPT
For the z/OS 2.3 ADCD, we found that this class was set for IBMUSER. You can verify this setting by running the following command:
RLIST FACILITY STGADMIN.*
You need to grant PERMIT access to users (other than IBMUSER) that need to access data set encryption for this profile.
5. Working as IBMUSER, select ISPF option 6 and define a number of RACF profiles:
RDEF CSFSERV CSFKGUP UACC(NONE) needed for KGUP
RDEF CSFSERV CSFKGN UACC(NONE) needed for KGUP
RDEF CSFSERV CSFKRR2 UACC(NONE) needed for KGUP
RDEF CSFSERV CSFKRC2 UACC(NONE) needed for KGUP
RDEF CSFSERV CSFPMCI UACC(NONE) needed to initialize ICSF
RDEF CSFSERV CSFOWS UACC(NONE) needed to initialize ICSF
RDEF CSFSERV CSFDKCS UACC(NONE) needed to initialize ICSF
RDEF CSFSERV CSFCRC UACC(NONE) needed to refresh ISCF
SETROPTS RACLIST(CSFSERV) REFRESH
As the profile owner, IBMUSER has ALTER access to these profiles.
6. While you are working with RACF, use the following job to enable automatic encryption for the HLQ that you selected (PROT) and allow access to the key that you intend to use:
ADDGROUP PROT (Add a group so that the HLQ can be protected.)
ADDSD 'PROT.*' UACC(NONE) DFP(DATAKEY(MYPROT.KEY1))
PE 'PROT.*' ID(ADCDA) ACCESS(READ)
PE 'PROT.*' ID(ADCDB) ACCESS(READ)
RDEF CSFKEYS MYPROT.KEY1 UACC(NONE) ICSF(SYMCPACFWRAP(YES) -
SYMCPACFRET(YES))
SYMCPACFRET(YES))
PE MYPROT.KEY1 CLASS(CSFKEYS) ID(ADCDA) ACCESS(READ)
SETROPTS RACLIST(CSFKEYS) REFRESH
The PERMIT statements allow ADCDA and ADCDB access to PROT.* Data sets are not needed because there are no RACF profiles to prohibit their access. However, this action illustrates what would be done in a more general environment. IBMUSER, as the profile owner, has access to these profiles.
ICSF and master keys
Initialize ICSF and the master keys as described in 17.3, “Initial ICSF startup” on page 333 if you have not done so.
Creating an encryption key
Create a random secure key by using a batch job, and then list the key data set with an IDCAMS job:
//CRYPTO2 JOB 1,OGDEN,MSGCLASS=X
// EXEC PGM=CSFKGUP
//CSFCKDS DD DISP=OLD,DSN=CSF.SCSFCKDS
//CSFDIAG DD SYSOUT=*,LRECL=133 (The LRECL parameters are required.)
//CSFKEYS DD SYSOUT=*,LRECL=1044
//CSFSTMNT DD SYSOUT=*,LRECL=80
//CSFIN DD *
ADD TYPE(DATA) ALGORITHM(AES) LABEL(MYPROT.KEY1) LENGTH(32)
/*
//*
// EXEC PGM=IDCAMS
//IN1 DD DISP=SHR,DSN=CSF.SCSFCKDS
//SYSPRINT DD SYSOUT=*
//SYSIN DD *
PRINT INFILE(IN1) DUMP
/*
Refresh the in-storage CKDS by going to ICSF and selecting option 8 and then option 4, which is REFRESH. Enter 'CSF.SCSFCKDS' (with single quotation marks) as the New CKDS parameter and press Enter. (The title is misleading because CSF.SCSFCKDS is not new in this case.) Exit ICSF.
Testing and verifying encryption
Test the RACF-controlled encryption with a job like the following one:
//CRYPTO3 JOB 1,OGDEN,MSGCLASS=X
// EXEC PGM=IEBGENER
//SYSPRINT DD *
//SYSIN DD DUMMY
//SYSUT1 DD DISP=SHR,DSN=OGDEN.ASM (Select a simple sequential file.)
//SYSUT2 DD DISP=(NEW,CATLG,DELETE),UNIT=3390,DSN=PROT.TRY1,
// SPACE=(TRK,(10,1)),VOL=SER=SMS001,DSNTYPE=EXTREQ
Submit the job. If it runs without errors, go to the new PROT.TRY1 data set. You should be able to go to it because it is automatically decrypted for IBMUSER because IBMUSER has access to both the data set and the key.
Log in as ADCDA and go to the data set. This action should work because ADCDA has access to both the data set and the key. Log in as ADCDB and go to the data set. This action fails because ADCDB does not have access to the key.
To determine whether the data set is encrypted, as IBMUSER, run the following job:
//CRYPTO4 JOB 1,OGDEN,MSGCLASS=X
// EXEC PGM=ADRDSSU,REGION=0M
//SYSPRINT DD SYSOUT=*
//DDNAME DD DISP=SHR,DSN=PROT.TRY1
//SYSIN DD *
PRINT INDDNAME(DDNAME) DS(PROT.TRY1)
/*
The results should show the data set as it is stored (encrypted) on disk.
Instead of using RACF to control encryption (through a preselected set of HLQs), you can specify encryption by using only JCL control. In this case, we do not use the HLQ of PROT in our example:
//CRYPTO5 JOB 1,OGDEN,MSGCLASS=X
// EXEC PGM=IEBGENER
//SYSPRINT DD *
//SYSIN DD DUMMY
//SYSUT1 DD DISP=SHR,DSN=OGDEN.ASM (select a simple sequential file)
//SYSUT2 DD DISP=(NEW,CATLG,DELETE),UNIT=3390,DSN=OGDEN.TRY2,
// SPACE=(TRK,(10,1)),VOL=SER=SMS001,DSNTYPE=EXTREQ,
// STORCLAS=’PROT’,DSKEYLBL=’MYPROT.KEY1’
You can again verify the encryption by dumping the data set with ADRDSSU. You might also use TSO commands such as the following ones to verify that the catalog entry denotes encryption and the key label:
LISTC ENTRIES(’OGDEN.TRY2’) ALL
LISTC LEVEL(PROT) ALL
Try logging on to TSO as user ADCDA and go to the two data sets (PROT.TRY1 and OGDEN.TRY2 in the examples). You should be able to access them. Then, log in as ADCDB and try it. You cannot access them because ADCDB does not have access to the crypto key.
Re-initializing the master keys
While experimenting with your sandbox ISV zPDT system, you might want to re-initialize th master keys. You might find this task difficult because the CKDS and PKDS data sets have content in them and a master key exists. To correct this situation, complete the following steps:
1. Stop CSF with a P CSF command.
2. Use an ISV zPDT command (entered from Linux) to clear the master keys:
$ ap_zeroize -a 0 -d 0 (Assume crypto adapter 0 and domain 0.)
3. You might need access to a specific RACF profile. If so, use the following commands:
RDEF CSFSERV CSFRSWS UACC(NONE) (As the owner, you have ALTER access.)
SETROPTS RACLIST(CSFSERV) REFRESH
4. Using ISPF 3.4, delete the VSAM clusters CSF.SCSFCKDS and CSF.SCSFPKDS. (Using a DEL line command instead of a D line command is a best practice.)
5. Allocate new data sets with a job like the following example. (Prototype jobs can be found in SYS1.SAMPLIB members CSFCKDS and CSFPKDS).
//CSFDS JOB 1,OGDEN,MSGCLASS=X
//DEFINE EXEC PGM=IDCAMS,REGION=0M
//SYSPRINT DD SYSOUT=*
//SYSIN DD *
DEFINE CLUSTER(NAME(CSF.SCSFCKDS) VOLUME(B5SYS1) -
RECORDS(200 100) RECORDSIZE(272 2048) KEYS(72 0) -
FREESPACE(10 10) SHAREOPTIONS(2,3)) -
DATA (NAME(CSF.SCSFCKDS.DATA) BUFFERSPACE(100000) ERASE) -
INDEX (NAME(CSF.SCSFCKDS.INDEX))
DEFINE CLUSTER(NAME(CSF.SCSFPKDS) VOLUME(B5SYS1) -
RECORDS(200 100) RECORDSIZE(800 3800) KEYS(72 0) -
FREESPACE(0 0) SHAREOPTIONS(2,3)) -
DATA (NAME(CSF.SCSFPKDS.DATA) BUFFERSPACE(100000) ERASE CISZ(8192)) -
INDEX (NAME(CSF.SCSFPKDS.INDEX))
/*
6. Start CSF (S CSF) and continue with the master keys.
17.5.1 z/VM usage
Cryptographic co-processors are defined for z/VM guests as shown in the following example:
USER USERJOE 999999 512M 16E BDEG
ACCOUNT ABC123 ABC123
CRYPTO DOMAIN 13 14 15 (domains to be used)
CRYPTO APDED 1 3 (co-processors to be dedicated for use)
OPTION TODENABLE MAINTCCW
MACHINE ESA 64
CPU 0 BASE
CPU 1
IPL 190 PARM AUTOCR
etc
1 This situation assumes that you use ISV zPDT GA11 or later. Earlier releases of ISV zPDT had earlier levels of CEX functions.
2 CEX8S functions on a larger IBM zSystems server have more domains. ISV zPDT is limited to 16 domains.
3 An ISV zPDT group controller instance can have up to 64 co-processors defined. Otherwise, the limit is 16.
4 Later ADCD releases might not need these additions.
5 Logging off Time Sharing Option (TSO) and then logging on again might accomplish this task.
6 A controller instance is an ISV zPDT instance (with a separate devmap and started with an awsstart command) that does not contain any IBM zSystems processors.
7 You might have used different data set names.
8 Later z/OS ADCD releases might include some of the RACF work that is described in this section.
9 The ACS routines that are distributed with new z/OS ADCD releases tend to vary, and the examples in this publication might need to be adapted to new ADCD releases.
..................Content has been hidden....................
You can't read the all page of ebook, please click here login for view all page.