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 or via a Certificate Authority (CA) certificate with a RACF managed key ring.

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:
```
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.

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')) 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:
```
keystoreFile="safkeyring://STCEQA/EQAPROF.Keyring"
keystorePass="password"
keystoreType="JCERACFKS"
```
Note: The value for keystorePass must be exactly "password" to satisfy the underlying HTTP server, even though SAF key rings do not have a password.
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.