This chapter describes how to install and configure ICSF.
Various steps are required to configure a z/OS system to be used as an external key store for a OKM Cluster.
Refer to documentation that accompanies this card.
The PTFs associated with Sun ELS 7.0 and NCS 6.2 are available at the Oracle Software Downloads site:
http://www.oracle.com/technetwork/indexes/downloads/index.html
Systems programmers can download the appropriate PTF and install it following standard procedures.
For ELS 7.0, the OKM-ICSF function is provided through an ELS PTF. The OKM-ICSF proxy is an HTTP server CGI routine. The SMC HTTP server must be active on a system with the ICSF PKCS11 function active.
The OKM command is valid from the SMCPARMS data set only.
The command name.
Specifies the PKCS11 token name for the OKM-ICSF interface. The first character of the name must be alphabetic or a national character (#, $, or @). Each of the remaining characters can be alphanumeric, a national character, or a period (.). The maximum length is 32 characters.
Specifies the default PKCS11 token name.
For NCS 6.2, the OKM-ICSF function is provided through an SMC PTF. The OKM-ICSF proxy is an HTTP server CGI routine. The SMC loadlib must be included in the STEPLIB for the HTTP server (SSKY500). The PKCS11 token name is KMS2.TOKEN.MASTERKEYS and cannot be changed.
Add the following to the SSKY500 HTTP Server startup parameters:
LOADMODULE SMCGCSF
See the Storage Management Component (SMC) 6.2 Configuration and Administration Guide for additional information about the HTTP Server startup parameters.
The following items activate the ICSF PKCS#11 function:
Ensure that ICSF is at HCR7740 or higher.
Define the Token Data Set (TKDS) in MVS. The TKDS is the repository for the keys used by PKCS#11. The TKDS is a key-sequenced VSAM data set.
Keys within the Token Data Set are not encrypted. Therefore, it is important that the security administrator create a RACF profile to protect the Token Data Set from unauthorized access.
The ICSF installation options data set contains two options related to the Token Data Set:
TKDSN(datasetname)
Identifies the VSAM data set that contains the token data set. It must be specified for ICSF to provide PKCS#11 services.
SYSPLEXTKDS(YES|NO,FAIL(YES|NO)
Specifies whether the token data set should have sysplex-wide data consistency.
See the IBM z/OS Cryptographic Services ICSF System Programmer's Guide (SA22-7520) for additional information on ICSF initialization.
ICSF uses profiles in the SAF CRYPTOZ class to control access to PKCS#11 tokens. The userid of the HTTP Server started task must have the following SAF access level for the defined PKCS#11 token:
SO.token_name CONTROL
USER.token_name UPDATE
The document Using AT-TLS with Sun Microsystems HSC Client/Server z/OS Solution, Implementation Example (October 2008) shows examples for configuring AT-TLS on the IBM mainframe.
AT-TLS is an encryption solution for TCP/IP applications that is completely transparent to the application server and client. Packet encryption and decryption occurs in the z/OS TCPIP address space at the TCP protocol level.
To implement AT-TLS encryption for the OKM to NCS/ELS HTTP server connection, the minimum level needed for the Communication Server is z/OS 1.9. The following available IBM PTFs (for APAR PK69048) should be applied for best performance:
Release 1A0: UK39417 available 08/10/07 z/OS 1.10
Release 190: UK39419 available 08/10/07 z/OS 1.9
See the following IBM publications for detailed information about the IBM z/OS Communications Server Policy Agent configuration and RACF definitions for AT-TLS:
IP Configuration Guide, SC31-8775
IP Configuration Reference, SC31-8776
Security Server RACF Security Administrator's Guide, SA22-7683
Security Server RACF Command Language Reference, SA22-7687
IBM Redbook Communications Server for z/OS V1R7 TCP/IP Implementation, Volume 4, Policy-Based Network Security, SG24-7172
Specify the following parameter in the TCPIP profile data set to activate the AT-TLS function:
TCPCONFIG TTLS
This statement may be placed in the TCP OBEY file.
The Policy Agent address space controls which TCP/IP traffic is encrypted. A sample PAGENT configuration follows.
PAGENT started task JCL:
//PAGENT PROC //* //PAGENT EXEC PGM=PAGENT,REGION=0K,TIME=NOLIMIT, // PARM='POSIX(ON) ALL31(ON) ENVAR("_CEE_ENVFILE=DD:STDENV")/-d1' //* //STDENV DD DSN=pagentdataset,DISP=SHR//SYSPRINT DD SYSOUT=* //SYSOUT DD SYSOUT=* //* //CEEDUMP DD SYSOUT=*,DCB=(RECFM=FB,LRECL=132,BLKSIZE=132)
The pagentdataset data set contains the PAGENT environment variables.
This is a sample PAGENT environment variable file:
LIBPATH=/lib:/usr/lib:/usr/lpp/ldapclient/lib:. PAGENT_CONFIG_FILE=/etc/pagent.conf PAGENT_LOG_FILE=/tmp/pagent.log PAGENT_LOG_FILE_CONTROL=3000,2 _BPXK_SETIBMOPT_TRANSPORT=TCPIP TZ=MST7MDT
/etc/pagent.conf contains the PAGENT configuration parameters.
This is a sample PAGENT configuration:
TTLSRule KMS-TO-ZOS { LocalAddr localtcpipaddress RemoteAddr remotetcpipaddress LocalPortRange localportrange RemotePortRange remoteportrange Jobname HTTPserverJobname Direction Inbound Priority 255 TTLSGroupActionRef gAct1~KMS_ICSF TTLSEnvironmentActionRefeAct1~KMS_ICSF TTLSConnectionActionRef cAct1~KMS_ICSF } TTLSGroupAction gAct1~KMS_ICSF { TTLSEnabled On Trace 2 } TTLSEnvironmentAction eAct1~KMS_ICSF { HandshakeRole Server EnvironmentUserInstance 0 TTLSKeyringParmsRef keyR~ZOS } TTLSConnectionAction cAct1~KMS_ICSF { HandshakeRole ServerWithClientAuth TTLSCipherParmsRef cipher1~AT-TLS__Gold TTLSConnectionAdvancedParmsRefcAdv1~KMS_ICSF CtraceClearText Off Trace 2 } TTLSConnectionAdvancedParmscAdv1~KMS_ICSF { ApplicationControlled Off HandshakeTimeout 10 ResetCipherTimer 0 CertificateLabel certificatelabel SecondaryMap Off } TTLSKeyringParms keyR~ZOS { Keyring keyringname } TTLSCipherParms cipher1~AT-TLS__Gold { V3CipherSuites TLS_RSA_WITH_3DES_EDE_CBC_SHA V3CipherSuites TLS_RSA_WITH_AES_128_CBC_SHA }
where:
localtcpipaddress
remotetcpipaddress
localportrange
remoteportrange
HTTPserverJobname
certificatelabel
keyringname
Activate the following RACF classes. Either the RACF panels or the CLI may be used.
DIGTCERT
DIGTNMAP
DIGTRING
SERVAUTH CLASS must be RACLISTed to prevent PORTMAP and RXSERV from abending TTLS is activated.
The RACF commands to achieve the above:
SETROPTS RACLIST(SERVAUTH)
RDEFINE SERVAUTH ** UACC(ALTER) OWNER (RACFADM)
RDEFINE STARTED PAGENT*.* OWNER(RACFADM) STDATA(USER(TCPIP) GROUP(STCGROUP)
RDEFINE FACILITY IRR.DIGTCERT.LISTRING UACC(NONE) OWNER(RACFADM)
RDEFINE FACLITY IRR.DIGTCERT.LIST UACC(NONE) OWNER(RACFADM)
RDEFINE FACILITY IRR.DIGTCERT.GENCERT UACC(NONE) OWNER (RACFADM)
The IBM Communications Server for z/OS V1R10 TCP/IP Implementation Volume 4: Security and Policy-Based Networking document outlines the procedure required to create and export digital certificates on the z/OS system.
The RACDCERT utility creates and manages digital certificates within RACF. Verify that RACDCERT is in the AUTHCMD section of the IKJTSOxx member in SYS1.PARMLIB.
The RACF commands to create Keyrings and certificates for use by the AT-TLS function follow:
RACDCERT ID(stcuser) ADDRING(keyringname)
where:
stcuser
keyringname
RACDCERT ID(stcuser) GENCERT CERTAUTH SUBJECTSDN(CN('serverdomainname') O('companyname') OU('unitname') C('country')) WITHLABEL('calabel') TRUST SIZE(1024) KEYUSAGE(HANDSHAKE,DATAENCRYPT,CERTSIGN)
where:
stcuser
serverdomainname
companyname
unitname
country
calabel
Note: This is the CA certificate for the OKM system. |
RACDCERT ID(stcuser) GENCERT SUBJECTSDN(CN('serverdomainname') O('companyname') OU('unitname') C('country')) WITHLABEL('serverlabel') TRUST SIZE(1024) SIGNWITH(CERTAUTH LABEL('calabel'))
where:
stcuser
serverdomainname
companyname
unitname
country
serverlabel
calabel
Note: This is the SERVER certificate. |
RACDCERT ID(stcuser) GENCERT SUBJECTSDN(CN('clientdomainname') O('companyname') OU('unitname') C('country')) WITHLABEL('clientlabel') TRUST SIZE(1024) SIGNWITH(CERTAUTH LABEL('calabel'))
where:
stcuser
serverdomainname
companyname
unitname
country
clientlabel
calabel
Note: This is the CLIENT certificate. |
The following commands connect the CA, SERVER and CLIENT certificates to the keyring specified in the PAGENT configuration:
RACDCERT ID(stcuser) CONNECT(CERTAUTH LABEL('calabel') RING('keyringname') USAGE(CERTAUTH))
where:
stcuser
calabel
keyringname
RACDCERT ID(stcuser) CONNECT(ID(stcuser) LABEL('serverlabel') RING('keyringname') DEFAULT USEAGE(PERSONAL)
where:
stcuser
serverlabel
keyringname
RACDCERT ID(stcuser) CONNECT(ID(stcuser) LABEL('clientlabel') RING('keyringname') USEAGE(PERSONAL)
where:
stcuser
clientlabel
keyringname
The following commands export the CA and client certificates for transmission to the OKM:
RACDCERT EXPORT (LABEL('calabel')) CERTAUTH DSN('datasetname') FORMAT(CERTB64)
where:
calabel
datasetname
RACDCERT EXPORT (LABEL('clientlabel')) ID(stcuser) DSN('datasetname') FORMAT(PKCS12DER) PASSWORD('password')
where:
clientlabel
stcuser
datasetname
password
The export data sets are now transmitted to the OKM, and FTP can be used. The CA certificate is transmitted with an EBCDIC to ASCII conversion. The CLIENT certificate is transmitted as a BINARY file and contains both the client certificate and its private key.
The following RACF commands list the status of the various RACF objects:
RLIST STARTED PAGENT.* STDATA ALL
RLIST DIGTRING * ALL
RLIST FACILITY IRR.DIGTCERT.LISTRING ALL
RLIST FACILITY IRR.DIGCERT.LST ALL
RLIST FACILITY IRR.DIGCERT.GENCERT ALL
RACDCERT ID(stcuser) LIST
RACDCERT ID(stcuser) LISTRING(keyringname)
RACDCERT CERTAUTH LIST
After the IBM mainframe has been configured, the z/OS systems programmer must provide the following information to the administrator of the OKM Cluster:
Host name or IP address of the mainframe
Port number (such as 9889)
Web application path (such as ”/cgi/smcgcsf”)
File containing the client ”user certificate” (exported and transferred off of the mainframe)
File containing the client private key (exported and transferred off of the mainframe)
Password that was used when the client private key was created
File containing the Root CA certificate (exported and transferred off of the mainframe)
The administrator of the OKM Cluster enters this information as the Master Key Provider settings in the Security Parameters panel of the OKM GUI.
The client ”user certificate” and the client private key might appear in the same file when they are exported from the IBM mainframe. If so, then the administrator should specify the same file in the OKM Certificate File Name and OKM Private Key File Name fields in the Master Key Provider settings.
The fields and their descriptions are given below:
Master Key Mode
Master Key Rekey Period
Master Key Provider Network Address
Master Key Provider Port Number
Master Key Provider Web App Path
OKM Certificate File Name
OKM Private Key File Name
OKM Private Key Password
CA Certificate File Name