Security parameters

Security (TLS) parameters for IBM® Spectrum Symphony include SOAM parameters and EGO parameters.

SOAM parameters

To configure security for individual connections between the IBM Spectrum Symphony client and the session director (SD) or session manager, edit the sd.xml file. This section details the configurable parameters of the sd.xml file.
Note: Do not use braces ({ and }) with SOAM security parameters.
Session director (SD) parameters
  • SD_SDK_TRANSPORT: (daemon and client) enables or disables secure connection between the SD (server) and SDK (client). Specify TCPIPv4SSL to enable security. To disable security, specify TCPIPv4 (this is the default setting).
  • SD_SDK_TRANSPORT_ARG: arguments for initializing the communication library (commLib) on the server side. Arguments consist of security keys and certificates. The format for the arguments is the same as the one used in EGO_DEFAULT_TS_PARAMS and EGO_KD_TS_PARAMS. Alternatively, a variable, such as $EGO_DEFAULT_TS_PARAMS can be substituted in place of the arguments.
  • SDK_TRANSPORT: (client) enables or disables secure connection on the SDK (client) side. Specify TCPIPv4SSL to enable security. To disable security, specify TCPIPv4 (this is the default setting).
  • SD_SOAP_TRANSPORT: (daemon and client) enables or disables secure connection between the SD SOAP server and SOAP client. Specify TCPIPv4SSL to enable secure connection between the SD SOAP server and client. To disable security, specify TCPIPv4 (this is the default setting).
  • SD_SOAP_TRANSPORT_ARG: (daemon only) security configuration for the SD SOAP server, if security between the SD SOAP server and client is enabled. It consists of the CERTIFICATE, CIPHER, and PRIVATE_KEY settings.

    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=AES256-GCM-SHA384,PRIVATE_KEY=$HOME/security/user.key]
  • SDSOAPCLIENT_ARG: (client only) security configuration for the SD SOAP client, if security between the SD SOAP server and client is enabled. It consists of the CIPHER, CAFILE, and SERVER_AUTH settings

    The format for this setting is the same format as the EGO_CLIENT_TS_PARAMS setting in the ego.conf file.

    For example:
    SSL[CIPHER=AES256-GCM-SHA384,CAFILE=$HOME/security/cacert.pem,SERVER_AUTH={SEC_EGO}]
Session manager parameters
  • SSM_SDK_TRANSPORT: protocol driver. The driver value for TLS security is TCPIPv4SSL.
  • SSM_SDK_TRANSPORT_ARG: arguments for initializing the communication library (commLib). Arguments consist of security keys and certificates. The format for the arguments is the same as the one used in EGO_DEFAULT_TS_PARAMS and EGO_KD_TS_PARAMS. Alternatively, a variable, such as $EGO_DEFAULT_TS_PARAMS can be substituted in place of the arguments.

EGO parameters

To configure security for individual connections between the EGO client and EGO, edit the ego.conf file on the management and client hosts as well as the egosc_conf.xml file on the EGO Service Controller host.

ego.conf file parameters
This section details the configurable parameters of the ego.conf file. The security parameters in the ego.conf file must be configured for the VEMKD daemon and the client, whichever is applicable.
  • EGO_TRANSPORT_SECURITY: (daemon and client) enables or disables the transport security feature.
  • EGO_DEFAULT_TS_PARAMS: (daemon only) this is a general parameter consisting of sub-parameters defined for security that apply to every daemon and container in the cluster. If parameters are not defined, TLS will use anonymous DH as the cipher. The user can define daemon-specific parameters that override these default parameters. Refer to ego.conf sub-parameters for a list of applicable sub-parameters.
  • EGO_KD_TS_PORT: (daemon and client) the TLS port number of VEMKD.
  • EGO_KD_TS_PARAMS: (daemon only) the security parameters specific to VEMKD. Refer to ego.conf subparameters for a list of applicable sub-parameters.
  • EGO_CLIENT_TS_PARAMS: (client only) the security parameters specific to the client. Refer to ego.conf subparameters for a list of applicable sub-parameters.
  • EGO_PEM_TRANSPORT_SECURITY: (daemon and client) enables or disables secure connection between VEMKD and PEM. Specify SSL to enable secure connection between VEMKD and PEM. To disable security, do not include (comment out) this setting.
  • EGO_KD_PEM_TS_PARAMS: (daemon only) security configuration for VEMKD, if security between VEMKD and PEM is enabled. It consists of the CAFILE, CERTIFICATE, CIPHER, PRIVATE_KEY, and SERVER_AUTH settings.
    For example:
    EGO_KD_PEM_TS_PARAMS="SSL[CAFILE=$HOME/secuirty/cacert.pem,CERTIFICATE=$HOME/security/vemkd.pem,CIPHER=AES256-GCM-SHA384,
