Migrating from CICS SSL to AT-TLS, example configurations

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 on the handshake are extracted from two sources; region level SIT parameters and TCPIPSERVICE resource parameters.

These tables show the two sets of CICS parameters and their AT-TLS level equivalents.

Table 1. SIT parameters with their AT-TLS equivalents
SIT Parameters	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	Not configurable in AT-TLS - TCB numbers grow dynamically
SSLCACHE=SYSPLEX	GSK_SYSPLEX_SIDCACHE ON
NISTSP800131A=CHECK	FIPS140 ON

Table 2. TCPIPSERVICE resource and AT-TLS equivalents
TCPIPSERVICE resource	AT-TLS equivalents
SSL=YES	HandShakeRole Server
SSL=CLIENTAUTH	HandShakeRole ServerWithClientAuth plus ClientAuthType FULL (although both ClientAuthType REQUIRED and ClientAuthType SAFCHECK are also supported).
CERTIFICATE	CertificateLabel
CIphers	TTLSCipherParms

Here are two examples, which show how to take existing CICS TLS implementations and move the TLS implementation into AT-TLS. The CICS TLS implementation can then be removed.

Example 1 - Coding the AT-TLS policy rules for TLS/SSL server authentication.

Here, the CICS configuration statements that are needed to establish the CICS-TLS environment when you are using simple server authentication, SSL(YES) on the TCPIPSERVICE. There is no support for client certificates with this setup. You might have this configuration if you are using CICS instead of AT-TLS to secure your inbound HTTP connections:

CICS startup parameters when using CICS to implement SSL support for server authentication.

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

TCPIPSERVICE when using CICS to implement SSL support for server authentication (showing selective SSL related parameters)..

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

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

Note: The following AT-TLS policy uses TLSV1.2 and this AT-TLS option is only supported from z/OS® 1.13. The use of TLSV1.2 helps to achieve optimum performance and it is also a prerequisite if you need to conform to NIST SP800-131A.

Full details of the NIST standards are available at the National Institute of Standards and Technology website (csrc.nist.gov).

AT-TLS configuration which replicates the CICS environment for the TCPIPSERVICE named HTTPSSL.

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 the AT-TLS policy (shown previously), you would need to alter the CICS TCPIPSERVICE, listed here:

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, then CICS does not check whether AT-TLS is securing inbound client connections.

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

When SSL(ATTLSAWARE) is specified, CICS checks for the presence of a client certificate. With the AT-TLS configuration (shown previously), the use of client certificates is not supported. Ensure that the TCPIPSERVICE definition does not specify an AUTHENTICATE option, which requires client certificates. The previous example uses AUTHENTICATE(BASIC), which does not require a client certificate.

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

If your CICS-SSL system is started with NISTSP800131A=CHECK, then CICS sets MINTLSLEVEL=TLS12 and also sets FIPS140 on. To reflect this setting in the AT-TLS POLICY configuration (previously referred to), make the following modifications:

TTLSGroupAction CICSGroupAct1
{
TTLSEnabled On 
FIPS140 on
}

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

Example 2 - Coding the AT-TLS policy rules for TLS/SSL client authentication.

Here are the CICS configuration statements that are needed to establish the CICS-TLS environment when you are using client authentication SSL(CLIENTAUTH) on the TCPIPSERVICE, which supports client certificates. You might have this configuration if you are using CICS instead of AT-TLS to secure your inbound HTTP connections:

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

TCPIPSERVICE listing selective SSL related parameters.

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

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

Note: The following AT-TLS policy uses TLSV1.2 and this AT-TLS option is only supported from z/OS V2R1.0. The use of TLSV1.2 helps to achieve optimum performance and it is also a prerequisite if you need to conform to NIST SP800-131A.

Full details of the NIST standards are available at the National Institute of Standards and Technology website (csrc.nist.gov).

Client authentication AT-TLS configuration which replicates the CICS environment for the TCPIPSERVICE named CLAUTH.

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 the AT-TLS policy (shown previously), you would need to alter the CICS TCPIPSERVICE 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. The reason is because the AUTHENTICATE option is set to CERTIFICATE and CICS retrieves a client certificate from AT-TLS when you are using SSL(ATTLSAWARE). 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 the presence of a client certificate. If this check maps to a RACF® USERID then CICS runs the web user transaction under this USERID. The TCPIPSERVICE (shown previously), uses AUTHENTICATE(CERTIFICATE), which requires a client certificate be present.

In Example 2, the AT-TLS policy was defined with ClientAuthType Full. This ClientAuthType replicates the SSL environment and handshake behavior, which is seen when CICS uses SSL. However, both ClientAuthType Required and ClientAuthType SAFCheck are also supported by CICS.

The use of ClientAuthType PassThru is not supported by CICS. If a TCPIPSERVICE port is configured by using ClientAuthType PassThru and the TCPIPSERVICE is defined with SSL(ATTLSAWARE), then CICS detects the unsupported configuration when the first client connects arrives. CICS closes the TCPIPSERVICE and issues message DFHSO0149, if it happens.

If your CICS-SSL system is started with NISTSP800131A=CHECK, then CICS sets MINTLSLEVEL=TLS12 and it also sets FIPS140 on. To reflect this setup in the AT-TLS POLICY configuration (shown previously), make the following modifications:

TTLSGroupAction CICSGroupAct2
{
TTLSEnabled On
FIPS140 on
}

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