Static Configuration

Canton differentiates between static and dynamic configuration. Static configuration is immutable and therefore has to be known from the beginning of the process start. An example for a static configuration are the connectivity parameters to the local persistence store or the port the admin-apis should bind to. On the other hand, connecting to a domain or adding parties however is not a static configuration and therefore is not set via the config file but through the adminstration APIs or the console.

initialization of Canton nodes.

The configuration files themselves are written in HOCON format with some extensions:

  • Durations are specified scala durations using a <length><unit> format. Valid units are defined by scala directly, but behave as expected using ms, s, m, h, d to refer to milliseconds, seconds, minutes, hours and days. Durations have to be non-negative in our context.

Canton does not run one node, but any number of nodes, be it domain or participant nodes in the same process. Therefore, the root configuration allows to define several instances of domain and participant nodes together with a set of general process parameters.

A sample configuration file for two participant nodes and a single domain can be seen below.

canton {
  parameters {
    manual-start = yes
  }
  participants {

    participant1 {
      storage {
        type = memory
      }

      admin-api {
        port= 5012
      }

      ledger-api {
        port = 5011
      }
    }

    participant2 {
      storage {
        type = memory
      }

      admin-api {
        port= 5022
      }

      ledger-api {
        port = 5021
      }
    }
  }

  domains {
    mydomain {
      storage {
        type = memory
      }

      public-api.port = 5018
      admin-api.port = 5019

    }
  }

}

HOCON supports substituting environment variables for config values using the syntax key = ${ENV_VAR_NAME}.

Configuration Compatibility

The enterprise edition configuration files extend the community configuration. As such, any community configuration can run with an enterprise binary, whereas not every enterprise configuration file will also work with community versions.

Advanced Configurations

Configuration files can be nested and combined together. First, using the include directive (with relative paths), a configuration file can include other configuration files.

canton {
    domains {
        include "domain1.conf"
    }
}

Second, by providing several configuration files, we can override configuration settings using explicit configuration option paths:

canton.participants.myparticipant.admin-api.port = 11234

Those defined first will have precedence if the same key is included in multiple configurations.

Configuration Mixin

Even more than multiple configuration files, we can leverage pureconfig to create shared configuration items that refer to environment variables. A handy example is the following, which allows to share database configuration settings in a setup involving several participant or domain nodes:

# shared configuration elements are placed in a key outside of canton so they won't be validated
# by pureconfig until they are substituted into the main config below
_shared {
# shared persistent storage definition
# storage.db-name must be specified at the substitution site as this cannot be shared
  storage {
    type = postgres
    config {
      dataSourceClass = "org.postgresql.ds.PGSimpleDataSource"
      properties = {
        serverName = ${CANTON_DB_HOST}
        portNumber = ${CANTON_DB_PORT}
        user = ${CANTON_DB_USER}
        password = ${CANTON_DB_PASSWORD}
      }
      connectionPool = HikariCP
      maxConnections = 8
      maxThreads = 8
      numThreads = 8
    }
  }
}

Such a definition can subsequently be referenced in the actual node definition:

canton {
    domains {
        mydomain {
            storage = ${_shared.storage}
            storage.config.properties.databaseName = ${CANTON_DB_NAME_DOMAIN}
        }
    }
}

Persistence

Participant and domain nodes both require storage configurations. Both use the same configuration format and therefore support the same configuration options. There are three different configurations available:

  1. Memory - Using simple, hash-map backed in-memory stores which are deleted whenever a node is stopped.
  2. H2 - Based on the H2-database engine.
  3. Postgres - To use with the open source relational database Postgres.

In order to set a certain storage type, we have to edit the storage section of the particular node, such as canton.participants.myparticipant.storage.type = memory. Memory storage does not require any other setting.

For the actual database driver, Canton does not directly define how they are configured, but leverages a third party library (slick) for it, exposing all configuration methods therein. Therefore, please refer to the respective detailed documentation to learn about all configuration options.

It is recommended to use a connection pool in production environments and consciously choose the size of the pool.

Please note that Canton will create, manage and upgrade the database schema directly. You don’t have to create tables yourselves.

Consult the example/03-advanced-configuration directory to get a set of configuration files to set your nodes up.

Postgres

The Slick configuration allows to either define the driver directly or use the respective dataSource objects. An example for a driver based definition for Postgres configuration would read:

