Configure TLS
Communications via TLS/SSL can be enabled by setting "tls": "STRICT"
.
If the value is set to "OFF"
, the rest of the SSL configuration will not be considered.
Warning
If using TLS make sure to update the hostname of the node to use https
instead of http
{
"sslConfig": {
"tls": "[Authentication mode : OFF,STRICT]",
"serverTrustMode": "[Possible values: CA, TOFU, WHITELIST, CA_OR_TOFU, NONE]",
"serverKeyStore": "[Path to server keystore]",
"serverKeyStorePassword": "[Password required for server KeyStore]",
"serverTrustStore": "[Server trust store path]",
"serverTrustStorePassword": "[Password required for server trust store]",
"serverTlsKeyPath": "[Path to server TLS key path]",
"serverTlsCertificatePath": "[Path to server TLS cert path]",
"serverTrustCertificates": [
"[Array of truststore certificates if no truststore is defined.]"
],
"clientTrustMode": "[Possible values: CA, TOFU, WHITELIST, CA_OR_TOFU, NONE]",
"clientKeyStore": "[Path to client keystore. The keystore that is used when communicating to other nodes.]",
"clientKeyStorePassword": "[Password required for client KeyStore]",
"clientTrustStore": "[Path to client TrustStore]",
"clientTrustStorePassword": "[Password required for client trust store]",
"clientTlsKeyPath": "[Path to client TLS Key]",
"clientTlsCertificatePath": "[Path to client TLS cert]",
"clientTrustCertificates": [
"[Array of truststore certificates if no truststore is defined.]"
],
"knownClientsFile": "[TLS known clients file for the server. This contains the fingerprints of public keys of other nodes that are allowed to connect to this one.]",
"knownServersFile": "[TLS known servers file for the client. This contains the fingerprints of public keys of other nodes that this node has encountered.]",
"generateKeyStoreIfNotExisted": "[boolean]",
"environmentVariablePrefix": "[Prefix to uniquely identify environment variables for this particular server ssl configuration]"
}
}
When SSL is enabled, each node will need to have certificates and keys defined for both client-side and server-side. These can be defined in multiple ways:
- Secured & unsecured
.jks
(Java keystore) format filesserverKeyStore
,serverKeyStorePassword
,serverTrustStore
,serverTrustStorePassword
clientKeyStore
,clientKeyStorePassword
,clientTrustStore
,clientTrustStorePassword
.pem
format certificate and key filesserverTlsKeyPath
,serverTlsCertificatePath
,serverTrustCertificates
clientTlsKeyPath
,clientTlsCertificatePath
,clientTrustCertificates
Important
.jks
files take precedence over .pem
files if both are provided for client-side or server-side.
Keystores
Passwords
Passwords for secured .jks
keystores can be provided in multiple ways, and in the following order of precedence:
Prefixed environment variables
<PREFIX>_TESSERA_SERVER_KEYSTORE_PWD
,<PREFIX>_TESSERA_SERVER_TRUSTSTORE_PWD
<PREFIX>_TESSERA_CLIENT_KEYSTORE_PWD
,<PREFIX>_TESSERA_CLIENT_TRUSTSTORE_PWD
The prefixed environment variables are only applied to the servers with that environmentVariablePrefix
value defined in their configuration.
This allows, for example, a P2P and ADMIN server to be configured with different prefixes, P2P
and ADMIN
.
Different keystores can then be used for each server and the individual passwords provided with P2P_<...>
and ADMIN_<...>
.
Configuration file
serverKeyStorePassword
,serverTrustStorePassword
clientKeyStorePassword
,clientTrustStorePassword
Global environment variables
TESSERA_SERVER_KEYSTORE_PWD
,TESSERA_SERVER_TRUSTSTORE_PWD
TESSERA_CLIENT_KEYSTORE_PWD
,TESSERA_CLIENT_TRUSTSTORE_PWD
The global environment variables, if set, are applied to all server configurations defined in the configuration file
Example
If a P2P and ADMIN server are both configured with TLS then the values set for the global environment variables will be used for both). These values are ignored if the passwords are also provided in the configuration file or as prefixed environment variables.
Generating keystores
If keystores do not already exist, Tessera can generate .jks
(Java keystore) files for use with non-CA Trust Modes (see Trust Modes).
By setting "generateKeyStoreIfNotExisted": "true"
, Tessera will check whether files already exist at the paths provided in the serverKeyStore
and clientKeyStore
configuration values. If the files do not exist:
- New keystores will be generated and saved at the
serverKeyStore
andclientKeyStore
paths - The keystores will be secured using the corresponding passwords if they are provided (see Passwords)
PEM files
Below is a configuration sample for using the .pem
file format:
"sslConfig" : {
"tls" : "STRICT",
"generateKeyStoreIfNotExisted" : "false",
"serverTlsKeyPath" : "server-key.pem",
"serverTlsCertificatePath" : "server-cert.pem",
"serverTrustCertificates" : ["server-trust.pem"]
"serverTrustMode" : "CA",
"clientTlsKeyPath" : "client-key.pem",
"clientTlsCertificatePath" : "client-cert.pem",
"clientTrustCertificates" : ["client-trust.pem"]
"clientTrustMode" : "TOFU",
"knownClientsFile" : "knownClients",
"knownServersFile" : "knownServers"
}
Trust Modes
The Trust Mode for both client and server must also be specified. Multiple trust modes are supported:
TOFU
, WHITELIST
, CA
, CA_OR_TOFU
, and NONE
.
TOFU (Trust-on-first-use)
Only the first node that connects identifying as a certain host will be allowed to connect as
the same host in the future. When connecting for the first time, the host and its certificate
will be added to `knownClientsFile` (for server), or `knownServersFile` (for client).
These files will be generated if not already existed, using the values specified in
`knownClientsFile` and `knownServersFile`.
A configuration sample for `TOFU` trust mode is:
```json
"sslConfig" : {
"tls" : "STRICT",
"generateKeyStoreIfNotExisted" : "true",
"serverKeyStore" : "server-keystore",
"serverKeyStorePassword" : "tessera",
"serverTrustMode" : "TOFU",
"clientKeyStore" : "client-keystore",
"clientKeyStorePassword" : "tessera",
"clientTrustMode" : "TOFU",
"knownClientsFile" : "knownClients",
"knownServersFile" : "knownServers"
}
```
WHITELIST
Only nodes that have previously connected to this node and have been added to the knownClients
file will be allowed to connect.
Similarly, this node will only be allowed to make connections to nodes that have been added to the knownServers
file.
This trust mode will not add new entries to the knownClients
or knownServers
files.
With this trust mode, the whitelist files (knownClientsFile
and knownServersFile
) must be provided.
A configuration sample for WHITELIST
trust mode is:
"sslConfig" : {
"tls" : "STRICT",
"generateKeyStoreIfNotExisted" : "true",
"serverKeyStore" : "server-keystore",
"serverKeyStorePassword" : "tessera",
"serverTrustMode" : "WHITELIST",
"clientKeyStore" : "client-keystore",
"clientKeyStorePassword" : "tessera",
"clientTrustMode" : "WHITELIST",
"knownClientsFile" : "knownClients",
"knownServersFile" : "knownServers"
}
CA
Only nodes with a valid certificate and chain of trust are allowed to connect. For this trust mode, trust stores must be provided and must contain a list of trust certificates.
A configuration sample for CA
trust mode is:
"sslConfig" : {
"tls" : "STRICT",
"generateKeyStoreIfNotExisted" : "false", //You can't generate trust stores when using CA
"serverKeyStore" : "server-keystore",
"serverKeyStorePassword" : "tessera",
"serverTrustStore" : "server-truststore",
"serverTrustStorePassword" : "tessera",
"serverTrustMode" : "CA",
"clientKeyStore" : "client-keystore",
"clientKeyStorePassword" : "tessera",
"clientTrustStore" : "client-truststore",
"clientTrustStorePassword" : "tessera",
"clientTrustMode" : "CA",
"knownClientsFile" : "knownClients",
"knownServersFile" : "knownServers"
}