Enabling secure communication

You can enable Debug Profile Service to communicate via a Secure Sockets Layer (SSL) certificate with a private key and self-signed certificate stored in a keystore file , a Certificate Authority (CA) certificate with a RACF managed key ring, or AT-TLS.

Remote clients such as the z/OS Debugger Profiles view might perform hostname verification when communicating with Debug Profile Service. Make sure that the hostname is defined in the Subject Alternative Name (SAN) extension of the SSL certificate.

Enabling secure communication with a keystore file

You can use the sample keystore file installed in /etc/debug/keystore.p12, or create a new one with the following steps:

  1. Create a keystore file by using the Java runtime utility keytool:
    keytool -genkey -alias liberty -keyalg RSA -storetype PKCS12 -keystore keystore.p12 -ext "SAN=DNS:`/bin/hostname`"
  2. Edit /etc/debug/eqaprof.env and update the keystore variables to use the new keystore file.
  3. To ensure that the keystore file is only readable by the protected user ID STCEQA, change the owner and permission of the file with:
      chown STCEQA:STCGROUP keystore.p12
      chmod 640 keystore.p12
  4. Export the SSL certificate with:
    keytool -export -keystore keystore.p12 -alias liberty -storetype PKCS12 -file liberty.cer -rfc
    The SSL certificate can be distributed to remote users to be imported into the client keystore.

    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.

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

Enabling secure communication with a RACF managed key ring

Instead of a keystore file, you can use a RACF managed key ring to enable secure communication with Debug Profile Service. To create a RACF key ring and certificates, you must have authorization to issue RACDCERT commands. For more information about the RACDCERT commands and authorizations that are required, see "RACDCERT (Manage RACF digital certificates)" in the z/OS Security Server RACF Command Language Reference.

  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.

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

Enabling secure communication with AT-TLS

You can also use the TCP/IP service called Application Transparent Transport Layer Security (AT-TLS) to enable secure communication with Debug Profile Service. For a step-by-step guide to setting up AT-TLS itself, see Setting up AT-TLS.
  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.
    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
    }