You can enable connection encryption using the ssl-tls property. When <ssl-tls> is specified, you must also supply:

With SSL/TLS configured, the specified security root directory must contain a valid truststore in the trusted-authority subdirectory and a valid keystore in the identity subdirectory. The identity certificate is required even if file-based or LDAP-based authentication is chosen. The choice of authentication scheme may require presence of additional files in the security root directory.

On the client, the security root directory must contain a trusted authority certificate in the trusted-authority subdirectory. Again, the choice of authentication scheme may mean other files, including an identity certificate, are also required in the security root directory.

To configure authentication in the cluster, use authc with the appropriate authentication scheme. Supported authentication schemes are file, ldap, and certificate. When authentication is configured, a security-dir, with the path to the security root directory, must also be specified.

To configure certificate-based authentication, use the certificate authentication scheme in the authc property, and set ssl-tls to true. Also, clients must have an appropriate identity certificate keystore in their security root directory.

To configure file-based authentication, use the file authentication scheme in the authc property.

The server's security root directory must contain a users.xml file, which is a list of all valid users with a password hash for each user. The only password hashing algorithm currently supported is bcrypt.

Example of a users.xml file for authentication:

The command-line utility for generating bcrypt password hashes is located in tools/security/bin under the product installation directory as bcrypt.bat for Windows platforms, and as bcrypt.sh for Unix/Linux.

When running the bcrypt script, you must specify the number of rounds. The number depends on the performance of the server hardware and how you decide to trade off security with speed. A higher number creates hashes that are harder for attackers to crack, but are also harder for your servers to verify. Increasing the number of rounds by 1 doubles the difficulty. You may find that a value between 10 and 13 is suitable.

The bcrypt script can read the input from the console:

or directly from the command line:

The console flavor of the command should be preferred to prevent the shell from saving the input password in its history.

To configure LDAP-based authentication, use the ldap authentication scheme in the authc property.

The server's security root directory must contain an ldap.properties file. The properties in the ldap.properties file are the same properties that are used to configure LDAP integration in other Software AG products. See LDAP Properties for a full list of supported properties.

Example of an ldap.properties file for authentication:

To configure security event auditing, use the audit-log-dir property along with security-dir and at least one form of security (i.e. one of ssl-tls, authc, or whitelist). The directory specified in audit-log-dir must exist already, and must be appropriately access controlled to prevent illegitimate access to audit logs.

The IP whitelisting feature enables you as the cluster administrator to ensure that only clients from known IP addresses can access the TSA. You can use this feature to prevent malicious clients from establishing connections to the TSA.

A whitelist file is a plain-text file containing a list of IPs. Only clients configured with these IPs are allowed to access the TSA. The server IPs specified in the config file, and the localhost IPs of the server are always whitelisted. The whitelist file must be named whitelist.txt and placed in the security root directory.

The whitelist file follows these parsing rules:

The following is an example of a valid whitelist file:

To configure IP whitelisting, use whitelist along with the security-dir property.

If the whitelist.txt file is not found in the security root directory, or there is an error reading the file, the server startup will fail with an appropriate error message.

If hostnames are used in the config file, the server attempts to resolve these hostnames to IPs. If the resolution fails, the server startup fails with an appropriate error message. Note that hostname resolution is done for the config file only, and any hostnames present inside the whitelist.txt file are ignored.

A multi-stripe cluster should be started with the same whitelist.txt file contents. Any updates to this file should be performed on all the stripes, as described in the following section.

After a cluster is started with whitelisting enabled, entries can be dynamically added to or removed from the whitelist without the need for server restarts. To perform a dynamic update, edit the whitelist.txt file contained in the server security root directories, and run the ipwhitelist-reload command to notify the servers in the cluster to reload the whitelist.txt file. Refer to the The "ipwhitelist-reload" Command section for more details.

Errors during whitelist reload, if any, are logged in respective server logs. Thus, after every update operation, server logs should be checked to verify that the updates took effect on all the servers.

If a cluster is not yet activated and the whitelist file needs to be reloaded on the servers, the server-level ipwhitelist-reload command can be used. It may also be helpful when the machine from where the cluster tool is to be used is itself not whitelisted initially. In this scenario, adding this machine's IP to the whitelist, and running the server-level ipwhitelist-reload command ensures that cluster tool can configure the cluster later.

When a client connects to a server, the server accepts the socket connection, and verifies the IP of the incoming client connection against the whitelist. If it finds that the client IP is not whitelisted, it closes the socket connection.

If a whitelisted client is removed from the whitelist via a dynamic update, it remains connected to the cluster as long as there is no network disconnection or explicit connection closure from the client. Subsequent connection attempts from the client to cluster will fail.

This example illustrates the security configuration section in the configuration file of a single stripe, two node cluster (with node names node1 and node2), that configures auditing, encrypted connections, LDAP authentication and IP whitelisting:

With the configuration in the above example, the server's security root directory would contain a truststore in the trusted-authority subdirectory, a keystore and a credentials.properties in the identity directory, an ldap.properties in the access-control subdirectory and a whitelist.txt file.

The credentials.properties file is required so that the server can connect to other servers in the stripe.

To configure a client to connect to a secured cluster, you need to give the client a path to the client's security root directory. This should contain, for example, the credentials that the client needs to connect to the cluster.

To enable command-line tools to connect to a secure cluster, a command must be prefixed with -security-root-directory.

The following example shows the use of the config tool get command with the -security-root-directory option specified:

Attempting to connect to a secure cluster without the -security-root-directory option will fail. Commands without this option retain their behavior.

An Ehcache client can define either an XML or a programmatic configuration, both of which support security configuration. The following are the examples of usages of each: