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:

There is a command line utility for generating bcrypt password hashes. The bcrypt script 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 to choose depends on both the performance of the servers on which authentication takes place and also how you decide to trade off security against 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 password from the console:

or directly from the command line:

The console form of the command is preferred because when a password is used on the command line, it can be written into files such as the command history and also readable using commands such as ps.

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. The term "clients" here refers to clients communicating with the Terracotta servers using the TSA wire protocol.

A whitelist file is a plain-text file containing a list of IPs. Only clients running on 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. An empty whitelist file has the semantics of blacklisting all the IPs, except the IPs fetched from the config file, and those corresponding to localhost.

The following rules need to be followed for a whitelist file to be considered valid, and the entries in it to be parsed properly:

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, or identical copies of the file. Similarly, when updates to the file are desired, they 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 individual Terracotta Server logs. Thus, after every update operation, server logs should be checked to verify that the updates took effect in 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.

Here is an example of a security configuration section in the config file of a single stripe, two node cluster, 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 keystore is required so that the server can prove to clients that it is the server they are expecting. The credentials.properties file is required so that the server can connect to other servers in the stripe. If there are no other servers in the stripe, the credentials.properties file should not be present.

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 -srd (or long option --security-root-directory).

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

Attempting to connect to a secure cluster without the -srd 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: