SSL/TLS and Security Support

This document covers the following topics:


Security Support for Adapter Services

The EntireX Adapter uses adapter services to send synchronous or asynchronous requests to various back-end systems. Access to these systems can be secured in the following ways:

  • Provide security credentials in the adapter connection for security-protected back-end systems
    If access to a back-end system is security protected, security credentials (user ID and password) have to be provided in the corresponding adapter connection. This can be done when the connection is configured or edited, see EntireX Adapter Connections. This security support is optional and not available for all connection types, see the overview of available connection parameters in Editing Adapter Connections.

    The credentials can also be provided dynamically when calling the adapter service, see EntireX Adapter Services.

  • Set access control permissions for the adapter service
    Using the Designer you can set access control permissions to restrict the right to execute an adapter service to a particular user group of the Integration Server:

    Start of instruction setTo set access control permissions using the Designer

    1. Choose Service Development > Package Navigator > Permissions.

      graphics/security_services.png

    2. Set Enforce Execute ACL to When top-level service only to select the group that is specified on the top-level service. This way, access control is already checked when executing the top-level service.

      Or:
      Set Enforce Execute ACL to Always and select a user group in Execute ACL.

Security Support for Adapter Listeners

Adapter listeners receive synchronous or asynchronous requests from external RPC clients. If the RPC request is sent to the EntireX Adapter using a broker that is configured to use security, the credentials of the RPC clients are checked to see if the client is permitted to call the adapter listener.

By enabling the listener property Execute Service with Client Credentials, an adapter listener can be configured to use the credentials (user ID and password) provided by the RPC client to execute the Integration Server service:

graphics/security_listeners.png

Then the RPC client has to provide credentials (RPC user ID and RPC password) which are used to execute the Integration Server service. Note that currently the RPC user ID and password are limited to eight characters.

Support for SSL/TLS

Communication between the Adapter and the back-end systems is done using TCP/IP or, for secure communication, SSL/TLS. The configuration of SSL depends on the connection type:

Connection Type Description Notes
Connection types using the EntireX Broker Use the URL-style syntax by which Broker IDs are defined to select SSL as transport method and to define the SSL parameters. For example: ssl://host:1958?definition_of_sslparameters. The syntax for defining SSL parameters is described in the notes below. 1,2,3,4,5
IMS Connect and CICS ECI Specify the SSL port in the Port property and the SSL parameters in the SSL Parameters property as described in Editing a Connection. The syntax for defining SSL parameters is described in the notes below. 1,3
Direct RPC Specify the SSL port and SSL parameters in the configuration wizard for Direct RPC. 1,5

Notes

  1. To operate with SSL, certificates need to be provided and maintained. Depending on the platform, Software AG provides default certificates, but we strongly recommend that you create your own. See SSL/TLS Sample Certificates Delivered with EntireX in the EntireX Security documentation.

  2. Specify Broker ID and SSL parameters.

    SSL transport will be chosen if the Broker ID starts with the string ssl://. Example of a typical URL-style Broker ID:

    ssl://host:1958?definition_of_sslparameters

    If no port number is specified, port 1958 is used as default.

  3. If the SSL client checks the validity of the SSL server only, this is known as one-way SSL. The mandatory trust_store parameter specifies the file name of a keystore that must contain the list of trusted certificate authorities for the certificate of the SSL server. By default a check is made that the certificate of the SSL server is issued for the hostname specified in the Broker ID. The common name of the subject entry in the server's certificate is checked against the hostname. If they do not match, the connection will be refused. You can disable this check with SSL parameter verify_server=no.

    If the SSL server additionally checks the identity of the SSL client, this is known as two-way SSL. In this case the SSL server requests a client certificate (the parameter verify_client=yes is defined in the configuration of the SSL server). Two additional SSL parameters must be specified on the SSL client side: key_store and key_passwd. This keystore must contain the private key of the SSL client. The password that protects the private key is specified with key_passwd.

    The ampersand (&) character cannot appear in the password.

    SSL parameters are separated by ampersand (&). See also SSL/TLS Parameters for SSL Clients.

    Example of one-way SSL:

    ssl://host:1958?trust_store=/temp/ExxCACert.jks&verify_server=no

    Example of two-way SSL:

    ssl://host:1958?trust_store=/temp/ExxCACert.jks&key_store=/temp/ExxJavaAppCert.jks&key_passwd=ExxJavaAppCert
  4. Make sure the SSL server to which the EntireX Adapter (service or listener) connects is prepared for SSL connections as well. The SSL server can be EntireX Broker or Broker SSL Agent. See:

    • Running Broker with SSL/TLS Transport under z/OS | UNIX | Windows | z/VSE

    • Settting up and Administering the EntireX Broker SSL Agent under UNIX | Windows

  5. For information on how to configure other EntireX components using SSL/TLS, see Using SSL/TLS with EntireX Components.