Daml

Configure session keys

Canton uses session keys to reduce expensive cryptographic operations during protocol execution, improving performance. There are two types: session encryption keys, which reduce the number of asymmetric encryptions, and session signing keys, which help avoid frequent calls to external signers such as a KMS.

You can read more about the rationale and security considerations in Session Keys.

Currently, session encryption keys are enabled by default, whereas session signing keys, being directly tied to a KMS, are disabled by default. However, the latter can be enabled when using an external KMS to store private keys via a configuration parameter.

Important

Extending the lifetime of session keys minimizes the need for repeated key negotiation or remote signing/encryption, but it also increases the window during which keys are stored in memory, raising the risk of compromise.

Increase session encryption keys lifetime

You can control how long a session encryption key remains active by adjusting the expire-after-timeout values in your configuration. To globally increase the lifetime of session encryption keys, increase the expire-after-timeout for both the sender-cache and receiver-cache.

canton.participants.participant1 {
    caching {
        session-encryption-key-cache {
            # these are the default values
            enabled = true
            sender-cache {
                maximum-size = 10000
                expire-after-timeout = 10s
            }
            receiver-cache {
                maximum-size = 10000
                expire-after-timeout = 10s
            }
        }
    }
}

Enable session signing keys

Much like session encryption keys, enabling session signing keys introduces a trade-off: short-lived keys are kept in memory and therefore outside of direct protection by the KMS. Therefore, operators should evaluate this performance and cost benefit against their security requirements and threat model before enabling this feature.

When using external KMS (Key Management Service) provider you can enable session signing keys by setting:

canton.participants.participant1.crypto.kms.session-signing-keys.enabled = true

Increase session signing keys lifetime

Increasing the lifetime of session signing keys is also a trade-off: longer lifetimes improves performance and reduce KMS load, but extends the time window during which key material remains in memory. Security best practice guidance (e.g. OWASP) recommends using short-lived sensitive key material, typically on the order of around 5 minutes: OWASP (Token Lifetime / Access Tokens) This is also the current default value.

You can increase the lifetime of session signing keys via the key-validity-duration config parameter:

canton.participants.participant1.crypto.kms {
  # default values
  session-signing-keys {
    key-validity-duration = 5m
    tolerance-shift-duration = 2m
    cut-off-duration = 1m,
    key-eviction-period = 10m,
    signing-algorithm-spec = ed-25519,
    signing-key-spec = ec-curve-25519,
  }
}

The key-validity-duration must always be shorter than the key-eviction-period. The key-validity-duration should also be at least as long as the defaultMaxSequencingTimeOffset, as well as the sum of confirmation_response_timeout and mediator_reaction_timeout, as configured in the dynamic Synchronizer parameters.

If you want to know more about each configurable parameter and the factors to consider when modifying them, you can refer to the session signing keys’ Configurable Parameters section.

← Back to Documentation