Enabling secure communication between RSA and the RSA client for grid synchronization

You can enable secure TLS communication between the EGO repository server agent (RSA) and the RSA client (for gridsync commands) by editing the rsa.xml file on the primary and primary candidate hosts within your cluster.

Before you begin

  • IBM® Spectrum Symphony supports TLS communication between RSA and the RSA client for Linux® hosts, Windows hosts, or a combination (that is, a mixed operating system cluster of Linux and Windows hosts).

    For a single operating system cluster, set the CERTIFICATE, PRIVATE_KEY, and CAFILE subparameters.

    For a mixed operating system cluster, additionally set the CERTIFICATE_WIN, PRIVATE_KEY_WIN, and CAFILE_WIN subparameters. For Windows hosts, binaries first use the values of the CERTIFICATE_WIN, PRIVATE_KEY_WIN, and CAFILE_WIN subparameters, and if not defined, then use the CERTIFICATE, PRIVATE_KEY, and CAFILE subparameter values.

  • Within IBM Spectrum Symphony, the RSA client includes:
    • Command line interface for gridsync.
    • RESTful API for gridsync.
    • Cluster management console pages that involve package operations.
    • The session director (SD).
  • This topic shows adding the GS_AGENT_TRANSPORT and GS_AGENT_TRANSPORT_ARG settings to configure TLS connections between the RSA and the RSA client. Ensure you configure both settings (for example, if you configure only the GS_AGENT_TRANSPORT setting, this enables TLS on the client side; the client will not verify certificates on the server side).

Procedure

  1. Open the $EGO_CONFDIR/../../eservice/esc/conf/services/rsa.xml (Linux) or %EGO_CONFDIR%\..\..\eservice\esc\conf\services\rsa.xml (Windows) file, in your shared directory, to add the following settings:
    1. Add GS_AGENT_TRANSPORT=TCPIPv4SSL to enable TLS connections between RSA and the RSA client.
    2. Add the GS_AGENT_TRANSPORT_ARG setting, which consists of the CERTIFICATE (or CERTIFICATE_WIN), CIPHER, and PRIVATE_KEY (or PRIVATE_KEY_WIN)settings. These are arguments for initializing the TLS communication library on the RSA side.

      Ensure you provide a valid CIPHER value for the GS_AGENT_TRANSPORT_ARG setting, and that you use a consistent value between RSA and the RSA client.

      The format for this setting is the same format as the EGO_DEFAULT_TS_PARAMS setting in the ego.conf file. For example:
      SSL[CERTIFICATE=$HOME/security/user.pem,CIPHER=ECDHE-ECDSA-AES256-GCM-SHA384,PRIVATE_KEY=$HOME/security/user.key]
      The supported ciphers for secure connections between RS (or local RS) and the RS client are as follows:
      • AES256-GCM-SHA384
      • AES256-SHA256
      • AES256-SHA
      • CAMELLIA256-SHA
      • AES128-GCM-SHA256
      • AES128-SHA256
      • AES128-SHA
      • SEED-SHA((7.3.2 Fix)as of OpenSSL 3.x, this is not a supported cipher, and therefore, is not supported for IBM Spectrum Symphony version 7.3.2 with Fix 601711 or later)
      • CAMELLIA128-SHA
      • IDEA-CBC-SHA((7.3.2 Fix)as of OpenSSL 3.x, this is not a supported cipher, and therefore, is not supported for IBM Spectrum Symphony version 7.3.2 with Fix 601711 or later)
      • ECDHE-ECDSA-AES256-GCM-SHA384
      • ECDHE-ECDSA-AES256-SHA384
      • ECDHE-ECDSA-AES128-GCM-SHA256
      • ECDHE-ECDSA-AES128-SHA256
      • ECDHE-RSA-AES256-GCM-SHA384
      • ECDHE-RSA-AES256-SHA384
      • ECDHE-RSA-AES128-GCM-SHA256 (default)
      • ECDHE-RSA-AES128-SHA256
    Note: Your configuration enables the RSA service to start on all compute hosts. For a mixed operating system cluster, ensure that you configure the GS_AGENT_TRANSPORT and GS_AGENT_TRANSPORT_ARG RSA security settings for all corresponding host types in your rsa.xml file.
  2. Ensure configuration changes take effect by stopping and restarting the cluster: 
    > egosh ego stop all
> egosh ego start all

What to do next

If TLS is not enabled successfully, follow these troubleshooting steps:
  1. Verify that your certificate was issued by a specific CA. For example:
    $ openssl verify -CAfile cacert.pem user.pem
user.pem: OK
  2. Check that the CERTIFICATE (or CERTIFICATE_WIN), PRIVATE_KEY (or PRIVATE_KEY_WIN), and CAFILE (or CAFILE_WIN) settings exist in the ego.conf file.
  3. When SERVER_AUTH is set to HOST, check that the server certificate's CN (used when generating the certificate) is same as the server's host name.

    When SERVER_AUTH is set to {string}, check that the server certificate's CN (used when generating the certificate) is same as the defined string used for the corresponding daemon.

    (7.3.2 Fix)When SERVER_AUTH is set to HOST_CN_DNS, check that the server certificate's DNS (defined in the subject alternative name), or the CN (used when generating the certificate), is the same as the server's host name.

  4. Check that the CIPHER setting is a supported cipher, and the cipher specified for server and client match.
  5. If you see a No permission to access this page error while accessing Resources > Hosts > Rack View within the cluster management console, ensure that you are accessing the console using the URL provided when you run the egosh client view GUIURL_1 command.
  6. Ensure the GS_AGENT_TRANSPORT setting is set to TCPIPv4SSL.
  7. Check the value of the GS_AGENT_TRANSPORT_ARG setting is $EGO_DEFAULT_TS_PARAMS, or in this format:
    SSL[CERTIFICATE=$HOME/security/user.pem,CIPHER=ECDHE-ECDSA-AES256-GCM-SHA384,PRIVATE_KEY=$HOME/security/user.key]
  8. If all the aforementioned configurations are correct, refer to the $EGO_TOP/eservice/rsa/log/rsa.host_name.log (Linux) or %EGO_TOP%\eservice\rsa\log\rsa.host_name.log (Windows) file for additional troubleshooting.