Enabling secure communication

1. Create a RACF key ring for Debug Profile Service to use as its keystore:

   RACDCERT ADDRING(EQAPROF.Keyring) ID(STCEQA)

2. Create a CA certificate and add it to the key ring:

   RACDCERT GENCERT CERTAUTH SUBJECTSDN(CN('CA for Debugger Services') O('IBM') OU('IBM z/OS Debugger') C('US')) SIZE(2048) WITHLABEL('zosDebuggerCA') NOTAFTER(DATE(2030-12-31))
   RACDCERT CONNECT(CERTAUTH RING(EQAPROF.Keyring) LABEL('zosDebuggerCA')) ID(STCEQA)

3. Create a signed personal certificate and add to the key ring:

   RACDCERT GENCERT SUBJECTSDN(CN('Debug Profile Service') O('IBM') OU('IBM z/OS Debugger') C('US')) ALTNAME(DOMAIN('dps.hostname.com')) SIZE(2048) SIGNWITH(CERTAUTH LABEL('zosDebuggerCA')) WITHLABEL('EQAPROF') NOTAFTER(DATE(2030-12-31)) ID(STCEQA)
   RACDCERT CONNECT(RING(EQAPROF.Keyring) LABEL('EQAPROF')) ID(STCEQA)

4. Confirm that the key ring and certificates were created correctly:

   RACDCERT LISTRING(EQAPROF.Keyring) ID(STCEQA)
   RACDCERT CERTAUTH LIST(LABEL('zosDebuggerCA'))
   RACDCERT LIST(LABEL('EQAPROF')) ID(STCEQA)

5. Enable the protected user ID STCEQA authority to access the key ring:

   PERMIT IRR.DIGTCERT.LIST CLASS(FACILITY) ID(STCEQA) ACC(READ)
   PERMIT IRR.DIGTCERT.LISTRING CLASS(FACILITY) ID(STCEQA) ACC(READ)
   SETROPTS RACLIST(FACILITY) REFRESH

6. Edit /etc/debug/eqaprof.env and update the keystore variables to use the key ring:

   keystoreFile="safkeyringjce://STCEQA/EQAPROF.Keyring"
   keystorePass="password"
   keystoreType="JCERACFKS"

   Similar to JCERACFKS, a JCECCARACFKS key ring uses RACF with the addition of ICSF to protect certificates and key material. To use a JCECCARACFKS key ring, edit /etc/debug/eqaprof.env with the following:

   keystoreFile="safkeyringjcecca://STCEQA/EQAPROF.Keyring"
   keystorePass="password"
   keystoreType="JCECCARACFKS"

   Notes:

   • The value for keystorePass must be exactly "password" to satisfy the underlying HTTP server, even though SAF key rings do not have a password.
   • Access to ICSF is protected by profiles in the CSFSERV security class. The protected user ID STCEQA must have the proper permissions in order to access the key ring. For more information, see the z/OS Cryptographic Services ICSF Administrator's Guide.
7. Export the CA certificate that contains the public key to a z/OS sequential file:

   RACDCERT CERTAUTH EXPORT(LABEL('zosDebuggerCA')) DSN('<sequential data set>') FORMAT(CERTDER)

   The CA certificate can be distributed to remote users to be imported into the client keystore manually if necessary.

   For Eclipse users, manually importing the certificate for z/OS Debugger Profiles view users is not required because users will be prompted to accept the certificate if it is not already in the keystore the first time the view connects to Debug Profile Service.

   users still need to manually import the self-signed certificate.

1. In the eqaprof.env configuration file, specify SECURE="AT-TLS".
2. Create an AT-TLS policy for the port used by Debug Profile Service as specified in the eqaprof.env configuration file. See the following sample policy.
   Note: The Jobname parameter in the TTLSRule statement is optional if you specify the LocalPortRange. However, if you choose to define it, set it to the job name shown in the output stream of the EQAPROF job. The EQAPROF job spawns a secondary process that runs the Liberty server.

   For example, the job name should be set to EQAPROF1:

   INFO EqaProfile - Server running with jobname EQAPROF1 has started, and is listening on
           HTTPS (AT-TLS) port=8143

   You can also run the TSO NETSTAT command to verify the server’s job name and check which job is listening on port 8143.

   TTLSRule EQAPROF
   {
        LocalPortRange               8143
        Direction Inbound
        TTLSGroupActionRef.          EQAPROF_group
        TTLSEnvironmentActionRef     EQAPROF_env
        TTLSConnectionActionRef      EQAPROF_conn
   }
   
   TTLSGroupAction  EQAPROF_group
   {
        TTLSEnabled                  On
   }
   
   TTLSEnvironmentAction EQAPROF_env
   {
        HandshakeRole                Server
        TTLSKeyringParms
        {
             # Keyring must be owned by the user id (STCEQA) running the EQAPROF started task
             Keyring                 eqaprof.keyring
        }
   }
   
   TTLSConnectionAction  EQAPROF_conn
   {
        HandshakeRole                                 Server
        TTLSCipherParmsRef                            EQAPROF_cipherparms
        TTLSConnectionAdvancedParmsRef.               EQAPROF_Conn_adv
        CtraceClearText                               Off
   }
   
   TTLSConnectionAdvancedParms EQAPROF_Conn_adv
   {
        TLSv1                         Off
        TLSv1.1                       Off
        TLSv1.2                       On
        SSLV3                         Off
        ApplicationControlled         Off
        SecondaryMap                  Off
        HandshakeTimeout.             20
   }
   
   TTLSCipherParms   EQAPROF_cipherparms
   {
        V3CipherSuites TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
        V3CipherSuites TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
        V3CipherSuites TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
        V3CipherSuites TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
        V3CipherSuites TLS_DHE_RSA_WITH_AES_256_GCM_SHA384
        V3CipherSuites TLS_DHE_RSA_WITH_AES_128_GCM_SHA256
   }

Option 1: Using the default encryption key:

${liberty_dir}/bin/securityUtility encode --encoding=aes <password>

Option 1: Use the encrypted password directly:

keystorePass="{aes}..."

Option 2: Reference an external file containing the encrypted password.

keystorePassFile="/etc/debug/keystore.password"

keystorePassEncryptionKeyfile="/etc/debug/encryption.key"

chown STCEQA:STCGROUP keystore.password
chown STCEQA:STCGROUP encryption.key
chmod 600 keystore.password
chmod 600 encryption.key