(Optional) ssl.properties, the RSE encrypted communication

You need assistance of a security administrator to complete this customization task, which requires the following resources or special customization tasks:
  • LINKLIST update
  • Security rule to add program controlled data sets
  • (Optional) Security rule to add a certificate for host authentication
Note: Due to a vulnerability in the SSLv3 (Secure Socket Layer) protocol, support for this protocol is deprecated in z/OS® Explorer.

External, client-host communication can be encrypted using TLS (Transport Layer Security). This feature is disabled by default and is controlled by the settings in ssl.properties.

Note:
  • Client authentication with an X.509 certificate requires the use of encrypted communication.
  • When using AT-TLS encryption, the RSED task has no knowledge about AT-TLS encrypting all incoming and outgoing traffic. Therefore, you must configure it to work in unencrypted mode by disabling legacy encryption mode in ssl.properties, that is to set enable_ssl to false. RSED offers the exclusive support of the two modes, and only one mode can be enabled at a time. For more information, see Setting up AT-TLS.

ssl.properties is located in /etc/zexpl/, unless you specified a different location when you customized and submitted the FEK.SFEKSAMP(FEKSETUP) job. For more details, see Customization setup. You can edit the file with the TSO OEDIT command. RSE must be restarted for the changes to take effect.

The client communicates with RSE daemon during connection setup and with RSE server during the actual session. Both data streams are encrypted when encryption is enabled.

Note:
  • SAF-compliant key rings are the supported method for managing certificates.
  • SAF-compliant key rings can store the certificate's private key either in the security database or by using ICSF, the interface to z Systems® cryptographic hardware. Access to ICSF is protected by profiles in the CSFSERV security class.

RSE daemon uses System SSL functions to manage encrypted communications. This implies that SYS1.SIEALNKE must be program controlled by the security software and be available to RSE when using LINKLIST or the STEPLIB directive in rse.env.

The following code sample shows the sample ssl.properties file, which must be customized to match your system environment. Comment lines start with a number sign (#) when using a US code page. Data lines can have only a directive and its assigned value; comments are not allowed on the same line. Line continuations are not supported.

Figure 1. ssl.properties – encrypted communication configuration file
# ssl.properties – encrypted communication configuration file

# Enable to ensure AT-TLS is providing encryption services.
enable_attls_policy=false

# Enable legacy encryption. When enabled, enable_attls_policy must be set to false.
enable_ssl=false

# Daemon Properties
daemon_keydb_file=
daemon_key_label=

# Server Properties
server_keystore_file=
server_keystore_label=
server_keystore_type=JCERACFKS

The daemon and server properties must be set only if you enable communication encryption. For more information about encrypted communication setup, see "Setting up encrypted communication and X.509 authentication" in the Host Configuration Reference Guide (SC27-8438).

enable_attls_policy
Enable or disable AT-TLS encrypted communication. The default is false. The only valid options are true and false. When AT-TLS is enabled, RSED must be started in non-SSL mode with enable_ssl set to false.
enable_ssl
Enable or disable encrypted communication. The default is false. The only valid options are true and false. When RSED is configured with enabled encrypted communication, AT-TLS must be disabled with enable_attls_policy set to false.
daemon_keydb_file
RACF® or similar security product key ring name. If encrypted communication is enabled, customize this directive.
daemon_key_label
The certificate label used in the key ring. If encrypted communication is enabled, customize this directive. Key labels are case-sensitive.
server_keystore_file
Name of the RACF or similar security product key ring name. If encrypted communication is enabled, customize this directive.
server_keystore_label
The certificate label used in the key ring. If encrypted communication is enabled, customize this directive. Key labels are case-sensitive.
server_keystore_type
Keystore type. The default is JCERACFKS. Valid values are these:
Table 1. Valid keystore types
Keyword Keystore type
JCERACFKS SAF-compliant key ring, where the certificate's private key is stored in the security database.
JCECCARACFKS SAF-compliant key ring, where the certificate's private key is stored using ICSF, the interface to z Systems cryptographic hardware.
Note:
  • You can use the rse.env configuration file that is located in the same directory as ssl.properties to specify additional options (GSK_*) to adjust your encrypted communication.
  • When you use JCECCARACFKS, ICSF does permission checks at thread level instead of process level as for JCERACFKS, which implies that each user ID that connects must have access to the private key of the server certificate.
  • As documented in Cryptographic Services ICSF Administrator's Guide (SA22-7521), ICSF uses profiles in the CSFKEYS and CSFSERV security classes to control who can use cryptographic keys and services.
  • At the time of publication, IBM® z/OS Java™ requires an update of the /usr/lpp/java/J8.0/lib/security/java.security file to support JCECCARACFKS. The following line must be added: 
    security.provider.1=com.ibm.crypto.hdwrCCA.provider.IBMJCECCA
    The resulting file looks like this: 
    security.provider.1=com.ibm.crypto.hdwrCCA.provider.IBMJCECCA
security.provider.2=com.ibm.jsse2.IBMJSSEProvider2
security.provider.3=com.ibm.crypto.provider.IBMJCE
security.provider.4=com.ibm.security.jgss.IBMJGSSProvider
security.provider.5=com.ibm.security.cert.IBMCertPath
...
  • Chapter Setting up encrypted communication and X.509 authentication in the Host Configuration Reference (SC27-8438) provides step-by-step guidance for setting up encrypted communication.