PRIVATE_KEY=$HOME/secuirty/vemkd.key,SERVER_AUTH={PEM}]"

    If you do not configure the cipher using the EGO_KD_PEM_TS_PARAMS setting, then the default cipher AES256-GCM-SHA384 will be used.

    Note: If you do not configure the EGO_KD_PEM_TS_PARAMS setting, ensure that the EGO_DEFAULT_TS_PARAMS setting is correctly configured in the ego.conf file; however, note that configuring the EGO_KD_PEM_TS_PARAMS setting to use the default parameter from the EGO_DEFAULT_TS_PARAMS setting, at the same time, is not supported. Configure one or the other.
  • EGO_PEM_TS_PARAMS: (client only) security configuration for PEM, if security between VEMKD and PEM is enabled. It consists of the CERTIFICATE, CIPHER, PRIVATE_KEY, CAFILE, and SERVER_AUTH settings.
    For example:
    EGO_PEM_TS_PARAMS="SSL[CERTIFICATE=$HOME/security/pem.pem,PRIVATE_KEY=$HOME/security/pem.key,CIPHER= ECDHE-ECDSA-AES256-GCM-SHA384,
CAFILE=$HOME/security/cacert.pem,SERVER_AUTH={SEC_VEMKD}]"
  • EGO_KD_PEM_TS_PORT: (daemon only) The security port where VEMKD accepts TLS connections from PEM. For example, port 32781.
  • EGO_PEM_TS_PORT: (client only) The security port where PEM accepts TLS connections from VEMKD. For example, port 32782.
egosc_conf.xml file parameters
The egosc_conf.xml file contains one configurable security parameter: ESC_TS_PARAMS. It contains the security parameters for the EGO Service Controller. ESC_TS_PARAMS uses the same subparameters as EGO_KD_TS_PARAMS but they are applicable only to the Service Controller.

Repository server parameters

To configure security for individual connections between the repository server (RS) and the RS client, edit the rs.xml file. This section details the configurable parameters of the rs.xml file.
  • RS_RSSDK_TRANSPORT: (daemon and client) enables or disables TLS authentication between the RS and the RS client. Specify TCPIPv4SSL to enable secure connection between RS and the RS client. To disable security, specify TCPIPv4 (this is the default setting).
  • RS_RSSDK_TRANSPORT_ARG: (daemon only) security configuration for the RS, if security between the RS and the RS client is enabled. It consists of the CERTIFICATE, CIPHER, and PRIVATE_KEY settings.
    For example:
    SSL[CERTIFICATE=$HOME/security/user.pem,CIPHER=AES256-GCM-SHA384,PRIVATE_KEY=$HOME/security/user.key]
  • RSSDK_TRANSPORT_ARG: (client only) security configuration for the RS client, if security between the RS and the RS client is enabled. It consists CIPHER, CAFILE, and SERVER_AUTH settings.

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

    The format for this setting is the same format as the EGO_CLIENT_TS_PARAMS setting in the ego.conf file.

    For example:
    SSL[CIPHER=AES256-GCM-SHA384,CAFILE=$HOME/security/cacert.pem,SERVER_AUTH={SEC_EGO}]

Repository server agent parameters

To configure security for individual connections between the EGO repository server agent (RSA) and the RSA client, edit the rsa.xml file. This section details the configurable parameters of the rs.xml file.
  • GS_AGENT_TRANSPORT: (daemon and client) enables or disables TLS authentication between the RSA and the RSA client. Specify TCPIPv4SSL to enable secure connection between RSA and the RSA client. To disable security, specify TCPIPv4 (this is the default setting).
  • GS_AGENT_TRANSPORT_ARG: (daemon only) security configuration for the RSA, if security between the RSA and the RSA client is enabled. It consists of the CERTIFICATE, CIPHER, and PRIVATE_KEY settings.
    For example:
    SSL[CERTIFICATE=$HOME/security/user.pem,CIPHER=AES256-GCM-SHA384,PRIVATE_KEY=$HOME/security/user.key]