# Postgres persistence configuration mixin
#
# This file defines a shared configuration resources. You can mix it into your configuration by
# refer to the shared storage resource and add the database name.
#
# Example:
#   participant1 {
#     storage = ${_shared.storage}
#     storage.database-name = "participant1"
#
# The user and password credentials are set to "canton" and "supersafe". As this is not "supersafe", you might
# want to either change this configuration file or pass the settings in via environment variables.
#
# NOTE: If you set storage.database-name = "...", then this database-name will be inserted by Canton into the
# storage.config.databaseName setting. The motivation behind this is that we can share the same database configuration
# between nodes if we run several of them in the same process (e.g. domain and participant node, or demos and tests).
#
_shared {
  storage {
    type = postgres
    config {
      dataSourceClass = "org.postgresql.ds.PGSimpleDataSource"
      properties = {
        serverName = "localhost"
        serverName = ${?CANTON_DB_HOST}
        portNumber = "5432"
        portNumber = ${?CANTON_DB_PORT}
        # the database name can be defined here, but for sharing the configuration, we can omit the setting here
        # and define it separately
        databaseName = "canton-database"
        databaseName = ${?CANTON_DB_NAME}
        user = "canton"
        user = ${?CANTON_DB_USER}
        password = "supersafe"
        password = ${?CANTON_DB_PASSWORD}
      }
      # Points to consider here:
      # - Configure `numThreads`. As a rule of thumb, choose a value between 2 and 8.
      #   When processing transactions with huge numbers of inputs, a bigger value may make sense.
      # - We are not aware of a scenario where it makes sense to also configure `maxConnections` (alias: `maximumPoolSize`).
      # - It never makes sense to configure `maxConnections` to be smaller than `numThreads`.
      numThreads = 8
    }
  }
}

There is an alternative configuration which expects the jdbc-url:

# Alternative Postgres persistence configuration mixin
#
# This is the second style how postgres databases can be configured. The `url` allows you to define more properties,
# at the cost of simplicity. Please consult the manual(s) for an in-depth explanation of the possible options.
_shared {
  storage {
    type = postgres
    config {
      url = "jdbc:postgresql://0.0.0.0:5432/canton-database"
      user = "canton"
      password = "supersafe"
      driver = org.postgresql.Driver
    }
  }
}

Please refer to the respective Slick configuration settings for detailed setup instructions and options, including the reference guide. The above configurations are included in the examples/03-advanced-configuration folder and are sufficient to get going.

H2 Database

In some cases, the overhead of running a separate database is not desired. For these situations, the H2-database engine can be leveraged.

Canton allows a user to directly access the underlying H2 setup settings which allows the administrator to use all available H2 modes directly.

The canonical example of using H2 with a file-backed database is given by

# File based H2 configuration mixin
#
# This file defines a shared configuration resources. You can mix it into your configuration by
# refer to the shared storage resource and add the database name.
#
# Example:
#   participant1 {
#     storage = ${_shared.storage}
#     storage.database-name = "participant1"
_shared {
  storage {
    type = "h2"
    config = {
      url = "jdbc:h2:file:./canton-data;MODE=PostgreSQL;LOCK_TIMEOUT=10000;DB_CLOSE_DELAY=-1"
      user = "canton"
      password = "morethansafe"
      driver = org.h2.Driver
    }
  }
}

If you are looking for any other H2 setup, please consult the H2 manual directly.

Api Configuration

A domain node exposes two main APIs: the admin-api and the public-api, while the participant node exposes the ledger-api and the admin-api. In this section, we will explain what the APIs do and how they can be configured. All APIs are based on GRPC, which is an efficient RPC and streaming protocol with client support in almost all relevant programming languages. Native bindings can be built using the API definitions.

Administration API

The nature and scope of the admin api on participant and domain nodes has some overlap. As an example, you will find the same key management commands on the domain and the participant node API, whereas the participant has different commands to connect to several domains.

The configuration currently is simple (see the TLS example below) and just takes an address and a port. The address defaults to 127.0.0.1 which means that in most cases you just need to configure the port number.

You should not expose the admin-api publicly in an unsecured way as it serves administrative purposes only.

TLS Configuration

Both, the Ledger API and the admin API provide the same TLS capabilities and can be configured using the same configuration directives. TLS provides end-to-end channel encryption between the server and client, and depending on the settings, server or mutual authentication.

