Configuring the TLS protocol


From version 8.9.01 of TrueSight Server Automation, version 1.2 of the Transport Layer Security (TLS) protocol is supported for the session layer security across the various communications legs between the TrueSight Server Automation components.

This topic describes the default settings and limitations of TLS version 1.2 (TLSv1.2) support and how to override the default behavior.

Default behavior of TLS communication

From version 8.9.01 of TrueSight Server Automation, TLSv1.2 is the default protocol for communication between the Application Servers and RSCD Agents. However, earlier versions of TLS are supported for backward compatibility in certain cases.

TLS communication between the Application Servers and RSCD Agents has the following default behavior, depending on the versions of RSCD Agents:

  • After you install RSCD Agent 23.2 or upgrade to 23.2, TLSv1.2 is set as the default protocol on the RSCD Agent and it is the only supported protocol.
  • After upgrading agents to 8.9.01 or later versions, existing SSL sessions continue with the current TLS version until the SSL session expires (typically 24 hours after the connection was established), at which time communication is updated to TLSv1.2.
  • After you install the RSCD Agent 20.02.01, TLSv1.2 is set as the default protocol.
  • When you upgrade the RSCD Agent to version 20.02.01, the existing TLS configuration settings are retained after the upgrade.
  • When you add an additional Application Server, the server is configured with the same TLS settings as that of the Application Server that is connected to the TrueSight Server Automation console.
  • On a Debian system, when you upgrade the RSCD Agent to version 20.02.01 using the native installer, the TLS settings are updated to tlsv1 and tlsv1_2. 
  • If you want to change the value of the OpenSSL protocol to tlsv1_2 during the upgrade, use the following parameter while upgrading the Agent: UPDATE_OPENSSL_PROTOCOL=1
  • For an upgrade, we can detect the configuration of one of the existing nodes and we can apply a similar configuration on the newly added node. 
  • Communication with agents of earlier versions (8.9.01 or earlier) can continue with the existing TLS version 1 (TLSv1). However, you must configure the TLS settings on the Application Server accordingly. For more information, see Configuring the TLS settings on the Application Server.

If you want to override this default behavior — for example, if you want to limit all communication to TLSv1.2 with no option for use of earlier versions of the TLS protocol — perform the tasks described in Overriding default TLS communication settings.

Limitations of TLSv1.2 communication

Support for TLSv1.2 in TrueSight Server Automation has the following limitations:

  • Bare-metal provisioning (specifically the BMI binary) does not work if images are created with a pre-8.9.01 BMI with TLSv1.2.
  • Use cases related to Active Directory (AD) or LDAP authentication and synchronization require an AD server or LDAP server that supports TLSv1.2 connections.
    LDAP synchronization has not yet been fully tested for TLSv1.2-only connections.
  • For patch downloads, outbound HTTPS connections to HTTPS sites (such as RHN or Shavlik) require TLSv1.2 support on the download site. If the connection goes through an HTTPS proxy, the proxy must also support TLSv1.2.

Overriding the default TLS communication settings

You might want to override the default TLS settings, typically to limit all communication to TLSv1.2 with no backward compatibility. To do so, you must perform configuration tasks on both the agent side and the Application Server side:

  1. On the RSCD Agent, you configure TLS settings in the openssl.cnf file, as described in To configure TLS settings on the RSCD Agent.
  2. On the Application Server, you configure settings in the appserver-options.properties file, as described in To configure TLS settings on the Application Server.

To configure TLS settings on the RSCD Agent

  1. On each agent host, locate the openssl.cnf file in the <installDirectory>/share/ directory, and open it with any text editor.

  2. In the [rscd] section of this configuration file, set the value of the protocol parameter.
    To limit communication to TLSv1.2 only, set a value of tlsv1_2, as shown in the following example.
    An additional parameter in this section enables you to specify the cipher suite to be used in the handshake between the RSCD Agent and the Application Server or file server. You can usually keep the default value for the choice of cipher suite.

    [rscd]
    # possible values for protocol: tlsv1_2
    protocol = tlsv1_2
    openssl_ciphers = AES256-SHA256:DES-CBC3-SHA
    .include fipsmodule.cnf

    Important

    During the installation, a fipsmodule.cnf file is automatically generated in the <installDirectory>/share/ directory. If, for any reason, the fipsmodule.cnf file is not present in the <installDirectory>/share/ directory, you can create it using the following commands:

    (Windows) openssl.exe fipsinstall -out <installDirectory>\share\fipsmodule.cnf -module <installDirectory>\bin\fips.dll

    (Linux) openssl fipsinstall -module <installDirectory>/lib/fips.so -out <installDirectory>/share/fipsmodule.cnf -quiet

    These commands allow you to generate the necessary fipsmodule.cnf file if it's missing from the specified directory.

    The following table describes the supported ciphers and the value to be specified for using them:

    Cipher name

    Value to be specified for the openssl_ciphers parameter

    TLS_RSA_WITH_AES_128_CBC_SHA256

    AES128-SHA256

    TLS_RSA_WITH_AES_256_GCM_SHA384

    AES256-GCM-SHA384

    TLS_RSA_WITH_AES_128_GCM_SHA256

    AES128-GCM-SHA256

    TLS_RSA_WITH_AES_256_CBC_SHA256

    AES256-SHA256

    To use multiple ciphers, specify the cipher names separated by a colon (:).

  3. Save the openssl.cnf file.
  4. Restart the RSCD Agent for the changes in the configuration file to take effect.

