1. Installation and Administration Guide
  2. OKM-ICSF Integration
  3. IBM Mainframe Configuration for ICSF

IBM Mainframe Configuration for ICSF

Various steps are required to configure a z/OS system to be used as an external key store for a OKM Cluster.

Install and Configure the CEX2C Cryptographic Card for ICSF

Refer to documentation that accompanies this card.

StorageTek ELS Setup for OKM-ICSF

This section describes the ELS command for to setup OKM-ICSF.

For ELS 7.0, the OKM-ICSF function is provided through ELS PTF L1H150P that can be downloaded from:

http://www.oracle.com/technetwork/indexes/downloads/index.html

The OKM-ICSF function is in the base code for subsequent releases. The OKM-ICSF proxy is an SMC HTTP server CGI routine. The SMC HTTP server must be active on a system with the ICSF PKCS11 function active. The KMS command is valid from the SMCPARMS data set only.

Description of kms_token1.png follows
Description of the illustration kms_token1.png
KMS

The command name.

TOKEN

tokenname

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.

KMS2.TOKEN.MASTERKEYS

Specifies the default PKCS11 token name.

Preparing ICSF

Verify the system is ready to activate ICSF.

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 user ID 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

Configuring AT-TLS

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.

The document Using AT-TLS with HSC/SMC Client/Server z/OS Solution, Implementation Example (http://docs.oracle.com/cd/E21457_01/en/E27193_01/E27193_01.pdf) shows examples for configuring AT-TLS on the IBM mainframe.

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

TCPIP OBEY Parameter

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

Policy Agent (PAGENT) Configuration

The Policy Agent address space controls which TCP/IP traffic is encrypted. This section provides a sample PAGENT configuration.

PAGENT JCL

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.

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.

PAGENT Configuration

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 — local TCP/IP address (address of HTTP server)

remotetcpipaddress— remote TCP/IP address (address of OKM client) can be ALL for all TCP/IP addresses

localportrange — local port of HTTP server (specified in the HTTP or SMC startup)

remoteportrange — remote port range (1024-65535 for all ephemeral ports)

HTTPserverJobname — jobname of the HTTP Server

certificatelabel — label from certificate definition

keyringname — name from RACF keyring definition

RACF Definitions

Activate the following RACF classes. Either the RACF panels or the CLI may be used.

  • DIGTCERT
  • DIGTNMAP
  • DIGTRING

The SERVAUTH class must use RACLIST processing to prevent PORTMAP and RXSERV from abending TTLS. See RACF Commands below.

RACF Commands

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)
RACF Certificate Creation Commands

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 following RACF commands to create Keyrings and certificates for use by the AT-TLS function:

RACDCERT ID(stcuser) ADDRING(keyringname)

where:

  • stcuser — RACF user ID associated with the SMC started task
  • keyringname — Name of keyring, must match the Keyring specified in the PAGENT configuration

RACDCERT GENCERT CERTAUTH SUBJECTSDN(CN('serverdomainname') O('companyname') OU('unitname') C('country')) WITHLABEL('calabel') TRUSTSIZE(1024) KEYUSAGE(HANDSHAKE,DATAENCRYPT,CERTSIGN)

where:

  • serverdomainname — Domain name of the z/OS server (for example, mvsa.company.com)
  • companyname — Organization name
  • unitname — Organizational unit name
  • country — Country
  • calabel — Label for certificate authority (for example, CAKMSSERVER). 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 — RACF user ID associated with the SMC started task
  • serverdomainname — Domain name of the z/OS server (for example, MVSA.COMPANY.COM)
  • companyname — Organization name
  • unitname — Organizational unit name
  • country — Country
  • serverlabel — Label for the server certificate (for example, KMSSERVER)
  • calabel — Label for certificate authority, specified in the CA certificate definition. 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 — RACF user ID associated with the SMC started task
  • serverdomainname — Domain name of the z/OS server (for example, MVSA.COMPANY.COM)
  • companyname — Organization name
  • unitname — Organizational unit name
  • country — Country
  • clientlabel — Label for the client certificate (for example, KMSCLIENT)
  • calabel — Label for certificate authority, specified in the CA certificate definition. 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 — RACF user ID associated with the SMC started task.
  • calabel — Label for certificate authority, specified in the CA certificate definition
  • keyringname — Name of keyring, must match the Keyring specified in the PAGENT configuration

