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:
- 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`"
- Edit /etc/debug/eqaprof.env and update the keystore variables to use the new keystore file.
- 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
- Export the SSL certificate
with:
The SSL certificate can be distributed to remote users to be imported into the client keystore.keytool -export -keystore keystore.p12 -alias liberty -storetype PKCS12 -file liberty.cer -rfc
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.
- Create a RACF key ring for Debug Profile Service to use as its
keystore:
RACDCERT ADDRING(EQAPROF.Keyring) ID(STCEQA)
- 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)
- 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)
- 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)
- 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
- Edit /etc/debug/eqaprof.env and update the keystore variables to
use the key ring:
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="safkeyringjce://STCEQA/EQAPROF.Keyring" keystorePass="password" keystoreType="JCERACFKS"
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.
- The value for
- Export the CA certificate that contains the public key to a z/OS sequential
file:
The CA certificate can be distributed to remote users to be imported into the client keystore manually if necessary.RACDCERT CERTAUTH EXPORT(LABEL('zosDebuggerCA')) DSN('<sequential data set>') FORMAT(CERTDER)
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
- In the eqaprof.env configuration file, specify
SECURE="AT-TLS"
. - 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 }