Migration from CICS SSL to AT-TLS

You can move an existing CICS® Transport Layer Security (TLS) (SSL) implementation for an inbound socket connection to Application Transparent Transport Layer Security (AT-TLS).

When CICS is used to establish a TLS (SSL) environment to perform a TLS handshake for an inbound socket connection, the attributes that are used for the handshake are extracted from two sources: region level SIT parameters and TCPIPSERVICE resource attributes.

The following two tables show the CICS SIT parameters and TCPIPSERVICE resource attributes that are used for a TLS handshake and their AT-TLS level equivalents.

Table 1. SIT parameters and AT-TLS equivalents
SIT Parameter	AT-TLS equivalents
MINTLSLEVEL	TLSv1 TLSv1.1 TLSv1.2
ENCRYPTION (deprecated: use MINTLSLEVEL)	TLSV1 TLSV1.1 TLSV1.2
KEYRING	TTLSKeyRingParms
CRLPROFILE	TTLSGskLdapParms
SSLDELAY	GSK_V3_SESSION_TIMEOUT
MAXSSLTCBS	Cannot be configured in AT-TLS; TCB numbers grow dynamically.
SSLCACHE=SYSPLEX	GSK_SYSPLEX_SIDCACHE ON
NISTSP800131A=CHECK	FIPS140 ON

Table 2. TCPIPSERVICE resource attributes and AT-TLS equivalents
TCPIPSERVICE resource attribute	AT-TLS equivalents
SSL=YES	HandShakeRole Server
SSL=CLIENTAUTH	HandShakeRole ServerWithClientAuth with ClientAuthType FULL ClientAuthType REQUIRED and ClientAuthType SAFCHECK are also supported.
CERTIFICATE	CertificateLabel
CIPHERS	TTLSCipherParms

Considerations for using keyrings

The CICS region user ID still requires access to the keyring that is specified in the AT-TLS policy. If you are migrating from CICS SSL to AT-TLS, you can continue to use the existing CICS-owned keyrings and reference them in the AT-TLS policies. If you want to set up new keyrings in TCPIP, the CICS region user ID will require access to this new keyring. The server certificate will remain as either a CICS-owned or SITE certificate.

Examples

The following examples show how to move an existing CICS TLS implementation to AT-TLS, and then remove the CICS TLS implementation.

Example 1: AT-TLS policy rules for TLS/SSL server authentication
Example 2: AT-TLS policy rules for TLS/SSL client authentication

Example 1: AT-TLS policy rules for TLS/SSL server authentication

An example configuration to use CICS to secure inbound HTTP connections might use simple server authentication on the TCPIPSERVICE resource (SSL(YES)). This configuration does not support client certificates. Figure 1 and Figure 2 show the CICS configuration statements that are needed to establish the CICS-TLS environment for simple server authentication.

Figure 1. CICS startup parameters

MINTLSLEVEL=TLS10  (or its deprecated equivalent ENCRYPTION=STRONG) 
KEYRING=CICSKeyRing (includes the certificate named CICS-2048-certificate) 
SSLDELAY=600
MAXSSLTCBS=8
SSLCACHE=CICS
NISTSP800131A=NOCHECK

Figure 2. SSL-related TCPIPSERVICE resource attributes

TCpipservice   : HTTPSSL                               
GROup          : JULESWEB                              
DEScription  ==> CICS WEB TCPIPSERVICE WITH SSL SUPPORT
POrtnumber   ==> 25008     
STatus       ==> Open        
PROtocol     ==> Http        
SSl          ==> Yes                
CErtificate  ==> CICS-2048-certificate 
CIphers      ==> 35363738392F303132330A1613100D15120F0C 
AUthenticate ==> Basic

To use AT-TLS to secure your inbound HTTP connections instead of CICS, you might use the following AT-TLS policy, and then update the TCPIPSERVICE resource definition to SSL(NO) or SSL(ATTLSAWARE).

Note: The following example AT-TLS policy uses the TLSV1.2 option, which is supported in z/OS® 2.1 and later. Using the TLSV1.2 option helps to achieve optimum performance; also, it is a prerequisite if you need to conform to NIST SP800-131A.

