Cryptographic keys in Canton¶
This section is about cryptographic keys in Canton. As a preliminary, it outlines general options for storing secrets in Canton. Then, it gives an overview of the various kinds of cryptographic keys and how Canton uses and stores them.
Storage of secrets¶
This section outlines the general options for storing secrets in Canton.
Plaintext storage options¶
For convenience, Canton offers the following options without encryption:
Database: A Canton node stores a secret in its database in plaintext.
File: A Canton node stores a secret in a file in plaintext.
Options without persistence¶
For better protection of secrets, Canton also offers options without persistence:
Offline: For some secrets, Canton allows for not storing them at all. Hence, usages of the secrets (such as signing and decryption operations) need to happen outside of Canton.
In memory: Canton stores a secret in memory in plaintext. It does not store the secret in a file nor in the database.
Options with a key management service¶
For better protection of secrets that Canton needs to persist, Canton allows for using a key management service (KMS):
KMS envelope encryption: Canton stores a secret in an encrypted manner in the database. Canton keeps the plaintext of the key in memory. When Canton needs to decrypt the secret, it sends its ciphertext to a KMS, the KMS decrypts the secret and sends the plaintext of the secret back to Canton.
Full KMS: A KMS generates and stores a secret, typically a private signing or encryption key. The KMS does not expose the secret to anybody. When Canton needs to sign some data, it sends the data to the KMS, the KMS produces the digital signature, and sends the signature back to Canton. Similarly, when Canton needs to decrypt some data, it sends the ciphertext to the KMS, the KMS decrypts the ciphertext, and sends the plaintext back to Canton.
KMS with session signing keys¶
As the option “full KMS” comes with substantial latency, Canton offers an option with lower signing latency at the cost of slightly weaker protection of secret keys. A node stores its long-term signing secret key in a KMS. For signing, it uses a private ephemeral signing key instead of the long-term signing key in the KMS. Alongside with the signature, it also ships (1) the public key corresponding to the private ephemeral signing key and (2) a certificate demonstrating that the ephemeral key is a legitimate replacement of the long-term key until a defined point in time. The long-term key needs to sign this certificate.
This approach limits the overhead of KMS operations, as the node accesses the KMS only when rolling the ephemeral key (as opposed to on every signing operation).
The node keeps the ephemeral signing key in memory in plaintext. The node does not store ephemeral signing keys on disk nor in the database. To limit the impact of a potential key compromise, a node does not accept signatures from an ephemeral signing key if its configurable lifetime has elapsed.
Session encryption keys¶
To reduce the load caused by asymmetric encryption and decryption operations, Canton uses symmetric encryption instead. Thereby, Canton greatly reduces its use of asymmetric encryption.
Every node has a long-term asymmetric encryption key, which it stores in its database or in a KMS. Additionally, every node produces ephemeral symmetric encryption keys and uses them to encrypt data it needs to protect. Alongside with a ciphertext, a node also ships the corresponding ephemeral encryption key asymmetrically encrypted with the long-term encryption key of the recipient.
In general, the data has a much bigger size than an ephemeral key. Moreover, a node usually needs to send the data to various recipients. Under these assumptions, the use of a session encryption key reduces the load of encryption and decryption operations for various reasons:
Canton needs to encrypt the data only once (as opposed to once per recipient) and it needs to send only one ciphertext of the data.
Canton uses the cheaper symmetric encryption for the bigger data and the more expensive asymmetric encryption for the smaller ephemeral key.
If a node uses an ephemeral key several times, the recipient needs to decrypt it only when it receives it for the first time.
Canton nodes keep ephemeral encryption keys in memory in plaintext. They do not store the plaintexts of ephemeral encryption keys on disk nor in the database. They may store ephemeral keys in an encrypted fashion in their databases. To limit the impact of a potential key compromise, a node does not use an ephemeral encryption key after its configurable lifetime has elapsed. A node reuses the same ephemeral encryption key for encrypting data d1 and data d2 only if the intended recipients of d1 coincide with the intended recipients of d2.
Overview of cryptographic keys in Canton¶
This section provides an overview of how Canton makes use of cryptographic keys.
TLS keys¶
Canton nodes provide various GRPC and HTTP apis that allow clients to interact with the node. Examples include:
ledger apis of Participant Nodes for submitting ledger commands and receiving ledger updates,
admin apis of all kinds of nodes for administrative purposes,
public apis of Sequencers for multicasting messages,
ordering apis for internal communication between Sequencers,
health apis.
Users can configure the apis of a node to use server side TLS and, in some cases, also to use mutual TLS. Canton reads the keys that TLS uses from one or several files at startup. These files contain the TLS keys in plaintext.
Namespace signing keys¶
Every topology namespace has a public signing key, called the namespace root key. The namespace is the hash of its root key. Operators use the private key corresponding to the root key to sign and thereby authorize topology transactions for the namespace. A namespace can have further signing keys and operators can use them as well to authorize topology transactions for the namespace.
Examples of topology transactions that a namespace key (root or not) can authorize include:
NamespaceDelegation: authorize further keys to authorize topology transactions related to the namespace,OwnerToKeyMapping: associate a key with a Canton node,PartyToParticipant: associate a party with a participant,SynchronizerParametersState: define parameters for a synchronizer.
Canton supports the following options for storing secret namespace keys:
database (the default),
all options storing the keys in a KMS.
Node signing keys¶
A node has one or several signing keys that serve the following purposes:
Sequencer client authentication: When interacting with the public api of a Sequencer, clients need to provide a valid authentication token. A client obtains its authentication token in a challenge-response protocol. During the protocol, the client signs a nonce generated by the Sequencer.
Additionally, a request to the Sequencer needs to include a signature from its sender if the request may change the Sequencer’s state.
Sequencer server authentication: The Sequencer signs every event that it emits to a client.
When processing Ledger API commands, Participant Nodes use their signing keys to sign and therefore authenticate messages sent as part of the transaction and reassignment protocols. This includes both processing of Daml transactions and reassignments.or
Sequencers exchange messages as part of their ordering protocol. They use their signing keys for authenticating the senders of such messages.
Participant Nodes use their signing keys to sign ACS commitments.
Canton supports the following options for storing node signing keys:
database (the default),
all options storing the keys in a KMS.
External party signing keys¶
By default, Participant Nodes sign and thereby authorize the execution of Daml transactions. Alternatively, the submitting party (referenced as external party) may directly sign and authorize the Daml Transaction that it intends to add to the ledger. That is, the submitting party signs instead of the submitting Participant Node. For this purpose, external parties have their own signing keys.
The recommended option for storing signing keys of external parties is “offline”. Other options (for example database) may be technically possible, but they are not recommended.
Encryption keys¶
When a Participant Node proposes a transaction, it decomposes the transaction into so called transaction views. It sends every transaction view to exactly those Participant Nodes that may see its contents. The decomposition of a transaction into views is crucial to achieve sub-transaction privacy.
Participant Nodes have one or several asymmetric encryption keys. When a Participant Node sends a transaction view to other Participant Nodes, it does so in an encrypted fashion. This is important so that Sequencer Nodes do not see the contents of transaction views. Participant Nodes do not directly encrypt transaction views using their asymmetric encryption keys, but instead they apply encryption session keys for better performance.
Nodes other than Participant Nodes (for example, Sequencer Nodes) can also have encryption keys. However, Canton does currently not use encryption keys of such nodes.