RACF Configuration

RACF configuration requires the assistance of your RACF and networking administrators. The two main components in this part of the configuration are a personal certificate and the AT-TLS rules that control which ports are to be secured.

Personal Certificate

To configure RACF, you must have a personal certificate and the user ID which starts the CICS region, and you also must be granted read access to this certificate.

The personal certificate must be created by your RACF administrator using RACF commands similar to those shown in the following example. Note that the exact requirements depend on your system version, configuration, and site standards.
Note: Much of this is completely familiar to your RACF administrator who has to customize this approach to your local situation. For example, it is very likely that you already have a CA with which to sign the personal certificate, making that part of the job unnecessary. Also, you want names that make sense to your organization.

Example

The following JCL illustrates the requirements for one possible configuration. In this example, the certificate named BWCP_Server_Cert is the personal certificate that is used to secure the connection. It has been exported with its private key included as a P12 file.

The signing certificate TIBCO Software Inc CA is exported as a DER-formatted certificate without its private key because it is not needed. It is unnecessary to expose the signing certificate outside of RACF.

This sample sets up the keyring, generates the certificates, and exports the certificates for downloading to the client: 
//#JOBNAME JOB (&SYSUID),'CERT CREATE',CLASS=A
//GENCERT EXEC PGM=IKJEFT01 
//SYSTSPRT DD SYSOUT=* 
//SYSTSIN DD *
RACDCERT GENCERT CERTAUTH - 
SUBJECTSDN( - 
OU('TIBCO Software Inc CA') - 
CN('TIBCO Software Inc Mainframe Server Root CA') -
O('TIBCO Software Inc.') - 
L('Palo Alto') - 
SP('CA') - 
C('US') ) - 
SIZE(2048) - 
NOTAFTER( DATE(2030-02-04) TIME(23:59:59) ) - 
WITHLABEL('TIBCO Software Inc CA') - 
KEYUSAGE(CERTSIGN HANDSHAKE DATAENCRYPT DOCSIGN) 
RACDCERT ID(TCPIP) GENCERT - This id may be an id you use to own all of your application certs if you choose 
SUBJECTSDN( - 
OU('BWCP_Server_Cert') - 
O('TIBCO Software Inc.') - 
L('Palo Alto') - 
SP('CA') - 
C('US') ) - 
SIZE(4096) - See IBM RACDCERT GENCERT doc on this. Allowed maximum values: 512, 1024, 2048, 4096 
NOTAFTER( DATE(2030-02-04) TIME(15:50:00) ) - 
WITHLABEL('BWCP_Server_Cert') - 
SIGNWITH(CERTAUTH LABEL('TIBCO Software Inc CA')) - Use this as the LABEL in subsequent CONNECT and EXPORT commands
KEYUSAGE(HANDSHAKE DATAENCRYPT DOCSIGN) 
RACDCERT ID(TIBUSER) ADDRING(Personal_TIBUSER) 
RACDCERT CONNECT(CERTAUTH LABEL('TIBCO Software Inc CA') -
RING(Personal_TIBUSER) USAGE(CERTAUTH)) ID(TIBUSER) 
RACDCERT CONNECT(ID(TIBUSER) LABEL('BWCP_Server_Cert') + 
RING(Personal_TIBUSER) DEFAULT) ID(TIBUSER) 
SETROPTS RACLIST(DIGTCERT, DIGTRING) REFRESH 