Full details of the NIST standards are available at the NIST Computer Security Resource Center (nist.gov).

Figure 3 shows the AT-TLS configuration that replicates the CICS environment for the TCPIPSERVICE named HTTPSSL.

Figure 3. AT-TLS configuration

TTLSRule SIMPLECICS
{
LocalPortRange 25008
Direction Inbound
Priority 256
TTLSGroupActionRef CICSGroupAct1
TTLSEnvironmentActionRef CICSEnvironmentAct1
}
TTLSGroupAction CICSGroupAct1
{
TTLSEnabled On
FIPS140 off
}
TTLSEnvironmentAction CICSEnvironmentAct1
{
HandShakeRole Server
TTLSKeyRingParmsRef CICSKeyRingParms1
TTLSCipherParmsRef CICSCipherParms1
TTLSEnvironmentAdvancedParmsRef CICSEnvAdvParms1
TTLSGskAdvancedParmsRef CICSGskAdvParms1
}
TTLSKeyRingParms CICSKeyRingParms1
{
Keyring CICSKeyRing
}
TTLSCipherParms CICSCipherParms1
{
V3CipherSuites TLS_RSA_WITH_AES_256_CBC_SHA
V3CipherSuites TLS_DH_DSS_WITH_AES_256_CBC_SHA
V3CipherSuites TLS_DH_RSA_WITH_AES_256_CBC_SHA
V3CipherSuites TLS_DHE_DSS_WITH_AES_256_CBC_SHA
V3CipherSuites TLS_DHE_RSA_WITH_AES_256_CBC_SHA
V3CipherSuites TLS_RSA_WITH_AES_128_CBC_SHA
V3CipherSuites TLS_DH_DSS_WITH_AES_128_CBC_SHA
V3CipherSuites TLS_DH_RSA_WITH_AES_128_CBC_SHA
V3CipherSuites TLS_DHE_DSS_WITH_AES_128_CBC_SHA
V3CipherSuites TLS_DHE_RSA_WITH_AES_128_CBC_SHA
V3CipherSuites TLS_RSA_WITH_3DES_EDE_CBC_SHA
V3CipherSuites TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA
V3CipherSuites TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA
V3CipherSuites TLS_DH_RSA_WITH_3DES_EDE_CBC_SHA
V3CipherSuites TLS_DH_DSS_WITH_3DES_EDE_CBC_SHA
V3CipherSuites TLS_DHE_RSA_WITH_DES_CBC_SHA
V3CipherSuites TLS_DHE_DSS_WITH_DES_CBC_SHA
V3CipherSuites TLS_DH_RSA_WITH_DES_CBC_SHA
V3CipherSuites TLS_DH_DSS_WITH_DES_CBC_SHA
}
TTLSEnvironmentAdvancedParms CICSEnvAdvParms1
{
SSLv3 Off
TLSV1 On
TLSV1.1 On
TLSV1.2 On
CertificateLabel CICS-2048-certificate 
}
TTLSGskAdvancedParms CICSGskAdvParms1
{
GSK_SYSPLEX_SIDCACHE off
GSK_V3_SESSION_TIMEOUT 600

}

Before you activate this AT-TLS policy, alter the CICS TCPIPSERVICE resource as follows:

TCpipservice   : HTTPSSL                               
GROup          : JULESWEB                              
DEScription  ==> CICS WEB TCPIPSERVICE WITH AT-TLS SSL SUPPORT
POrtnumber   ==> 25008     
STatus       ==> Open        
PROtocol     ==> Http       
SSl          ==> NO|ATTLSAWARE
CErtificate  ==> 
CIphers      ==> 
AUthenticate ==> Basic

If SSL is set to NO, CICS does not check whether AT-TLS is securing inbound client connections.

If SSL is set to ATTLSAWARE, CICS checks whether AT-TLS is securing inbound client connections. If a client connection is not secured by AT-TLS, it is rejected with an HTTP 403 error and message DFHWB0365 is written to the CICS log.

