Basic Connection Security

You can secure the connections between the TMS and managed agents using a built-in hash-based message authentication scheme and digital certificates, also known as "identity assertion" (IA). Use this level of security in environments where the TMS might be exposed to unwanted connection attempts from rogue agents, or where managed agents might come under attack from a rogue TMS.

Note: To fully secure connections between the TMS and managed agents, it is recommended that SSL be used for encryption. For information about adding SSL to a connection, see Adding SSL.

To set up identity assertion, complete the following steps:

Configure identity assertion as described in Configuring Identity Assertion.

Create a shared secret for the TMS and the managed agents as described in Creating a Shared Secret.

The TMS must have a truststore containing the public-key certificate of every agent that connects to it. If you are not using a Certificate Authority (which provides the public keys), export public keys from the self-signed certificates in the keystore of each agent using a command similar to the following:

keytool -export -alias myAgent -keystore keystore-file.jks \
-file myAgentCert.cert

Then import the keys into the TMS truststore, creating it as shown (if it does not already exist):

keytool -import -alias myAgent -file myAgentCert.cert \
-keystore truststore.jks

When you use the keytool utility, you can maintain additional certificates for the chain of trust in a file cacerts. If you wish to use these additional certificates for the import, refer to the use of the option -trustcacerts in the documentation of the keytool utility.

Tip: As an alternative to using the command line tool keytool, you might want to try the open source graphical tool KeyStore Explorer, available at http://www.keystore-explorer.org/index.html.

If a managed agent does not have a keystore, set one up. For examples, see the BigMemory Max Security Guide.

Make your truststore available to the TMS in one of the following ways:

Alternatively, you can import these public keys into the default truststore for the JVM (typically the cacerts file).

Note: If a different default location for TMS-related files is required, set it using the system property com.tc.management.config.directory.

To configure identity assertion (IA) for the Terracotta Server Array, see the BigMemory Max Security Guide.

To configure IA on a Terracotta client, enable security (authentication by IA) on the REST service by adding the securityServiceLocation attribute to the managementRESTService element in the managed agent's configuration. The following example is for Ehcache:

If securityServiceLocation is not set, the authentication feature is disabled. To enable it, set its value to the URI used to connect to the TMC, with /tmc/api/assertIdentity appended. In the example above, "http://localhost:9889" is the TMC URI.

For BigMemory Go, use the same procedure as for a Terracotta client.

You must create a password (or secret) that is shared between the TMS and managed agents, storing it in a Terracotta keychain file.

The scripts required in the following procedures are found in ${BIGMEMORY_GO_HOME}/management-console/bin or ${BIGMEMORY_MAX_HOME}/tools/management-console/bin. Use the equivalent .bat scripts for Microsoft Windows.

1. Create a shared secret for the assertion of trust between the TMS and managed agents by running the following script:

where <agent-url> is the URI of the agent. This value should correspond exactly to the URI you use in the TMC to connect to the given agent. For example:

The script automatically creates the Terracotta keychain file <user_home>/.tc/mgmt/keychain if it does not already exist. Do not move or delete this keychain file because it must remain accessible to the TMS at that location.

2. When prompted, enter a shared secret of your choice. Be sure to remember the secret that you enter because you might need to enter it again in a later step.

3. Run the add-tc-agent script once for each agent, using that agent's URI. The script saves these entries to the same keychain file.

1. Each agent with a keychain entry must also have access to the same shared secret through a Terracotta keychain file:

./keychain.sh -c <user_home>/.tc/mgmt/agentKeychainFile \
http://myHost:9889/tc-management-api

where <tmc-url> is the URI used to connect to the TMC, with /tc-management-api appended. If the named keychain file already exists on the node, omit the -c flag. Agents running on the same node can share a keychain file.

Terracotta Management Console - Keychain Client
KeyChain file successfully created in /path/to/agentKeychainFile
Open the keychain by entering its master key:

Enter the password you wish to associate with this URL:
Password for http://myHost:9889/ successfully stored

The secret you enter must match the one entered for the TMS. Note that the script's success acknowledgment does not confirm that the secret matches the one stored on the TMS.