To export the certificate and the signing CA to datasets for transfer to the client:
//EXPORT EXEC PGM=IKJEFT01,COND=(2,LT) 
//SYSTSPRT DD SYSOUT=* 
//SYSTSIN DD * 
RACDCERT EXPORT(LABEL('BWCP_Server_Cert')) ID(TCPIP) - 
FORMAT(PKCS12DER) DSN('TIBUSER.BWCP.SERVER.CERT.DER') - 
PASSWORD('password') 
RACDCERT EXPORT(LABEL('TIBCO Software Inc CA')) CERTAUTH - 
FORMAT(CERTDER) DSN('TIBUSER.BWCP.CA.DER') 
/* 
//

AT-TLS Configuration with Rules

After the personal certificate is created, you must configure the z/OS TCP/IP stack application transparent TLS feature to secure the connection.

AT-TLS can secure a single port or a range of ports using a single set of rules. Provided that the use of a single certificate is acceptable for all connections to CICS regions on your z/OS system, you can allocate a range of ports and accomplish the whole task with one set of rules.
Note: With the plug-in, you can define several CICS regions in one region resource definition. If such a region definition uses AT-TLS to secure its connections, all CICS regions must use the same certificate to secure their ports.

AT-TLS configuration is covered in the z/OS Communications Server bookshelf, which even includes a configuration assistant to simplify the process.

With the assistance of your z/OS network administrator, you might customize the set of rules shown in the following example so that your port or ports are secured by the personal certificate created previously.

Example

This example shows a set of AT-TLS rules customized to configure ports for use with the personal certificate created in the previous example. Your z/OS network administrator is familiar with the documentation required to make the customizations needed for your system. Note that, to make the necessary customization, you must be aware of the keyring, label, and personal certificate name stored in RACF. 
TTLSGroupAction grp_Action 
{ 
TTLSEnabled On 
Trace 2 # Log Errors to syslogd 
} 
# Common StartUp Group that new Rules may use 
# Shows how each connection maps to policy 
TTLSGroupAction grp_StartUp 
{ 
TTLSEnabled On 
Trace 6 # Log Errors and Info messages to syslogd 
} 
# Common Diagnostic Group that a problem Rule may use 
# Shows AT-TLS events and result of each System SSL call 
TTLSGroupAction grp_Diagnostic 
{ 
TTLSEnabled On 
Trace 255 # Log Error, Info, Event and Flow to syslogd 
} 
# Common Environment that most servers could use 
TTLSEnvironmentAction Generic_Server_Env 
{ 
HandshakeRole Server 
TTLSKeyRingParms 
{ 
Keyring Server_Ring 
} 
} 
################################################################### 
# # 
# BWCP Specific Rules and Actions # 
# # 
################################################################### 
# Server # 
################################################################### 
TTLSRule BWCP_Server 
{ 
LocalAddr ALL 
RemoteAddr ALL 
LocalPortRange 6810-6819 
RemotePortRange 1024-65535 
# Jobname (do not know, do not care) 
Direction Inbound 
Priority 255 
TTLSGroupActionRef grp_Action 
TTLSEnvironmentActionRef BWCP_Env_Action_Server 
TTLSConnectionActionRef BWCP_Connection_Action_Server 
} 
# BWCP Environment 
TTLSEnvironmentAction BWCP_Env_Action_Server 
{ 
HandshakeRole Server 
TTLSKeyringParms 
{ 
# In this configuration (non-z/OS client), this cannot be a shared 
# keyring with a site certificate. It must be a keyring and 
# certificate owned by the userid assigned to the application. 
# 
Keyring Personal_TIBUSER 
} 
} 
# BWCP Connections 
TTLSConnectionAction BWCP_Connection_Action_Server 
{ 
HandshakeRole Server 
TTLSCipherParms 
{ 
V3CipherSuites TLS_RSA_WITH_AES_256_CBC_SHA 
V3CipherSuites TLS_RSA_WITH_AES_128_CBC_SHA 
V3CipherSuites TLS_RSA_WITH_3DES_EDE_CBC_SHA 
} 
TTLSConnectionAdvancedParms 
{ 
ApplicationControlled Off 
HandshakeTimeout 10 
ResetCipherTimer 0 
SecondaryMap Off 
} 
CtraceClearText Off 
Trace 3 
} 
################################################################### 
# Client # 
################################################################### 
TTLSRule OSB_Client 
{ 
LocalAddr ALL 
RemoteAddr ALL 
LocalPortRange 6810-6819 
RemotePortRange 1024-65535 
# LocalPortRange 0 # any local port, we are not sure
# RemotePortRange 0 # any remote port, we are not sure
# Jobname (not applicable) 
Direction Outbound 
Priority 255 
TTLSGroupActionRef grp_Action 
TTLSEnvironmentActionRef BWCP_Env_Action_Client 
TTLSConnectionActionRef BWCP_Connection_Action_Client 
} 
# BWCP Environment 
TTLSEnvironmentAction BWCP_Env_Action_Client 
{ 
HandshakeRole Client 
TTLSKeyringParms 
{ 
# In this configuration (non-z/OS client), this cannot be a shared 
# keyring with a site certificate. It must be a keyring and 
# certificate owned by the userid assigned to the application. 
# 
Keyring Personal_TIBUSER 
} 
} 
# BWCP Connections 
TTLSConnectionAction BWCP_Connection_Action_Client 
{ 
HandshakeRole Client 
TTLSCipherParms 
{ 
V3CipherSuites TLS_RSA_WITH_AES_256_CBC_SHA 
V3CipherSuites TLS_RSA_WITH_AES_128_CBC_SHA 
V3CipherSuites TLS_RSA_WITH_3DES_EDE_CBC_SHA 
} 
TTLSConnectionAdvancedParms 
{ 
ApplicationControlled Off 
HandshakeTimeout 10 
ResetCipherTimer 0 
SecondaryMap Off 
} 
CtraceClearText Off 
Trace 3 
}