Truststores

Overview
In an enterprise environment, it is very common to have an internal root certificate authority (root CA) that signs all certificates used internally for TLS termination on HTTPS sites. While this trust is federated on the operating system level for all domain-connected Windows workstations, non-Windows servers are typically not configured the same way. Even on a Windows workstation, your Java runtime might not necessarily trust the enterprise root CA certificates.
If a Java application attempts to make a connection to an untrusted remote server, it will throw an SSLException and fail to connect.
Java Truststores
A Java truststore is a bundle of certificates used when establishing connections to remote servers (this could be internal or on the Internet). Each Java runtime ships with a default truststore called cacerts. Adding certificates directly into cacerts is usually not recommended unless there is a centrally-managed deployment process for all workstations and servers.
Bot Truststore
A bot requires connections to several servers like the key manager or API agent, as defined in your bot configuration. This configuration should also define the path to a custom truststore, which ensures that the trust relationship is maintained even as the bot's deployment location is moved, as long as the truststore file is moved together with the deployment artifacts.
Java SDK / BDK 1.0
The Java SDK and BDK 1.0 uses the Java Key Store (JKS) format for its truststore. Your config.json should look like this:
1
{
2
  // ...
3
  "truststorePath": "path/to/my-truststore.jks",
4
  "truststorePassword": "changeit"
5
}
Copied!
BDK 2.0
The BDK 2.0 uses the JKS format, but the configuration has moved under the ssl section:
1
ssl:
2
  trustStorePath: path/to/my-truststore.jks
3
  trustStorePassword: changeit
Copied!
Python SDK
The Python SDK uses a concatenated PKCS format. Your config.json should look like this:
1
{
2
  // ...
3
  "truststorePath": "path/to/my-truststore.pem",
4
  "truststorePassword": "changeit"
5
}
Copied!
You can follow the same steps as the Java process below for Python, except instead of using keytool to import the certificates, simply concatenate all the certificates into a single file.
Certificate Chains
A typical internal certificate has has least 2 certificates in its chain - the certificate itself as well as the root CA certificate that signed it. Some enterprises will have intermediate CAs to form a 3-certificate chain. When Java establishes a connection to a remote server, it requires all signing certificates in that chain to be trusted. Hence, when building a truststore, you will need to import every signing certificate in the chain of each remote server that is not already present in the cacerts bundle.
Publicly-trusted signing certificates from established certificate authorities are already in cacerts so you will most likely not need to import certificates for services on the public Internet. However, if the Java runtime you are using pre-dates the existence of those certificates, then you will need to add them manually.
Building a Java Truststore
The keytool command that ships with all Java runtimes is used to manage truststores. You can build a new truststore or append to an existing one using the same command as follows:
1
keytool -import -file my_cert_file -alias my_cert_alias -keystore my_truststore \
2
   -storepass my_store_password -trustcacerts
Copied!
Automatic: Convenience Shell Script
You may use the following convenience shell script to automatically build out a new truststore based on a list of servers. Please remember to include all possible connections that your bot requires. This may include: all Key Manager servers, all API Agent servers, the Symphony pod, any other third-party or internal endpoints that the bot will interact with.
1
#!/bin/bash
2
SERVERS=my-key-manager-2:8443,my-agent:443,my-company.symphony.com:443
3
TRUSTSTORE_FILENAME=truststore
4
TRUSTSTORE_PASSWORD=changeit
5
​
6
command -v keytool >/dev/null 2>&1||{ echo >&2 "Please add keytool to \$PATH";exit 1;}
7
​
8
# Download all certificates from all servers
9
for SERVER in $(echo $SERVERS | sed "s/,/ /g")
10
do
11
  HOSTNAME="${SERVER%%:*}"
12
  openssl s_client -showcerts -verify 5 -connect $SERVER< /dev/null | \
13
    awk -v h=$HOSTNAME '/BEGIN/,/END/{ if(/BEGIN/){a++}; out=h"-"a-1".crt"; print >out}'
14
done
15
​
16
# Remove end certificates
17
rm *-0.crt
18
​
19
# Loop unique list of signing certificates
20
for cert in `shasum *-*.crt | sort -k1 | uniq -w41 | sort -k2 | awk '{print $2}'`
21
do
22
  keytool -import -file $cert -alias $cert -trustcacerts -noprompt \
23
    -keystore $TRUSTSTORE_FILENAME -storepass $TRUSTSTORE_PASSWORD
24
done
25
​
26
# Cleanup and verify truststore
27
rm *-*.crt
28
keytool -list -keystore $TRUSTSTORE_FILENAME -storepass $TRUSTSTORE_PASSWORD
Copied!
Manual: Collating Certificates in Windows
If you have no access to a Linux-based shell, you can also manually perform this process within a Windows environment. All you need is a browser and a Java runtime with keytool installed.
Step 1: Visit an endpoint on each server in your browser and view the certificate
Step 2: Select the next signing certificate
In the Certification Path tab, select the end certificate's parent and View Certificate
Step 3: Export the certificate
In the Details tab, click Copy to File.. and select the Base-64 encoded X.509 option then save the certificate to disk.
Step 4: Repeat for the rest of the chain
Repeat Steps 2 and 3 until you have exported all signing certificates in the chain.
Step 5: Build the trust store
Launch command prompt and repeat this command for each exported certificate
1
keytool -import -file my_cert_file -alias my_cert_alias -keystore my_truststore \
2
  -storepass my_store_password -trustcacerts -noprompt
Copied!
You can verify the entries by using the -list option:
1
keytool -list -keystore my_truststore -storepass my_store_password
Copied!

Bot Permissions

Next - Building Bots on Symphony

Authentication

Last modified 1yr ago

Copy link

Contents

Building a Java Truststore

Automatic: Convenience Shell Script

Manual: Collating Certificates in Windows