The following Rhapsody components use TLS (Transport Layer Security) in order to secure connections to provide confidentiality, integrity, and authorization of transmitted data:

When a TLS connection is established, the client and server exchange keys, negotiate a cipher suite, and then generate a random session key to use for the connection. As Rhapsody is designed to communicate with a wide range of systems, it supports several SSL/TLS (Secure Sockets Layer/Transport Layer Security) versions and allows the enabled cipher suites to be configured as required.

SSL/TLS Protocol Versions

Rhapsody currently supports the following SSL/TLS protocols: TLSv1.0, TLSv1.1, and TLSv1.2. These protocols can be enabled using a configuration property on the relevant Rhapsody components.

For various compatibility reasons, some SSL/TLS clients send an SSLv2 ClientHello packet (the first message sent to start the SSL handshake) even if they actually only support SSLv3/TLSv1.0. All Rhapsody SSL/TLS server components accept these SSLv2 ClientHello packets as long as the remote client actually supports either SSLv3 or TLSv1.0. Rhapsody does not support SSLv1, SSLv2, and SSLv3 due to significant security issues with those protocols.

You can configure Rhapsody client components to send an SSLv2 ClientHello packet to establish the SSL connection if this is required for compatibility with the SSL server that Rhapsody needs to talk to. This option is not available on AIX, as the JSSE security implementation in the IBM JRE does not support this behavior.

Consequently, Rhapsody TLS components allow the following SSL protocol modes to be configured:

  • SSL - enables the TLSv1.0, TLSv1.1 and TLSv1.2 protocols and if this is an SSL client, it sends an SSLv2-compatible ClientHello packet (but does not support SSLv2 itself). An incoming SSLv2 ClientHello packet is accepted by an SSL server configured using this mode (provided that it actually is using TLS).

  • TLSv1 - enables the TLSv1.0, TLSv1.1 and TLSv1.2 protocols. An incoming SSLv2 ClientHello packet is accepted by an SSL server configured using this mode (provided that it actually is using TLS).

  • TLSv1.1 - enables the TLSv1.1 and TLSv1.2 protocols only.
  • TLSv1.2 - enables the TLSv1.2 protocol only.

Using TLSv1.1 or TLSv1.2 may result in a component not being able to connect to legacy systems that do not support these protocols, therefore ensure your configuration has been tested before being placed in a production environment.

For backward compatibility, some Rhapsody communication points list an additional number of SSL protocol modes:

  • SSLv2 - Treated as SSL (in other words, the TLSv1.0 protocol is enabled, and an SSLv2-compatible ClientHello is sent if this is a client).

  • SSLv3 - Treated as TLSv1 (in other words, only the TLSv1.0 protocol is enabled).

  • TLS - Treated as TLSv1 (in other words, only the TLSv1.0 protocol is enabled).

In most cases, newly created components default to using TLSv1.2.

SSL/TLS Cipher Suites

The SSL cipher suite determines which algorithms are used for key exchange, encryption, and message integrity. Due to the SSL handshake, the client and server negotiate which cipher suite should be used for the connection, and the connection can only be established if the client and server have a cipher suite in common. This allows both the client and server to set minimum expectations for the security of the connection.

Supported cipher suites in Rhapsody are arranged into groups to make it easier to configure the desired security level for each SSL component, while still allowing a system administrator the fine-grained control of which cipher suites belong to which groups. In Rhapsody's default configuration, the cipher suites are grouped as follows:

Cipher Suite Group

Description

Usage

Very Strong

Only the AES 256-bit cipher suites are enabled.

Only available to components using TLSv1, TLSv1.1, or TLSv1.2 as the SSL protocol.

FIPS

Only the FIPS cipher suites are enabled. This includes AES 128-bit and AES 256-bit cipher suites.

Only available to components using TLSv1, TLSv1.1, or TLSv1.2 as the SSL protocol. By default, the FIPS cipher suites are enabled for all SSL/TLS components in Rhapsody. This can be changed as required on a per component basis.

Strong

Only cipher suites with greater than 128-bit encryption are enabled. This includes AES 128-bit and AES 256-bit.


Weak

Intended for the weak strength cipher suites.

