RACF Configuration

This procedure 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 userid which starts the CICS region must have read access to this certificate.

The personal certificate should be created by your RACF administrator create a personal certificate, using RACF commands similar to those shown in the example below. Note that the exact requirements depend on your system version, configuration, and site standards.

 

Much of this are completely familiar to your RACF administrator and he/she has to customize this approach to your local situation. For instance, 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, Cloud Software Group, Inc.CA is exported as a DER-formatted certificate without its private key because it is not needed. There is no need 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('Cloud Software Group, Inc.CA') -

CN('Cloud Software Group, Inc.Mainframe Server Root CA') -

O('Cloud Software Group, Inc.') -

L('Palo Alto') -

SP('CA') -

C('US') ) -

SIZE(2048) -

NOTAFTER( DATE(2030-02-04) TIME(23:59:59) ) -

WITHLABEL('Cloud Software Group, 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('Cloud Software Group, 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('Cloud Software Group, 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('Cloud Software Group, 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('Cloud Software Group, Inc.CA')) CERTAUTH -

FORMAT(CERTDER) DSN('TIBUSER.BWCP.CA.DER')

/*

//

---

 

AT-TLS Configuration with Rules

Once the personal certificate has been created, you must configure the z/OS TCP/IP stack's 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. As long as 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.

The Plug-in allows you to define several CICS regions in one region resource definition. If such a region definition uses AT-TLS to secure its connections, then 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 may customize the set of rules shown in the example below 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 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 certificatecertificatecertificate. 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

}

---