Configure an AT-TLS profile

Configure an AT-TLS profile for HTTPS on the z/OS® system you want to use for the IBM® MFA web services started task.

Before you begin

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.

Procedure

  1. 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)
  2. Refresh the RACF® DIGTCERT class.
    SETROPTS RACLIST(DIGTCERT) REFRESH
  3. 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)
  4. Refresh the RACF DIGTCERT class.
    SETROPTS RACLIST(DIGTCERT) REFRESH
  5. 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'))
  6. Refresh the RACF DIGTCERT class.
    SETROPTS RACLIST(DIGTCERT) REFRESH
  7. 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)
  8. Refresh the RACF DIGTRING class.
    SETROPTS RACLIST(DIGTRING) REFRESH
  9. 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))
  10. Refresh the RACF DIGTRING class.
    SETROPTS RACLIST(DIGTRING) REFRESH
  11. Use the RACDCERT LISTRING command to list the key ring.
    RACDCERT ID(AZFWEB)  LISTRING(ring-name)
  12. Create Policy Agent files.
    1. Create a Policy Agent main configuration file containing a TcpImage statement for the server stack.
    2. Create a Policy Agent image configuration file for the server stack.
    3. 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.
  13. Add AT-TLS configuration.
    1. For local AT-TLS policies, add a TTLSConfig statement to the Policy Agent image configuration file, identifying the TTLSConfig policy file location:
      TTLSConfig	serverpath
    2. For remote AT-TLS policies, add a PolicyServer statement to the policy client image configuration file:
      PolicyServer
      {
         ClientName  name
         PolicyType  TTLS
         {
            …
         }
         …
      }
    3. Add a DynamicConfigPolicyLoad statement to the policy server main configuration file:
      DynamicConfigPolicyLoad  clientname
      {
         PolicyType TTLS
         {
            PolicyLoad  serverpath
         }
         …
      }
  14. 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:
    1. You need to specify this port when you run AZFEXEC to configure the IBM MFA web services started task.
    2. The name of the SAF key ring you created.
    3. Use this specific set of ciphers to be compatible with an Apple Touch ID device.
  15. Set up InitStack access control:
    1. Define the EZB.INITSTACK.sysname.tcpname profile for each AT-TLS stack.
    2. 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.
  16. Enable AT-TLS. Set TCPCONFIG TTLS in PROFILE.TCPIP.