In the JRE versions used as of Rhapsody 6.5, vulnerable and compromised cipher suites have been removed from this group. Currently, the group contains the same set of cipher suites as the FIPS and Strong groups.

Not available to components using TLSv1.1 or TLSv1.2 as the SSL protocol.

Weak cipher suites should not be used unless there is a justified need for them (for example, when Rhapsody is required to connect to a system that only supports weak cipher suites and no higher security options are available). To enable weak cipher suites, refer to Enabling Disabled Cipher Suites.

Configuring Cipher Suites

The cipher suites included within each cipher suite group can be configured through the rhapsody.properties file using the following keys:

  • SslProvider.CipherSuites.VeryStrong (the very strong cipher suites).
  • SslProvider.CipherSuites.Fips (the FIPS cipher suites).
  • SslProvider.CipherSuites.Strong (the strong cipher suites).
  • SslProvider.CipherSuites.Weak (the weak cipher suites).

Anonymous cipher suites have been removed from the JRE version used by Rhapsody as of Rhapsody 6.5 because of vulnerabilities. Therefore, as of Rhapsody 6.5, Rhapsody no longer uses them. As with other compromised or weak cipher suites, anonymous cipher suites can be re-added to the rhapsody.properties file if necessary, as can the anonymous cipher suite groups which they previously belonged to (refer to TLS/SSL Support in Rhapsody 6.4 for the cipher suites supported in that version):

  • SslProvider.CipherSuites.Strong.Anonymous (the strong but anonymous cipher suites).
  • SslProvider.CipherSuites.Weak.Anonymous (the weak and anonymous cipher suites).

To enable a specific set of cipher suites in a cipher suite group, uncomment them in the rhapsody.properties file, and restart Rhapsody in order for the changes to be picked up.

By default, all available cipher suites are enabled. The list of cipher suites included for each group level is the exhaustive list of all available cipher suites at that level. The cipher suites actually enabled for a particular socket are always a subset of this list depending on the platform in use and the selected SSL certificate for the connection (for example, the DSA cipher suites are only available if using a DSA key instead of an RSA key).

The set of cipher suites currently supported and therefore enabled in Rhapsody is as follows:

# SSL Cipher Suites
# Note that each cipher suite group wraps over multiple lines. All the lines for a particular group
# should be uncommented if it is going to be modified. Wrapping requires that the last character on
# the previous line is a backslash.
#WebMonitoringService.ssl.enabledCiphers=TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384 TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 \
#    TLS_RSA_WITH_AES_256_CBC_SHA256 TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA384 TLS_ECDH_RSA_WITH_AES_256_CBC_SHA384 \
#    TLS_DHE_RSA_WITH_AES_256_CBC_SHA256 TLS_DHE_DSS_WITH_AES_256_CBC_SHA256 TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA \
#    TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA TLS_RSA_WITH_AES_256_CBC_SHA TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA \
#    TLS_ECDH_RSA_WITH_AES_256_CBC_SHA TLS_DHE_RSA_WITH_AES_256_CBC_SHA TLS_DHE_DSS_WITH_AES_256_CBC_SHA \
#    TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 TLS_RSA_WITH_AES_128_CBC_SHA256 \
#    TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256 TLS_ECDH_RSA_WITH_AES_128_CBC_SHA256 TLS_DHE_RSA_WITH_AES_128_CBC_SHA256 \
#    TLS_DHE_DSS_WITH_AES_128_CBC_SHA256 TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA \
#    TLS_RSA_WITH_AES_128_CBC_SHA TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA TLS_ECDH_RSA_WITH_AES_128_CBC_SHA \
#    TLS_DHE_RSA_WITH_AES_128_CBC_SHA TLS_DHE_DSS_WITH_AES_128_CBC_SHA TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 \
#    TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 TLS_RSA_WITH_AES_256_GCM_SHA384 \
#    TLS_ECDH_ECDSA_WITH_AES_256_GCM_SHA384 TLS_ECDH_RSA_WITH_AES_256_GCM_SHA384 TLS_DHE_RSA_WITH_AES_256_GCM_SHA384 \
#    TLS_DHE_DSS_WITH_AES_256_GCM_SHA384 TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 TLS_RSA_WITH_AES_128_GCM_SHA256 \
#    TLS_ECDH_ECDSA_WITH_AES_128_GCM_SHA256 TLS_ECDH_RSA_WITH_AES_128_GCM_SHA256 TLS_DHE_RSA_WITH_AES_128_GCM_SHA256 \
#    TLS_DHE_DSS_WITH_AES_128_GCM_SHA256 TLS_EMPTY_RENEGOTIATION_INFO_SCSV
#SslProvider.CipherSuites.VeryStrong=TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA \
#    TLS_RSA_WITH_AES_256_CBC_SHA256 TLS_RSA_WITH_AES_256_CBC_SHA \
#SslProvider.CipherSuites.Fips=TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384  TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA \
#    TLS_RSA_WITH_AES_256_CBC_SHA256 TLS_RSA_WITH_AES_256_CBC_SHA TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 \
#    TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA TLS_RSA_WITH_AES_128_CBC_SHA256 TLS_RSA_WITH_AES_128_CBC_SHA
#SslProvider.CipherSuites.Strong=TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA \
#    TLS_RSA_WITH_AES_256_CBC_SHA256 TLS_RSA_WITH_AES_256_CBC_SHA TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 \
#    TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA TLS_RSA_WITH_AES_128_CBC_SHA256 TLS_RSA_WITH_AES_128_CBC_SHA
#SslProvider.CipherSuites.Weak=TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA \
#    TLS_RSA_WITH_AES_256_CBC_SHA256 TLS_RSA_WITH_AES_256_CBC_SHA TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 \
#    TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA TLS_RSA_WITH_AES_128_CBC_SHA256 TLS_RSA_WITH_AES_128_CBC_SHA