To configure TLS settings on the Application Server

  1. For each Application Server deployment, locate the appserver-options.properties file in <installDirectory>/br/deployments/<deploymentName>/options/, and open it for editing.

  2. Set values for the following properties:

    Property

    Description

    EnabledSecureProtocols

    Comma-separated list of protocols enabled for listening to requests from the Console and from Web Services, as well as for connections that involve an NSH proxy. Valid values are: TLSv1, TLSv1.2, and TLSv1 , TLSv1.2.

    Default:

    Fresh installation:

    (Versions later than 20.02) TLSv1.2
         (20.02 and earlier versions) TLSv1,TLSv1.2

    After upgrade to 21.02: TLSv1, TLSv1.2

    Note: For fresh installations, if you want to use both TLSv1 and TLSv1.2, change the value to TLSv1, TLSv1.2.

    EnabledPkiProtocols

    Protocol for PKI authentication. Valid value is TLSv1.2.

    Default:

    (Fresh, upgrade) TLSv1.2

    EnabledRscdProtocols

    Comma-separated list of protocols enabled for communication with RSCD agents. Valid values are: TLSv1 , TLSv1.2 , and TLSv1 , TLSv1.2 .

    Default:

    Fresh installation:

    (Versions later than 20.02) TLSv1.2
         (20.02 and earlier versions) TLSv1, TLSv1.2

    After upgrade to 21.02: TLSv1, TLSv1.2

    Important: If the value of the EnabledTlsContextProtocol property is set to TLSv1 , set EnabledRscdProtocols also to TLSv1 for proper communication .

    EnabledAppserverClientProtocols

    Comma-separated list of protocols enabled for use by the Application Server for external connection as an SSL client. Valid values are: TLSv1 , TLSv1.2 , and TLSv1 , TLSv1.2 .

    Default:

    Fresh installation:

    (Versions later than 20.02) TLSv1.2
         (20.02 and earlier versions) TLSv1, TLSv1.2

    After upgrade to 21.02: TLSv1, TLSv1.2

    EnabledTlsContextProtocol

    Protocol used for initiating TLS Context during application server communication with other TrueSight Server Automation components.

    Default:

    Fresh installation:

    (Versions later than 20.02) TLSv1.2
         (20.02 and earlier versions) TLSv1

    After upgrade to version 21.02: TLS

    The value TLS means both TLSv1 and TLSv1.2 are supported. However, if none of the agents are using TLSv1, we recommend you to change the property value to TLSv1.2 from TLS.

    Important: If TLSv1.2 is not supported in your environment, set property value to TLSv1. In that case, communication with agents might break. To resolve the issue, remove the 3DES_EDE_CBC cipher suite from the java.security file:

    1. Go to the following directory:
    (Windows) <INSTALL_DIR>\NSH\jre\lib\security
    (UNIX) <INSTALL_DIR>/NSH/br/java/lib/security

    2. Open the java.security file with a text editor and from the jdk.tls.disabledAlgorithms property value, remove the 3DES_EDE_CBC algorithm.

    JVMArgs

    Custom JVM arguments for the TrueSight Server Automation Application Server.

    For the defaults to be used, ensure that the following protocol arguments are NOT included in the JVMArgs property value:

    • -Dhttps.protocols
    • -Djdk.tls.client.protocols

    EnabledCipherSuites

    A comma-separated list of cipher names. For information about the supported ciphers, see Session-layer-security.

    EnabledCipherSuitesForWebservices

    A comma-separated list of cipher names. For information about the supported ciphers, see Session-layer-security.

  3. Save the properties file.
  4. Restart the Application Server.

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*