ego.conf, rs.xml, rsa.xml, and sd.xml subparameters

The EGO_DEFAULT_TS_PARAMS, EGO_KD_TS_PARAMS, EGO_CLIENT_TS_PARAMS, EGO_KD_PEM_TS_PARAMS, EGO_PEM_TS_PARAMS, RS_RSSDK_TRANSPORT_ARG, RSSDK_TRANSPORT_ARG, GS_AGENT_TRANSPORT_ARG, SD_SOAP_TRANSPORT_ARG, and SDSOAPCLIENT_ARG parameters contain the following configurable subparameters:

  • CERTIFICATE or CERTIFICATE_WIN: (daemon only) the location of the certificate file. Certificate files with the PEM file format are supported.

    For a mixed operating system cluster, on Linux® hosts, binaries use the value of the CERTIFICATE subparameter. For Windows hosts, binaries first use the value of the CERTIFICATE_WIN subparameter, and if not defined, then use the CERTIFICATE subparameter value.

    For information about generating certificates using openssl, refer to http://www.openssl.org/docs/apps/openssl.html. For testing on Linux hosts, IBM Spectrum Symphony provides a self-signed server certificate (user.pem), which is at /opt/ibm/spectrumcomputing/wlp/usr/shared/resources/security/.

  • CIPHER: (daemon and client) the cipher list used by TLS. The client and server will negotiate the cipher list and select the first shared one.
    If not specified, the default (AES256-GCM-SHA384) is used.
    Note: If you use a cipher that contains ECDSA (rather than RSA), you must generate the Certification Authority certificate and server certificate key with the openssl ecparam command.
    The supported ciphers for secure connections between VEMKD and its clients are as follows:
    • DHE-RSA-AES256-GCM-SHA384
    • DHE-RSA-AES256-SHA256
    • DHE-RSA-AES256-SHA
    • DHE-RSA-CAMELLIA256-SHA
    • DHE-RSA-AES128-GCM-SHA256
    • DHE-RSA-AES128-SHA
    • DHE-RSA-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)
    • DHE-RSA-CAMELLIA128-SHA
    • 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
    The supported ciphers for secure connections between VEMKD and PEM are as follows:
    • DHE-RSA-AES256-GCM-SHA384
    • DHE-RSA-AES256-SHA256
    • DHE-RSA-AES256-SHA
    • DHE-RSA-AES128-GCM-SHA256
    • DHE-RSA-AES128-SHA
    • DHE-RSA-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))
    • DHE-RSA-CAMELLIA128-SHA
    • 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
    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
    The supported ciphers for secure connections between the SD SOAP server and client are as follows:
    • AES256-SHA256
    • AES256-GCM-SHA384 (default)
    • AES256-SHA256
    • AES256-SHA
    • AES128-GCM-SHA256
    • AES128-SHA256
    • AES128-SHA
    • 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: C# applications that invoke WSDL APIs using a specific cipher depend on your Windows version. For example, Microsoft does not support ECDHE-RSA-AES256-GCM-SHA384 and ECDHE-RSA-AES128-GCM-SHA256 for Windows 8. For more details, refer to https://msdn.microsoft.com/en-us/library/windows/desktop/mt762882(v=vs.85).aspx. For an overview of the cipher suites that Microsoft supports, refer to https://msdn.microsoft.com/en-us/library/windows/desktop/aa374757(v=vs.85).aspx.

    CBC ciphers are known to be vulnerable to SSLv3 POODLE attacks. However, because IBM Spectrum Symphony uses the TLSv1.2 protocol, you can safely use CBC ciphers. The default cipher is AES256-GCM-SHA384.

  • CAFILE or CAFILE_WIN: (client only) the location of the certification authority (CA) certificate. The client reads this file and trusts the CA within the file. This parameter is used in cases where there is only one certificate file.

    For a mixed operating system cluster, on Linux hosts, binaries use the value of the CAFILE subparameter. For Windows hosts, binaries first use the value of the CAFILE_WIN subparameter, and if not defined, then use the CAFILE subparameter value.

    For testing on Linux hosts, IBM Spectrum Symphony provides a self-signed CA certificate (cacert.pem), which is at /opt/ibm/spectrumcomputing/wlp/usr/shared/resources/security/.

    Note: The built-in certificate is installed with IBM Spectrum Symphony only on management hosts. If you enable security for system daemons and want to run a client on compute hosts or a client outside the cluster, you must copy the cacert.pem certificate to your client host and configure the ego.conf file on the local host.
  • CA_THUMBPRINT_LIST: used to configure the thumbprint of the CA on Windows . If there is only one CA, configure it with the format thumbprint@store. If there are multiple CAs in the certificate chain, separate each thumbprint@store string using a colon (:), for example, thumbprint1@store1:thumbprint2@store2. The system will use the thumbprint configured in CA_THUMBPRINT_LIST to acquire a CA certificate from the Windows certificate store, rather than from disk. If CA_THUMBPRINT_LIST is configured, CAFILE and CAFILE_WIN will be ignored.
  • PRIVATE_KEY or PRIVATE_KEY_WIN: (daemon only) the location of the private key file. The private key of the default self-signed certificate is user.key.

    Note that IBM Spectrum Symphony system daemons do not support encrypted private keys.

    For a mixed operating system cluster, on Linux hosts, binaries use the value of the PRIVATE_KEY subparameter. For Windows hosts, binaries first use the value of the PRIVATE_KEY_WIN subparameter, and if not defined, then use the PRIVATE_KEY subparameter value.

  • SERVER_AUTH: (client only) defines whether the client must authenticate the CN (common name) fields within the server's certificate.
    Syntax:
    • SERVER_AUTH=NONE|HOST|{string}name{string}…
    • (7.3.2 Fix)SERVER_AUTH=NONE|HOST|{string}name{string}…|HOST_CN_DNS
    where:
    NONE
    Indicates the client will not verify the server certificate. This is the default value. To ensure that the client verifies the server's certificate, set a value for SERVER_AUTH and ensure that it is not set to SERVER_AUTH=NONE).

    If the SERVER_AUTH parameter is not set, IBM Spectrum Symphony treats it as a value of SERVER_AUTH=NONE.

    HOST
    Specified per host certificate. Check the connected host with the subject CN in the certificate. The connected host's name must exactly match the CN in the certificate. CNs such as *.symphony.ibm.com are not supported.
    {string}name{string}...
    Use this format to enable certificate verification on a per cluster, daemon, or application basis.

    The name can be either a name of a daemon (such as VEMKD) or an application (such as SOATesting). The string is the subject CN in the certificate. The first {string} is the default value for daemons or applications whose names are not defined here.

    (7.3.2 Fix)HOST_CN_DNS
    The client verifies the server certificate by checking the server’s hostname against the server certificate’s DNS (which is defined in the subject alternative name) or against its CN. Hostname checking succeeds if the DNS name defined in certificate’s subject alternative name or in the CN matches the server’s hostname.

    The certificate’s DNS name defined in subject alternative name can be one or multiple DNS names.

    The hostname checking is done using the OpenSSL API X509_check_host during certificate verification, and the hostname checking behavior follows the API description. The hostname checking disables wildcard expansions using the X509_CHECK_FLAG_NO_WILDCARDS flag.

    Note: The SD SOAP client does not check the CN defined in server certificates; therefore, the SERVER_AUTH parameter will be ignored in the SD SOAP interface. This statement is still true for the SERVER_AUTH=HOST_CN_DNS configuration.
    Note: All IBM Spectrum Symphony daemons have reserved names. An application cannot have the same name as an IBM Spectrum Symphony daemon. For example, you cannot define a IBM Spectrum Symphony application with the name vemkd.
    For example:
    1. SERVER_AUTH={Platform EGO}: only default is provided. All daemons share the same certificate of Platform EGO.
    2. SERVER_AUTH=vemkd{Platform vemkd}egosc{Platform Service Controller}: value is provided for each daemon. Client will check VEMKD certificate with Platform vemkd, and EGOSC certificate with Platform Service Controller.
    3. SERVER_AUTH={Platform EGO}SOATesting{SOA Testing}: both default and name-value pair are provided. IBM Spectrum Symphony client of SOATesting will check SSM certificate with SOA Testing. All other clients check daemon certificate against Platform EGO.
    4. (7.3.2 Fix)SERVER_AUTH=HOST_CN_DNS: Specifying HOST_CN_DNS for the SERVER_AUTH value allows the client to check the connected server hostname against the server certificate's DNS (which is defined in the subject alternative name) or against its CN.