Rhapsody does not enable ECDHE cipher suites by default for HP-UX servers, unless explicitly stated in the rhapsody.properties file.

Caution is urged when editing these settings in the rhapsody.properties file as they wrap over multiple lines using the escape character (a backslash) since they are very long. If one of these properties is not set, then the current cipher suite reverts to the default cipher suites for that level. The actual cipher suites included in each category are written to the Rhapsody log during startup at the DEBUG level. This can be enabled if desired by adding the following line to the log4j.properties file:

log4j.logger.com.orchestral.rhapsody.security.ssl=DEBUG

Enabling Disabled Cipher Suites

Algorithms which have been disabled in Rhapsody are listed in the property jdk.tls.disabledAlgorithms in the java.security file, which is located in <Rhapsody>/jre/lib/security. This file is automatically updated during every upgrade.

To enable a cipher suite that has been disabled:

  1. Edit the java.security file to remove the relevant algorithms from the list of disabled algorithms listed in the property jdk.tls.disabledAlgorithms.
  2. Edit the rhapsody.properties file to add the relevant cipher suite into one of the existing groups. Ensure the entire group is uncommented.
  3. Restart Rhapsody so the engine can pick up the changes.

For example, the TLS_ECDHE_RSA_WITH_RC4_128_SHA cipher suite has been removed because the RC4 algorithm has exploitable vulnerabilities. To enable TLS_ECDHE_RSA_WITH_RC4_128_SHA for an external system can only connect to Rhapsody using it:

  1. Modify the java.security file by removing the RC4 algorithm:

    jdk.tls.disabledAlgorithms=SSLv3, RC4, DES, MD5withRSA, DH keySize < 1024, \
    EC keySize < 224, 3DES_EDE_CBC, anon, NULL

  2. Modify the rhapsody.properties file by adding the cipher suite to the weak group and uncommenting the entire group:

    SslProvider.CipherSuites.Weak=TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA \
    TLS_RSA_WITH_AES_256_CBC_SHA256 TLS_RSA_WITH_AES_256_CBC_SHA TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 \
    TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA TLS_RSA_WITH_AES_128_CBC_SHA256 TLS_RSA_WITH_AES_128_CBC_SHA TLS_ECDHE_RSA_WITH_RC4_128_SHA

  3. Restart Rhapsody.

Updating Cipher Suites Post-upgrade

The list of cipher suites enabled in Rhapsody is not automatically updated in the rhapsody.properties file during an upgrade.