Also, if SSL is set to ATTLSAWARE, CICS checks for the presence of a client certificate. The previous example AT-TLS configuration does not support the use of client certificates. Therefore, ensure that the TCPIPSERVICE definition does not specify an AUTHENTICATE option that requires client certificates. The previous example TCPIPSERVICE resource specifies AUTHENTICATE(BASIC), which does not require a client certificate.

When the AT-TLS policy is active and the TCPIPSERVICE resource is redefined to remove the SSL attributes, you can also remove all the related SSL SIT parameters. However, first ensure that nothing else in the CICS region depends on these parameters.

If your CICS-SSL system is started with NISTSP800131A=CHECK, CICS sets MINTLSLEVEL=TLS12 and also sets FIPS140 on. To reflect these settings in the example AT-TLS POLICY configuration, modify it as follows:

TTLSGroupAction CICSGroupAct1
{
TTLSEnabled On 
FIPS140 on
}

TTLSEnvironmentAdvancedParms CICSEnvAdvParms1
{
SSLv3 Off 
TLSV1 Off
TLSV1.1 Off
TLSV1.2 On
CertificateLabel CICS-2048-certificate 
}

Example 2: AT-TLS policy rules for TLS/SSL client authentication

An example configuration to use CICS to secure inbound HTTP connections might use client authentication on the TCPIPSERVICE resource (SSL(CLIENTAUTH)).

This configuration supports client certificates. Figure 4 and Figure 5 show the CICS configuration statements that are needed to establish the CICS-TLS environment for client authentication.

Figure 4. CICS startup parameters

MINTLSLEVEL=TLS10  (or its deprecated equivalent ENCRYPTION=STRONG) 
KEYRING=CICSKeyRing (includes the certificate named CICS-2048-certificate) 
SSLDELAY=600
MAXSSLTCBS=8
SSLCACHE=CICS
NISTSP800131A=NOCHECK

Figure 5. SSL-related TCPIPSERVICE resource attributes

TCpipservice   : CLAUTH
GROup          : JULESWEB                              
DEScription  ==> CICS Web TCPIPSERVICE with SSL CLIENTAUTH support
POrtnumber   ==> 25009
STatus       ==> Open        
PROtocol     ==> Http        
SSl          ==> Clientauth
CErtificate  ==> CICS-2048-certificate 
CIphers      ==> 35363738392F303132330A1613100D15120F0C    
AUthenticate ==> Certificate

To use AT-TLS to secure your inbound HTTP connections instead of CICS, you might use the following AT-TLS policy, and then update the TCPIPSERVICE resource definition to use SSL(ATTLSAWARE).

Note: The following example AT-TLS policy uses the TLSV1.2 option, which is supported in z/OS 2.1 and later. Using the TLSV1.2 option helps to achieve optimum performance; also, it is a prerequisite if you need to conform to NIST SP800-131A.

Full details of the NIST standards are available at the NIST Computer Security Resource Center (nist.gov).

Figure 6 shows the AT-TLS client authentication configuration that replicates the CICS environment for the TCPIPSERVICE named CLAUTH.

Figure 6. AT-TLS client authentication configuration