A full configuration example is given by

  ledger-api {
    address = "127.0.0.1" // IP / DNS must be SAN of certificate to allow local connections from the canton process
    port = 5041
    tls {
      // the certificate to be used by the server
      cert-chain-file = "./tls/participant.crt"
      // private key of the server
      private-key-file = "./tls/participant.pem"
      // trust collection, which means that all client certificates will be verified using the trusted
      // certificates in this store. if omitted, the JVM default trust store is used.
      trust-collection-file = "./tls/root-ca.crt"
      // define whether clients need to authenticate as well (default not)
      client-auth = {
        // none, optional and require are supported
        type = require
        // If clients are required to authenticate as well, we need to provide a client
        // certificate and the key, as Canton has internal processes that need to connect to these
        // APIs. If the server certificate is trusted by the trust-collection, then you can
        // just use the server certificates. Otherwise, you need to create separate ones.
        admin-client {
          cert-chain-file = "./tls/admin-client.crt"
          private-key-file = "./tls/admin-client.pem"
        }
      }
      // protocols = ...
      // ciphers = ...
    }
  }

These TLS settings allow a connecting client to ensure that it is talking to the right server. In this example, we have also enabled client authentication, which means that the client needs to present a valid certificate (and have the corresponding private key). The certificate is valid if it has been signed by a key in the trust store.

The trust-collection-file allows us to provide a file based trust store. If omitted, the system will default to the built-in JVM trust store. The file must contain all client certificates (or parent certificates which were used to sign the client certificate) who are trusted to use the API. The format is just a collection of PEM certificates (in the right order or hierarchy), not a java based trust store.

In order to operate the server just with server-side authentication, you can just omit the section on client-auth. However, if client-auth is set to require, then Canton also requires a client certificate, as various Canton internal processes will connect to the process itself through the API.

All the private keys need to be in the pkcs8 PEM format.

By default, Canton only uses new versions of TLS and strong ciphers. You can also override the default settings using the variables ciphers and protocols. If you set these settings to null, the default JVM values will be used.

Note

Error messages on TLS issues provided by the networking library netty are less than optimal. If you are struggling with setting up TLS, please enable DEBUG logging on the io.netty logger.

If you need to create a set of testing TLS certificates, you can use the following openssl commands:

#!/bin/bash

mkdir tls
cd tls

DAYS=730

function create_key {
  local name=$1
  openssl genrsa -out "${name}.key" 4096 -days ${DAYS}
  # netty requires the keys in pkcs8 format, therefore convert them appropriately
  openssl pkcs8 -topk8 -nocrypt -in "${name}.key" -out "${name}.pem"
}

# create self signed certificate
function create_certificate {
  local name=$1
  local subj=$2
  openssl req -new -x509 -sha256 -key "${name}.key" \
              -out "${name}.crt" -days ${DAYS} -subj "$subj"
}

# create certificate signing request with subject and SAN
# we need the SANs as our certificates also need to include localhost or the
# loopback IP for the console access to the admin-api and the ledger-api
function create_csr {
  local name=$1
  local subj=$2
  local san=$3
  (
    echo "authorityKeyIdentifier=keyid,issuer"
    echo "basicConstraints=CA:FALSE"
    echo "keyUsage = digitalSignature, nonRepudiation, keyEncipherment, dataEncipherment"
  ) > ${name}.ext
  if [[ -n $san ]]; then
    echo "subjectAltName=${san}" >> ${name}.ext
  fi
  # create certificate (but ensure that localhost is there as SAN as otherwise, admin local connections won't work)
  openssl req -new -sha256 -key "${name}.key" -out "${name}.csr" -subj "$subj"
}

function sign_csr {
  local name=$1
  local sign=$2
  openssl x509 -req -sha256 -in "${name}.csr" -extfile "${name}.ext" -CA "${sign}.crt" -CAkey "${sign}.key" -CAcreateserial  \
               -out "${name}.crt" -days ${DAYS}
  rm "${name}.ext" "${name}.csr"
}

function print_certificate {
  local name=$1
  openssl x509 -in "${name}.crt" -text -noout
}

# create root certificate
create_key "root-ca"
create_certificate "root-ca" "/O=TESTING/OU=ROOT CA/emailAddress=canton@digitalasset.com"
#print_certificate "root-ca"

# create domain certificate
create_key "domain"
create_csr "domain" "/O=TESTING/OU=DOMAIN/CN=localhost/emailAddress=canton@digitalasset.com" "DNS:localhost,IP:127.0.0.1"
sign_csr "domain" "root-ca"
print_certificate "domain"

# create participant certificate
create_key "participant"
create_csr "participant" "/O=TESTING/OU=PARTICIPANT/CN=localhost/emailAddress=canton@digitalasset.com" "DNS:localhost,IP:127.0.0.1"
sign_csr "participant" "root-ca"