If you are using the default set of cipher suites (in other words, the list of cipher suites is fully commented out), it is recommended that you replace the original settings with the default cipher suite settings of the version of Rhapsody you are upgrading to. This ensures that the correct cipher suites are in place for future use.

If you are using custom cipher suites (in other words, relevant parts of the list of cipher suites have been uncommented), it is also recommended that you replace the original settings with the default cipher suite settings of the version of Rhapsody you are upgrading to, having taken note of any customizations. Thereafter, you can modify the section to re-incorporate your customizations.

Ensure you are not using any disabled cipher suites.

Testing all components which use the SSL/TLS protocol is especially important after an upgrade. If a component fails to start due to the use of a disabled cipher suite, the expected error in the logs would be of the form:

*.SSLHandshakeException: No appropriate protocol (protocol is disabled or cipher suites are inappropriate)

Mutual Authentication

Mutual authentication refers to a situation where both parties in a connection authenticate each other at the same time. This means that when establishing a connection the client must authenticate itself to the server and the server must also authenticate itself to a client. Mutual authentication is a crucial part of establishing a secure connection so that both the client and server know who they are talking to. This means that they can prevent transmitting or receiving data from an untrusted party. 

In the context of TLS, the authentication of servers is almost always done using SSL certificates. However, client authentication can be done in a number of different ways including SSL certificates, or sometimes via a login using a username and password.

It is highly recommended that SSL with mutual authentication be enabled whenever it is supported by the remote system. Using SSL without mutual authentication could result in connections being established to untrusted systems.

Server Authentication

Server authentication is normally performed using SSL certificates. The server is configured to use a private key and corresponding certificate chain, and it presents the certificate chain to clients as they connect. Clients connecting to such a server examine the presented certificate chain to ensure that they trust either the presented certificate directly, or one of the certificates higher in the chain.

All TLS-capable server communication points in Rhapsody provide some way to configure the SSL private key to use for the connection:

  • TCP Server, HTTP Server, Rhapsody Connector, ASTM TCP Server, Clinicom Server, and JavaScript TCP Server communication points configure this using the Secure Keys configuration property.
  • Hosted Web Services configure this using the Private Key configuration property in the Web Service itself (as opposed to the Web Service Hosting communication point). Web services can configure a key even when not using TLS as it can be used to perform message-level encryption using XML security rather than the transport level encryption provided by TLS.

This private key and certificate pair should ideally be at least of 2048-bit strength. It can be generated through the Rhapsody IDE Certificate Manager if required.

All TLS capable client communication points in Rhapsody provide a way to configure the SSL certificates that they expect to be presented by the server. If the server does not present the expected certificate or a certificate issued by the expected certificate, Rhapsody will prevent the connection from being established.

  • TCP Client, HTTP Client, Rhapsody Connector, ASTM TCP Client, Clinicom Client, JavaScript TCP Client, E-mail Client, TN3270, SMS Batch, and SMS Invision communication points, along with REST Clients, configure this using the Trusted Certificates configuration property. In the case of the HTTP Client communication point and REST Clients, they may optionally leave this property blank in order to accept certificates issued by a trusted certificate authority instead.
  • Web Service Client communication points configure this using the Web Service Certificate configuration property. Note that web service clients can configure the server's certificate even when not using TLS as it can be used to perform message-level encryption using XML security rather than the transport level encryption provided by TLS. In addition, the Server Authentication configuration property can be used to allow accepting certificates issued by a trusted certificate authority instead.
  • (S)FTP Client communication points configure the expected SSL server certificate using the SSL Server Certificates configuration property when connecting to FTPS servers. Server authentication is performed using SSH public keys configured using the SFTP Server Public Key configuration property when connecting to SFTP servers.

Client Authentication

Client authentication of TLS connections can generally be done using SSL certificates, however, some communication point types also provide some alternative mechanisms to accomplish this. TLS client authentication is used by configuring the SSL private key on the client-side, and providing the SSL certificate to the TLS server so that it can authenticate the client. Alternatively, the issuer certificate can be provided to the TLS server to allow it to authenticate any client with a certificate issued by the configured certificate.

