Configure an AT-TLS profile for HTTPS on the z/OS® system you want to use for the IBM® MFA web services started task.
You must satisfy the following prerequisites before you configure an AT-TLS profile:
- You must have already installed and configured z/OS
Communications Server and should be familiar with Application Transparent Transport Layer Security
(AT- TLS) policies.
Important: A sample AT-TLS policy is included in
SYS1.SAZFSAMP(AZFTTLSX). IBM strongly
recommends that if you are not already familiar with AT-TLS policies, you should start with this
sample. User changeable parameters are indicated by ?XYZ?
.
- This procedure assumes that you are using a public CA. It is strongly recommended that you use a
certificate issued by a well-known certificate authority (CA).
- Subject Alternative Name (SAN) is an extension to X.509 that allows multiple values (email
addresses, IP addresses, DNS host names, and so forth) that a certificate should match to be
associated with the certificate using a subjectAltName field. When ordering server certificates to
use with IBM MFA web services, ensure that you specify
Subject Alternate Names that cover all names that a user may enter into their browser to reach the
server. For example, assume you have an LPAR named LP13 with two TCP/IP stacks,
and the host names are lp13 and lp13tcpip2. The Subject
Alternate Name attributes should be as follows. The DNS names and IP addresses are for example
purposes only.
DNS Name=lp13.yourcompany.com
DNS Name=lp13
DNS Name=lp13tcpip2.yourcompany.com
DNS Name=lp13tcpip2
DNS Name=10.168.54.96
DNS Name=192.168.55.113
IP Address=10.168.54.96
IP Address=192.168.55.113
When
you specify Subject Alternate Names, the base Subject Distinguished Name (DN)
CN attribute is not used by the browser to validate the certificate. See https://tools.ietf.org/html/rfc6125 for reference
information.
This procedure briefly summarizes the steps to create an AT-TLS policy for your convenience. See
z/OS Communications Server: IP Configuration Guide
and
z/OS Communications Server: IP Configuration Reference
for complete information.
You might also find (IBM
z/OS V2R1 Communications Server TCP/IP Implementation Volume
4: Security and Policy-Based Networking
http://www.redbooks.ibm.com/redbooks/pdfs/sg248099.pdf)
to be a useful resource.
About this task
AT-TLS policy conditions consist of a variety of selection criteria that act as filters for
AT-TLS rules. Traffic can be filtered based on local addresses, remote addresses, local port range,
remote port range, job name, user identification, and direction.
On the z/OS system you want to use for the
IBM MFA web services started task, perform the following
tasks:
Important: The ALTNAME portion of the
SYS1.SAZFSAMP(AZFTTLSX) sample describes how to specify more than one IP
address to contact the IBM MFA server.
- Create the certificate authority if you do not already have one. This
command creates a new CA certificate (and private key) and adds it to the CERTAUTH store. Replace
?CA-yyyy-mm-dd? with the preferred expiration date of the CA certificate.
RACDCERT GENCERT CERTAUTH SUBJECTSDN(CN('MFA CERT AUTH')) SIZE(2048)
NOTAFTER(DATE(?CA-yyyy-mm-dd?)) WITHLABEL('server cert root CA label')
KEYUSAGE(CERTSIGN)
-
Refresh the RACF® DIGTCERT class.
SETROPTS RACLIST(DIGTCERT) REFRESH
- It is a best practice to also create an intermediate certificate authority
if you do not already have one. This command creates a new intermediate CA certificate (and private
key) and adds it to the CERTAUTH store. Replace ?CA-yyyy-mm-dd? with the
preferred expiration date of the CA certificate.
RACDCERT GENCERT CERTAUTH SUBJECTSDN(CN('MFA INTERMEDIATE CERT AUTH')) SIZE(2048)
NOTAFTER(DATE(?CA-yyyy-mm-dd?)) WITHLABEL('server intermediate CA label')
SIGNWITH(CERTAUTH LABEL('server cert root CA label')) KEYUSAGE(CERTSIGN)
-
Refresh the RACF DIGTCERT class.
SETROPTS RACLIST(DIGTCERT) REFRESH
- Create the MFA web services certificate if you do not already have one.
This command creates a new end-entity certificate (and private key). In this example
AZFWEB is the user ID of the web services AZF#IN01 started task.
RACDCERT GENCERT ID(AZFWEB) SUBJECTSDN( CN('MFA WEB SERVICES') ) SIZE(2048)
NOTAFTER(DATE(2050-12-31)) WITHLABEL('server cert label')
SIGNWITH(CERTAUTH LABEL('server intermediate CA label')) KEYUSAGE(HANDSHAKE DOCSIGN)
ALTNAME(IP(numeric-ip-address) DOMAIN('numeric-ip-address') DOMAIN('dns-name')
DOMAIN('hostname'))
-
Refresh the RACF DIGTCERT class.
SETROPTS RACLIST(DIGTCERT) REFRESH
-
Create the server key ring with the server certificate and necessary certificate authority
certificates.
For System SSL, use a SAF key ring. This is typically a RACF key ring. RACF supports multiple PKI private keys
and certificates to be managed as a group. These groups are called key rings.
Create the SAF key ring with the
RACDCERT ADDRING command, where
AZFWEB is the user ID of the web services started task.
RACDCERT ADDRING (ring-name) ID(AZFWEB)
-
Refresh the RACF DIGTRING class.
SETROPTS RACLIST(DIGTRING) REFRESH
-
Connect the certificate chain to the key ring.
RACDCERT ID(AZFWEB)
CONNECT(LABEL('server cert label') RING(ring-name))
RACDCERT ID(AZFWEB)
CONNECT(LABEL('intermediate root CA label') RING(ring-name))
RACDCERT ID(AZFWEB) CONNECT(CERTAUTH
LABEL('root CA label') RING(ring-name))
-
Refresh the RACF DIGTRING class.
SETROPTS RACLIST(DIGTRING) REFRESH
-
Use the RACDCERT LISTRING command to list the key ring.
RACDCERT ID(AZFWEB) LISTRING(ring-name)
-
Create Policy Agent files.
-
Create a Policy Agent main configuration file containing a TcpImage statement for the server
stack.
-
Create a Policy Agent image configuration file for the server stack.
-
If AT-TLS policies are to be retrieved from the policy server, create image-specific AT-TLS
configuration files, and optionally, common AT-TLS configuration files, on the policy server.
-
Add AT-TLS configuration.
-
For local AT-TLS policies, add a TTLSConfig statement to the Policy Agent
image configuration file, identifying the TTLSConfig policy file location:
-
For remote AT-TLS policies, add a PolicyServer statement to the policy
client image configuration file:
PolicyServer
{
ClientName name
PolicyType TTLS
{
…
}
…
}
-
Add a DynamicConfigPolicyLoad statement to the policy server main
configuration file:
DynamicConfigPolicyLoad clientname
{
PolicyType TTLS
{
PolicyLoad serverpath
}
…
}
-
Add the AT-TLS policy statements to the serverpath file. Specific lines in
the example are numbered to the right so that you can associate them with the notes that follow.
Important: This example is a fragment extracted from the complete sample AT-TLS policy
included in SYS1.SAZFSAMP(AZFTTLSX).
TTLSRule AZFSrvAuthRule
{
LocalAddr ALL
RemoteAddr ALL
LocalPortRange ?serverAuthPort? a
Direction Inbound
Priority 255
TTLSGroupActionRef AZFGroupAction1
TTLSEnvironmentActionRef AZFEnvAction1
TTLSConnectionActionRef AZFConnAction1
}
TTLSKeyringParms AZFKeyringParms
{
Keyring ?keyringName? b
}
TTLSGroupAction AZFGroupAction1
{
TTLSEnabled On
Trace 255
}
TTLSEnvironmentAction AZFEnvAction1
{
HandshakeRole Server
EnvironmentUserInstance 0
TTLSEnvironmentAdvancedParmsRef AZFEnvAdvServer
TTLSKeyringParmsRef AZFKeyringParms
Trace 255
}
TTLSConnectionAction AZFConnAction1
{
TTLSCipherParmsRef AZFCipherParms c
TTLSConnectionAdvancedParmsRef AZFConnAdvParms1
CtraceClearText Off
Trace 255
}
TTLSEnvironmentAdvancedParms AZFEnvAdvServer
{
ClientAuthType PassThru
ApplicationControlled Off
SSLv2 Off
SSLv3 Off
TLSv1 Off
TLSv1.1 Off
TLSv1.2 On
TLSv1.3 On
}
TTLSConnectionAdvancedParms AZFConnAdvParms1
{
ApplicationControlled Off
SecondaryMap Off
}
TTLSCipherParms AZFCipherParms c
{
V3CipherSuites TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256
V3CipherSuites TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384
V3CipherSuites TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
V3CipherSuites TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384
V3CipherSuites TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
V3CipherSuites TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
V3CipherSuites TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
V3CipherSuites TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
}
Callout Notes:
- You need to specify this port when you run AZFEXEC to configure the IBM MFA web services started task.
- The name of the SAF key ring you created.
- Use this specific set of ciphers to be compatible with an Apple Touch ID device.
-
Set up InitStack access control:
-
Define the EZB.INITSTACK.sysname.tcpname profile for each AT-TLS
stack.
-
Permit administrative applications to use the stack before AT-TLS is initialized.
For examples of the security product commands needed to create this resource profile name and
grant users access to it, see member EZARACF in sample data set SEZAINST.
-
Enable AT-TLS. Set TCPCONFIG TTLS in PROFILE.TCPIP.