SSL/TLS Security Configuration in Terracotta
Terracotta supports the following modes of security:
1. SSL/TLS-based: Secures the entire cluster with encrypted connections using Transport Layer Security (TLS) protocol (formerly known as Secure Sockets Layer (SSL) Protocol), and provides two-way verification of the identities of the two hosts involved in the communication. This includes securing communication across the servers in the cluster, as well as between clients and the cluster.
2. IP whitelist based: Allows you to ensure that only clients from known IP addresses can access the TSA.
This document assumes a good understanding of SSL/TLS fundamentals, and only describes SSL/TLS security configuration in Terracotta. For information on IP whitelist based security, see the section
Securing TSA Access using a Permitted IP List.
Security root directory
To configure SSL/TLS security, each client and server must have a security root directory. It is the central place for certificates, and other security-related files.
Important: Certificates must be created using the RSA algorithm, preferably with a key size of 4096.
The security root directory, and the files and directories contained in it should be readable by the respective client or server process.
If IP whitelisting based security is needed, this directory should contain a single plain-text file named whitelist.txt.
If SSL/TLS based security is needed, this directory should contain the following two sub-directories as explained below:
identity: contains keystore files with this host's private key and the host's certificate. This directory should only be readable by users who are authorized to run the respective Terracotta client or server.
trusted-authority: contains truststore files with certificates trusted by this host.
Important: Ensure that the identity directory is readable only by users who are authorized to run the respective Terracotta client or server.
Certificate generation
Keystore rules
Keystores can be generated in any way desirable, and placed in the identity directory, as long as the following rules are followed:
Keystore must be of type
jks.
Keystore filename must be in
${common name}-${yyyyMMddThhmmss}.jks format (e.g.
com.organization.host-20180223T102319.jks).
yyyyMMddThhmmss should represent the time of creation (timestamp) of the file. When multiple keystores are present, the keystore with the latest timestamp will be used.
Keystore must have only one
terracotta_security_alias entry, and it should contain a private key and the host's certificate.
Common Name field in the Distinguished Name in the host's certificate must match the host name and the common name fragment in the keystore filename.
Private key and the host's certificate must be within its period of validity.
Password for the keystore and the
terracotta_security_alias store entry must be
terracotta_security_password.
Certificate must be created using the RSA algorithm, preferably with a key size of 4096.
Truststore rules
Similarly, truststores could be generated in any way desirable, and placed in the trusted-authority directory, as long as the following rules are followed:
Truststore must be of type
jks.
Truststore filename must be in
trusted-authority-${yyyyMMddThhmmss}.jks format (e.g.
trusted-authority-20180223T102319.jks). When multiple truststores are present, all the truststores will be used.
Truststore must have only one
terracotta_security_alias entry, and it should contain a trusted certificate.
Trusted certificate must be within its period of validity.
Password for the truststore must be
terracotta_security_password.
Certificate must be created using the RSA algorithm, preferably with a key size of 4096.
Certificate rotation
If the certificates expire or get compromised, they must be rotated. Following are the different ways of rotating them:
Certificate rotation with cluster shutdown
The followed steps need to be performed in order:
1. Generate new keystore and truststore files following the rules mentioned in the Keystore rules and Truststore rules topics above.
2. Shut down all the servers and clients.
3. Replace the old keystores and truststores with the new keystores and truststores in the corresponding identity and trusted-authority directories of each client and server.
4. Start all the servers and the clients for the new certificates to take effect.
The above sequence has the advantage that it is simple to perform, with the drawback of requiring the entire cluster and the clients to be restarted.
Certificate rotation with rolling restarts
The followed steps need to be performed in order:
1. Generate new keystore and truststore files following the rules mentioned in the Keystore rules and Truststore rules topics above.
2. Deploy new truststores in corresponding trusted-authority directories of each client and server.
3. Restart all the passive servers and clients. Once the passive servers reach PASSIVE-STANDBY status, restart all the active servers.
4. Replace old keystores with the new keystores in corresponding identity directories of each client and server.
5. Restart all the passive servers and clients. Once the passive servers reach PASSIVE-STANDBY status, restart all the active servers.
6. Delete old truststores from corresponding trusted-authority directories of each client and server.
7. Restart all the passive servers and clients. Once the passive servers reach PASSIVE-STANDBY status, restart all the active servers.
The above sequence has the advantage that it does not require cluster downtime, with the drawback of having a significant number of steps.
Changes needed to enable security
Once the required security root directories are created, they can be used to enable SSL/TLS connections. The following examples illustrate how to do it on the server and different Terracotta clients:
Terracotta Server
The following are examples of additions to Terracotta configuration file(s) that need to be made in different security configurations:
1. When only SSL/TLS based security is needed:
<service>
<security xmlns="http://www.terracottatech.com/config/security">
<security-root-directory>/path/to/security-root-directory
</security-root-directory>
<ssl-tls/>
</security>
</service>
1. When both SSL/TLS and IP whitelist based security are needed:
<service>
<security xmlns="http://www.terracottatech.com/config/security">
<security-root-directory>/path/to/security-root-directory
</security-root-directory>
<ssl-tls/>
<whitelist/>
</security>
</service>
1. When only IP whitelist based security is needed:
<service>
<security xmlns="http://www.terracottatech.com/config/security">
<security-root-directory>/path/to/security-root-directory
</security-root-directory>
<whitelist/>
</security>
</service>
Cluster tool
To enable the cluster tool to connect to a secure cluster, each cluster tool command must be prefixed with -srd (or long option --security-root-directory) as in the following example:
./cluster-tool.sh -srd /path/to/security-root-directory
configure -l ~/license.xml
-n tc-cluster ~/tc-config-stripe-1.xml ~/tc-config-stripe-2.xml
Configuration successful
License installation successful
Command completed successfully.
Attempting to connect to a secure cluster without the
-srd option will fail. Commands without this option retain their behavior. For more information on cluster tool commands, see
Cluster Tool.
Ehcache Client
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:
1. API Example
PersistentCacheManager cacheManager = CacheManagerBuilder
.newCacheManagerBuilder()
.with(EnterpriseClusteringServiceConfigurationBuilder.
enterpriseSecureCluster(connectionURI, securityRootDirectoryPath) (1)
.autoCreate())
.build(true);
1 | EnterpriseClusteringServiceConfigurationBuilder enterpriseSecureCluster(URI, Path) lets you create a CacheManager using a secure connection. The first argument is the URI of the Terracotta cluster, appended with the CacheManager name. The second argument is the path to the client's security root directory. The EnterpriseClusteringServiceConfigurationBuilder enterpriseCluster(URI) API continues to provide unsecured connections to unsecured clusters. |
2. XML Example
<ehcache:config
xmlns:ehcache="http://www.ehcache.org/v3"
xmlns:tc="http://www.terracottatech.com/v3/terracotta/ehcache">
<ehcache:service>
<tc:cluster>
<tc:connection url="${cluster-uri}/CM"
security-root-directory="${security-root-directory}"/> (1)
<tc:server-side-config auto-create="true"/>
</tc:cluster>
</ehcache:service>
</ehcache:config>
1 | security-root-directory lets you specify the path to the client's security root directory. Not passing this option retains the behavior of communicating with an unsecured cluster. |
TC Store Client
DatasetManager datasetManager =
DatasetManager.secureClustered(connectionURI, securityRootDirectoryPath) (1)
.build();
1 | DatasetManager.secureClustered(URI, Path) lets you create a DatasetManager using a secure connection. The first argument is the URI of the Terracotta cluster. The second argument is the path to the security root directory which is to be used for the connection. The DatasetManager.clustered(URI) API continues to provide unsecured connections to unsecured clusters. |
Terracotta Management Console
For information on configuring SSL/TLS based security, see the topic
Security in the section
Getting Started with the Terracotta Management Console.