RACDCERT ID(stcuser) CONNECT(ID(stcuser) LABEL('serverlabel') RING('keyringname') DEFAULT USEAGE(PERSONAL)

where:

  • stcuser — RACF user ID associated with the SMC started task
  • serverlabel — Label for server certificate
  • keyringname — Name of keyring, must match the Keyring specified in the PAGENT configuration

RACDCERT ID(stcuser) CONNECT(ID(stcuser) LABEL('clientlabel') RING('keyringname') USEAGE(PERSONAL)

where:

  • stcuser — RACF user ID associated with the SMC started task
  • clientlabel — Label for client certificate
  • keyringname — Name of keyring, must match the Keyring specified in the PAGENT configuration

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 — Label for certificate authority, specified in the CA certificate definition
  • datasetname — Data set to receive the exported certificate

RACDCERT EXPORT (LABEL('clientlabel')) ID(stcuser) DSN('datasetname') FORMAT(PKCS12DER) PASSWORD('password')

where:

  • clientlabel — Label for the client certificate
  • stcuser — RACF user ID associated with the SMC started task
  • datasetname — Data set to receive the exported certificate
  • password — Password for data encryption. Needed when the certificate is received on the OKM. The password must 8 characters or more.

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.

RACF List Commands

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

Update OKM Cluster Information

After configuring the IBM mainframe, the z/OS systems programmer must provide information to the administrator of the OKM Cluster.

The administrator of the OKM Cluster enters the following information as the Master Key Provider settings in the Security Parameters panel of the OKM GUI.

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

Select "Off," "All Keys," or "Recover Keys Only." A value of "Off" means that the KMAs in this OKM Cluster create their own keys and do not derive keys from a Master Key Provider. A value of "All Keys" means that the KMAs in this OKM Cluster contact the Master Key Provider defined in the settings on this screen in order to create and retrieve master keys, and then use these master keys to derive keys for Agents. A value of "Recover Keys Only" means that the KMAs in this OKM Cluster contact the Master Key Provider defined in the settings on this screen to retrieve (but not create) master keys and then use these master keys to derive keys for Agents. The "All Keys" and "Recover Keys Only" values can be set only if the Replication Version is at least 11.

Master Key Rekey Period

Type the amount of time that defines how often this KMA should contact the Master Key Provider to create and retrieve new master keys. The default is 1 day. The minimum value is 1 day; maximum value is 25,185 days (approximately 69 years).

Master Key Provider Network Address

Type the host name or IP address of the host where the Master Key Provider resides.

Master Key Provider Port Number

Type the port number on which the Master Key Provider listens for requests from the KMAs in this OKM Cluster.

Master Key Provider Web App Path

Type the web application path that forms part of the URL for contacting the Master Key Provider (for example, "/cgi/smcgcsf").

OKM Certificate File Name

Specify the name of the file that contains the OKM certificate that was exported from the Master Key Provider host. The Master Key Provider uses this certificate to verify requests from KMAs in this OKM Cluster.

OKM Private Key File Name

Specify the name of the file that contains the OKM private key that was exported from the Master Key Provider host. The Master Key Provider uses this private key to verify requests from KMAs in this OKM Cluster.

OKM Private Key Password

Type the OKM private key password as it was generated on the Master Key Provider host. The Master Key Provider uses this private key password to verify requests from KMAs in this OKM Cluster.

CA Certificate File Name

Specify the name of the file that contains the CA (Certificate Authority) certificate that was exported from.