It is highly recommended that all TLS server communication points in Rhapsody be configured to perform client authentication either using one of the supported modes, or via custom logic in the routes immediately after receiving the incoming message.

  • TCP Server, ASTM TCP Server, Clinicom Server, and JavaScript TCP Server communication points have built-in support for TLS client authentication using the Trusted Certificates configuration property.
  • HTTP Server communication points have built-in support for TLS client authentication. This is enabled by setting the Require Client Authentication configuration property to true, and then providing the SSL certificates in the Trusted Certificates configuration property.
  • Rhapsody Connector communication points have built-in support for TLS client authentication using the Trusted Certificates and Trusted Certificate Issuers configuration properties.
  • Hosted Web Services have built-in support for client authentication using: TLS client authentication using SSL certificates; HTTP basic authentication; WS-Security Username Token authentication; and WS-Security X509 Token authentication. The Authentication Method configuration property determines what authentication mode is supported, and then the users, passwords, and certificates are configured in the Web Services User Store. As the HTTP basic authentication and WS-Security Username Token authentication modes can result in effectively a plaintext password being sent across the wire, it is strongly recommended that these authentication modes only be enabled when using a TLS connection.

While there are some cases where it is reasonable to configure a server communication point without client authentication, these cases should be relatively rare. Whenever possible it is highly recommended that server communication points in Rhapsody be configured to enforce client authentication.

With the exception of the E-mail Client, all TLS-capable client communication points in Rhapsody support client authentication using SSL client certificates. Some client communication point support types also support alternative modes of authentication:

  • TCP Client, Rhapsody Connector, ASTM TCP Client, Clinicom Client, JavaScript TCP Client, TN3270, SMS Batch, and SMS Invision communication points have built-in support for TLS client authentication using the Secure Keys configuration property.
  • HTTP Client communication points have built-in support for client authentication using: TLS client authentication, configured using the Secure Keys configuration property; and HTTP basic or digest authentication using a username and password, configured using the HTTP Authentication Username and HTTP Authentication Password configuration properties.
  • E-mail Client communication points support client authentication using an IMAP, POP3, or SMTP login with a username and password, configured using the User and Password configuration properties.
  • Web Service Client communication points support client authentication using: TLS client authentication using SSL certificates; HTTP basic or digest authentication; Username Token plaintext authentication, Username Token Digest authentication, and X509 Token authentication. The Authentication Method configuration property determines what authentication mode is supported. If required the private key is provided using the Client Private Key configuration property, and usernames and passwords are provided using the Username and Password properties respectively. As the HTTP basic authentication and WS-Security Username Token authentication modes can result in effectively a plaintext password being sent across the wire, it is strongly recommended that these authentication modes only be enabled when using a TLS connection.
  • (S)FTP Client communication points support client authentication using: username and password authentication (via the Username and Password configuration properties); TLS client authentication when connecting to FTPS servers (using the SSL Client Private Key configuration property); SSH public key authentication when connecting to SFTP servers (using the SFTP Client Private Key configuration property). In addition, when connecting to an SFTP server, the SFTP Client Authentication Mode configuration property can be used to perform client authentication using both a private key and a username/password. 

Certificate Revocation Checks

Rhapsody is capable of performing certificate revocation checks using either the Online Certificate Status Protocol (OCSP) or Certificate Revocation Lists (CRLs). These can be enabled globally via the rhapsody.properties file and are picked up after a Rhapsody restart:

SslProvider.revocationChecks.enable=true

If revocation checks are enabled, then the internal JSSE security implementation will examine the extensions on the issuing certificate to see which of OCSP and CRLs should be used, and then check that the certificate is still valid. If a Rhapsody component has been configured to validate the peer using a self-signed certificate then revocation checks will not be performed.

If revocation checks are enabled, then they are performed on all TLS connections that enable authentication but are not using self-signed certificates. Due to how this is implemented in the JSSE, this will cause certificates that do not provide revocation information either via OCSP or via CRLs to be rejected. This is not a problem if the certificates in question are issued by a public certificate authority, but may be an issue if they are issued by an internal organization certificate authority that does not provide these checks. For this reason, the revocation checks are not enabled by default.