TTLSRule CLIENTAUTHCICS
{
LocalPortRange 25009
Direction Inbound
Priority 256
TTLSGroupActionRef CICSGroupAct2
TTLSEnvironmentActionRef CICSEnvironmentAct2
}
TTLSGroupAction CICSGroupAct2
{
TTLSEnabled On
FIPS140 off
}
TTLSEnvironmentAction CICSEnvironmentAct2
{
HandShakeRole ServerWithClientAuth
TTLSKeyRingParmsRef CICSKeyRingParms2
TTLSCipherParmsRef CICSCipherParms2
TTLSEnvironmentAdvancedParmsRef CICSEnvAdvParms2
TTLSGskAdvancedParmsRef CICSGskAdvParms2
}
TTLSKeyRingParms CICSKeyRingParms2
{
Keyring CICSKeyRing
}
TTLSCipherParms CICSCipherParms2
{
V3CipherSuites TLS_RSA_WITH_AES_256_CBC_SHA
V3CipherSuites TLS_DH_DSS_WITH_AES_256_CBC_SHA
V3CipherSuites TLS_DH_RSA_WITH_AES_256_CBC_SHA
V3CipherSuites TLS_DHE_DSS_WITH_AES_256_CBC_SHA
V3CipherSuites TLS_DHE_RSA_WITH_AES_256_CBC_SHA
V3CipherSuites TLS_RSA_WITH_AES_128_CBC_SHA
V3CipherSuites TLS_DH_DSS_WITH_AES_128_CBC_SHA
V3CipherSuites TLS_DH_RSA_WITH_AES_128_CBC_SHA
V3CipherSuites TLS_DHE_DSS_WITH_AES_128_CBC_SHA
V3CipherSuites TLS_DHE_RSA_WITH_AES_128_CBC_SHA
V3CipherSuites TLS_RSA_WITH_3DES_EDE_CBC_SHA
V3CipherSuites TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA
V3CipherSuites TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA
V3CipherSuites TLS_DH_RSA_WITH_3DES_EDE_CBC_SHA
V3CipherSuites TLS_DH_DSS_WITH_3DES_EDE_CBC_SHA
V3CipherSuites TLS_DHE_RSA_WITH_DES_CBC_SHA
V3CipherSuites TLS_DHE_DSS_WITH_DES_CBC_SHA
V3CipherSuites TLS_DH_RSA_WITH_DES_CBC_SHA
V3CipherSuites TLS_DH_DSS_WITH_DES_CBC_SHA
}
TTLSEnvironmentAdvancedParms CICSEnvAdvParms2
{
SSLv3 Off
TLSV1 On
TLSV1.1 On
TLSV1.2 On
CertificateLabel CICS-2048-certificate 
ClientAuthType Full
}
TTLSGskAdvancedParms CICSGskAdvParms2
{
GSK_SYSPLEX_SIDCACHE off
GSK_V3_SESSION_TIMEOUT 600
}

Before you activate this example AT-TLS policy, alter the CICS TCPIPSERVICE resource definition as follows:

TCpipservice   : CLAUTH
GROup          : JULESWEB                              
DEScription  ==> CICS Web TCPIPSERVICE with SSL CLIENTAUTH support
POrtnumber   ==> 25009
STatus       ==> Open        
PROtocol     ==> Http        
SSl          ==> ATTLSAWARE
CErtificate  ==> 
CIphers      ==> 
AUthenticate ==> Certificate

In this example, SSL must be set to ATTLSAWARE so that CICS retrieves a client certificate from AT-TLS, because AUTHENTICATE is set to CERTIFICATE (a client certificate is required). If a client connection is not secured by AT-TLS, it is rejected with an HTTP 403 error and message DFHWB0365 is written to the CICS log.

With SSL(ATTLSAWARE), CICS checks for a client certificate. If this check maps to a RACF® USERID, CICS runs the web user transaction under this USERID.

The previous example AT-TLS policy is defined with ClientAuthType Full. This ClientAuthType replicates the SSL environment and handshake behavior that occurs when CICS uses SSL. However CICS also supports ClientAuthType Required and ClientAuthType SAFCheck.

CICS does not support the use of ClientAuthType PassThru. If a TCPIPSERVICE port is configured by using ClientAuthType PassThru and the TCPIPSERVICE resource is defined with SSL(ATTLSAWARE), when the first client connection arrives, CICS detects the unsupported configuration. CICS then closes the TCPIPSERVICE and issues message DFHSO0149.

If your CICS-SSL system is started with NISTSP800131A=CHECK, CICS sets MINTLSLEVEL=TLS12 and it also sets FIPS140 on. To reflect these settings in the example AT-TLS POLICY configuration, modify it as follows:

TTLSGroupAction CICSGroupAct2
{
TTLSEnabled On
FIPS140 on
}

TTLSEnvironmentAdvancedParms CICSEnvAdvParms2
{
SSLv3 Off
TLSV1 Off
TLSV1.1 Off
TLSV1.2 On
CertificateLabel CICS-2048-certificate 
ClientAuthType Full
}