Configuring SSL/TLS for Akka
Configuring SSL/TLS for Akka in an On-Premises Environment
 |
This distributed capability is available after ThingWorx 9.4 and up.
|
To configure SSL for Akka when using ThingWorx HA clustering in an on-premises environment, perform the following steps:
1. Create a keystore and truststore, which all platforms will use.
|
|
The keyword secret can be replaced with a customized password. Use this password to access the created keystore and truststore.
|
a. To create a keystore with a public and private key, execute the following command in your terminal:
keytool -v -genkeypair -dname "CN=SEEKERS,OU=RND,O=PTC,C=IL" -keystore akka-keystore.jks -storepass secret -keyalg RSA -keysize 2048 -alias server -validity 3650 -deststoretype pkcs12 -ext KeyUsage=digitalSignature,dataEncipherment,keyEncipherment,keyAgreement -ext ExtendedKeyUsage=serverAuth,clientAuth -ext SubjectAlternativeName:c=DNS:localhost,IP:127.0.0.1
b. Export the server certificate.
keytool -v -exportcert -file server.cer -alias server -keystore akka-keystore.jks -storepass secret -rfc
c. Create the truststore for the client and import the server certificate with the following command:
keytool -v -importcert -file server.cer -alias server -keystore akka-truststore.jks -storepass secret -noprompt
2. Create a keystore.conf with the following content:
{
security {
secret-provider = "com.thingworx.security.provider.keystore.KeyStoreProvider"
default-encryption-key-length = 128
keystore {
password-file-path = "I:\\ThingworxPlatform"
password-file-name = "keystore-password"
path = "I:\\ThingworxStorage"
name = "keystore"
}
}
}
security {
secret-provider = "com.thingworx.security.provider.keystore.KeyStoreProvider"
default-encryption-key-length = 128
keystore {
password-file-path = "I:\\ThingworxPlatform"
password-file-name = "keystore-password"
path = "I:\\ThingworxStorage"
name = "keystore"
}
}
}
|
|
password-file-path should be the path to the ThingworxPlatform folder. path should be the path to the ThingworxStorage folder.
|
The following is relevant for a, b, and c. Add the keystore and truststore passwords into the ThingWorx internal keystore to protect these values.
a. In the following substeps, we will use security-common-cli, an internal ThingWorx tool to insert secrets into the keystore. The security-common-cli tool should exist in the installation folder. For more information, visit the Security Management Tool in the help center. Repeat this process for each platform, if needed, with different versions of keystore.conf specifying the following parameters: password-file-path and path.
b. Using the security-common-cli tool, from the command line, run the following command (specify the valid path to the security-common-tool)
:
cd [...]\security-common-cli-<latest>\bin
security-common-cli
security-common-cli
c. From thesecurity-common-cli terminal, run the following commands and replace secret with your custom passwords for the keystore and the truststore. Enter the valid keystore.conf path.
> init [...]\keystore.conf
> set encrypt.akka.keystore.password "secret"
> set encrypt.akka.truststore.password "secret"
> set encrypt.akka.keystore.password "secret"
> set encrypt.akka.truststore.password "secret"
3. Place the files akka-keystore.jks and akka-truststore.jks in a known path. The path can be relative or absolute. For example, a relative path would be/ThingworxPlatform/[...]/akka-keystore.jks. An example of an absolute path would be C:/akkaCerts/akka-keystore.jks.
|
|
You should only have one copy of akka-keystore.jks and akka-truststore.jks. Because you create these files once for all the platforms in the cluster and use the same files for all the platforms, you need to use the same copies for each platform.
|
|
|
It is recommended that you place the files in the/ThingworxPlatform folder and use a relative path.
|
4. Edit ThingworxPlatform\platform-settings.json and add the following parameters under the AkkaSettings section: AkkaSSLEnabled, AkkaKeyStore, AkkaTrustStore, AkkaKeyStorePassword, AkkaTrustStorePassword, AkkaTlsProtocolVersion, as described in Platform Settings for ThingWorx HA. Provide the valid akka-keystore.jks and akka-truststore.jks path.
Example:
"AkkaSSLEnabled": true,
"AkkaKeyStore":"[...]/akka-keystore.jks",
"AkkaTrustStore":"[...]/akka-truststore.jks",
"AkkaKeyStorePassword":"encrypt.akka.keystore.password",
"AkkaTrustStorePassword":"encrypt.akka.truststore.password"
"AkkaTlsProtocolVersion":"TLSv1.2"
"AkkaKeyStore":"[...]/akka-keystore.jks",
"AkkaTrustStore":"[...]/akka-truststore.jks",
"AkkaKeyStorePassword":"encrypt.akka.keystore.password",
"AkkaTrustStorePassword":"encrypt.akka.truststore.password"
"AkkaTlsProtocolVersion":"TLSv1.2"
|
|
AkkaTlsProtocolVersion is an optional parameter. The default value for this parameter is TLSv1.2, which, if necessary, can be changed in the future.
|
5. Restart the application.