# create participant client key and certificate
create_key "admin-client"
create_csr "admin-client" "/O=TESTING/OU=ADMIN CLIENT/CN=localhost/emailAddress=canton@digitalasset.com"
sign_csr "admin-client" "root-ca"
print_certificate "admin-client"

# create self-signed certificate (used to test that mutual client auth works by refusing to connect with not-authorized certificate)
create_key "some"
create_certificate "some" "/O=TESTING/OU=DISCONNECTED CERT/emailAddress=canton@digitalasset.com"

Keep Alive

In order to prevent load-balancers or firewalls to terminate long running RPC calls in the event of some silence on the connection, all GRPC connections enable keep-alive by default. An example configuration for an adjusted setting is given below:

      admin-api 	{
        address = "127.0.0.1"
        port = 5022
        keep-alive {
          time = 40s
          timeout = 20s
        }
      }

The effect of the time and timeout settings are described in the GRPC documentation. To turn off the keep-alive, unset the default settings using keep-alive = null.

Participant Configuration

Ledger Api

The configuration of the ledger API is similar to the admin API configuration, except that the group starts with ledger-api instead of admin-api.

JWT Authorization

The Ledger Api supports JWT based authorization checks. Please consult the DAML SDK manual to understand the various configuration options and their security aspects. Canton exposes precisely the same JWT authorization options as explained therein.

In order to enable JWT authorization checks, your safe configuration options are

canton {
  participants {
    participant1 {
      ledger-api {
        auth-service {
          // type can be
          //   jwt-rs-256-crt
          //   jwt-es-256-crt
          //   jwt-es-512-crt
          type = jwt-rs-256-crt
          certificate = my-certificate.cert
        }
      }
    }
  }
}
canton {
  participants {
    participant1 {
      ledger-api {
        auth-service {
          type = jwt-rs-256-jwks
          url = "https://path.to/jwks.key"
        }
      }
    }
  }
}

while there is also unsafe HMAC256 based support, which can be enabled using

canton {
  participants {
    participant1 {
      ledger-api {
        auth-service {
          type = unsafe-jwt-hmac-256
          secret = "not-safe-for-production"
        }
      }
    }
  }
}

Domain Configurations

Public Api

The domain configuration requires the same configuration of the admin-api as the participant. Next to the admin-api, we need to configure the public-api, which is the api where all participants will connect to. There is a built in authentication of the restricted services on the public api, leveraging the participant signing keys. You don’t need to do anything in order to set this up. It is enforced automatically and can’t be turned off.

As with the admin-api, network traffic can (and should be) encrypted using TLS.

An example configuration section which enables TLS encryption and server-side TLS authentication is given by

  public-api {
    port = 5028
    address = localhost // defaults to 127.0.0.1
    tls {
      cert-chain-file = "./tls/domain.crt"
      private-key-file = "./tls/domain.pem"
      // protocols = TLSv1.3, optional argument
      // ciphers = null // use null to default to JVM ciphers
    }
  }

If TLS is used on the server side with a self-signed certificate, we need to pass the certificate chain during the connect call of the participant. Otherwise, the default root certificates of the Java runtime will be used. An example would be:

    participant3.domains.connect(
      domainAlias = "acme",
      connection = s"https://$hostname:$port",
      certificatesPath = certs // path to certificate chain file (.pem) of server
    )

Domain Rules

Every domain has its own rules in terms of what parameters are used by the participants while running the protocol. The participants obtain these parameters before connecting to the domain. They can be configured using the specific parameter section. An example would be:

domain-parameters {
  # Left empty to use default values from class DomainParameters.
}

The full set of available parameters can be found in the scala reference documentation.

Cryptography

All crypto-graphic routines used in Canton are represented through an abstract API for asymmetric and symmetric cryptographic operations. Currently, there are two implementations available, a convenient one for development and testing and one for serious and secure use.

Tink

The real cryptographic module is based on Tink and can be activated using

canton.domains.<mydomain>.crypto.type = tink
canton.domains.<myparticipant>.crypto.type = tink

Symbolic

The symbolic cryptography module will not encrypt anything but just wrap the content in a clear-text container together with the information of what was encrypted by whom.

canton.domains.<mydomain>.crypto.type = symbolic

Reference

Canton configuration file for static properties is based on Pureconfig. Pureconfig maps Scala case classes into appropriate configuration options. Therefore, the ultimate source of truth for all available configuration options is given by the appropriate scaladocs of the CantonConfig classes.

In order to map the Scala names into the HOCON format, we need to map the names from CamelCase to lowercase-with-dashes, i.e. domainParameters becomes domain-parameters (dash, not underscore).