TLS

Usage

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.

If using TLS make sure to update the hostname of the node to use https instead of http

Keystores

When SSL is enabled, each node will need to have keystores defined for both client side and server side. If these files do not already exist, they can be generated by setting "generateKeyStoreIfNotExisted": "true". The values of serverKeyStore and clientKeyStore will determine the name and location of these generated files. The keystores can be secured by providing passwords in serverKeyStorePassword and clientKeyStorePassword. The generated files will be in .jks (Java keystore) format.

Paths to keys and certificates can be provided using serverTlsKeyPath and serverTlsCertificatePath (for server-side config) and clientTlsKeyPath and clientTlsCertificatePath (for client-side config).

Keys and certificates using the .pem format are also supported, however a Java keystore (specified by serverKeyStore and clientKeyStore) will always be used as priority. Therefore if .pem is the preferred method, ensure that these properties are not included in the config. Additionally, generateKeyStoreIfNotExisted will need to be set to false, otherwise Tessera will try to generate a .jks keystore by default.

Below is a config 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 config sample for TOFU trust mode is:

  "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 config 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 config 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"
  }
  

---

Sample SSL config

{
  "sslConfig": {
    "tls": "[Authentication mode : OFF,STRICT]",
    "generateKeyStoreIfNotExisted": "[boolean]",
    "serverKeyStore": "[Path to server keystore]",
    "serverTlsKeyPath": "[Path to server TLS key path]",
    "serverTlsCertificatePath": "[Path to server TLS cert path]",
    "serverKeyStorePassword": "[Password required for server KeyStore]",
    "serverTrustStore": "[Server trust store path]",
    "serverTrustCertificates": [
      "[Array of truststore certificates if no truststore is defined.]"
    ],
    "serverTrustStorePassword": "[Password required for server trust store]",
    "serverTrustMode": "[Possible values: CA, TOFU, WHITELIST, CA_OR_TOFU, NONE]",
    "clientKeyStore": "[Path to client keystore. The keystore that is used when communicating to other nodes.]",
    "clientTlsKeyPath": "[Path to client TLS Key]",
    "clientTlsCertificatePath": "[Path to client TLS cert]",
    "clientKeyStorePassword": "[Password required for client KeyStore]",
    "clientTrustStore": "[Path to client TrustStore]",
    "clientTrustCertificates": [
      "[Array of truststore certificates if no truststore is defined.]"
    ],
    "clientTrustStorePassword": "[Password required for client trust store]",
    "clientTrustMode": "[Possible values: CA, TOFU, WHITELIST, CA_OR_TOFU, NONE]",
    "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.]"
  }
}