Sign with AWS KMS

Security architecture · Package and contract operations

When this applies

Use this page when your Canton participant uses AWS KMS as its crypto provider. The participant setting is canton.participants.<participant>.crypto.provider = kms. On such a participant, Canton creates the party keys inside AWS KMS. The private keys cannot leave AWS KMS.

Each member of a Decentralized Party holds two keys:

Key	Signs	How it signs on a KMS-backed participant
Namespace key	Topology transactions	The participant signs through its own KMS access. No setup is necessary.
Daml key	Ledger transactions, for example the governance contract deployment	Decentralization Manager calls the AWS KMS `Sign` API. This needs IAM setup.

Canton has no API that signs a ledger transaction with a vault key. Decentralization Manager therefore calls AWS KMS itself. It signs during the contracts workflow, after it checks each prepared transaction.

You do not select the signing path. Decentralization Manager reads the key metadata from the participant with VaultService.ListMyKeys. A key with a KMS key ID uses AWS KMS. A key without one uses the export path in JCE alternative.

Key spec

Decentralization Manager creates each party key with an unspecified key spec. The participant then applies its own default: EC-P256 on a KMS-backed participant, Ed25519 on a JCE participant.

The AWS KMS signer supports EC-P256 keys only. AWS KMS calls this key spec ECC_NIST_P256. For each prepared transaction hash, Decentralization Manager does these steps:

It calls Sign with the signing algorithm ECDSA_SHA_256 and the message type RAW.
It receives a DER-encoded signature. Canton accepts this format without conversion.
It verifies the signature against the public key that the participant registered. The coordinator then submits the transaction.

IAM permissions

Decentralization Manager calls one AWS KMS API: kms:Sign. It reads the key ID and the public key from the participant, not from AWS KMS.

The participant creates the keys under its own KMS role. The IAM role of Decentralization Manager therefore has no access by default. Grant kms:Sign on the Daml key of each party.

Key policy (recommended)

Add this statement to the key policy of each party Daml key. A key policy statement works whether or not the key policy delegates access to IAM.

{
  "Sid": "AllowPartyDamlKeySigning",
  "Effect": "Allow",
  "Principal": { "AWS": "arn:aws:iam::<account>:role/<decentralization-manager-role>" },
  "Action": "kms:Sign",
  "Resource": "*"
}

In a key policy, "Resource": "*" means the key that the policy belongs to.

IAM policy

An IAM policy on the Decentralization Manager role works only when the key policy delegates access to IAM. The statement has no Principal. Its Resource must name the ARN of each party Daml key.

{
  "Sid": "AllowPartyDamlKeySigning",
  "Effect": "Allow",
  "Action": "kms:Sign",
  "Resource": "arn:aws:kms:<region>:<account>:key/<party-daml-key-id>"
}

Find the key ID

The party Daml key has the name <party-prefix>-daml-transactions. List the key over the participant Admin API. Its metadata holds the kmsKeyId field.

grpcurl -plaintext -d '{"filters":{"name":"<party-prefix>-daml-transactions"}}' \
  <admin-host>:<admin-port> \
  com.digitalasset.canton.crypto.admin.v30.VaultService/ListMyKeys

The example uses -plaintext. Replace it with your TLS options if the Admin API uses TLS.

As an alternative, run the contracts workflow once. The AccessDeniedException error names the key ARN.

Configure AWS credentials

Decentralization Manager has no DECPM_* variable for AWS KMS. It discovers the key ID from the participant. It loads the AWS credentials and the region from the default AWS credential chain:

Source	Settings
Environment variables	`AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`, plus `AWS_SESSION_TOKEN` for temporary credentials
Shared configuration	`AWS_PROFILE` with the AWS configuration and credentials files
Web identity role	On Amazon EKS, an IAM role for the Decentralization Manager service account (IRSA)
Region	`AWS_REGION`. Set it to the region of the KMS keys if the chain does not resolve it.

AWS resolves a bare key ID in the account and region of the credentials. If the participant keys are in another AWS account, give Decentralization Manager credentials for that account.

Key ID validation

The participant metadata must hold a bare key ID. A bare key ID is a UUID, or mrk- followed by 32 hexadecimal digits. Decentralization Manager rejects an ARN, an alias or a malformed ID before it calls Sign. Metadata therefore cannot redirect signing to a key in another account.

Verify the setup

Run the ListMyKeys command from Find the key ID. The result must show kmsKeyId with a bare key ID.
Optional: check the key spec in AWS. Use an AWS identity that can read the key.
Terminal window
```
aws kms describe-key --key-id <kms-key-id> --region <region> \
  --query 'KeyMetadata.[KeySpec,KeyUsage]'
```
The expected values are ECC_NIST_P256 and SIGN_VERIFY.
Run the contracts workflow for the Decentralized Party. Package and contract operations describes the workflow.
Read the Decentralization Manager log on each KMS-backed member. A successful workflow run logs Signing <n> transaction hashes via AWS KMS key <kms-key-id>.... It then logs Signature <n> verified locally for each hash.

A member on a JCE participant logs Exporting private key from Canton... instead.

Failure modes

Log message	Cause and action
`KMS signing failed: ... AccessDeniedException`	The Decentralization Manager role has no `kms:Sign` on the key. Add the key policy statement.
`KMS signing failed: ... dispatch failure`	Decentralization Manager found no AWS credentials, or it uses the wrong region. Check the credential chain and `AWS_REGION`.
`Invalid kms_key_id`	The vault metadata holds an ARN, an alias or a malformed ID. Use the bare ID of the participant key and credentials for its account.
`AwsKmsSigner does not support key spec`	The party Daml key is not EC-P256. The AWS KMS signer supports EC-P256 only.
`failed local verification against the registered public key`	The KMS key does not match the registered public key. Check that the `kmsKeyId` belongs to the Daml key of this party.
The workflow fails at export with `ExportKeyPair`	The key has no KMS key ID, so Decentralization Manager used the export path. This is normal on a JCE participant. On a KMS-backed participant, the key metadata is inconsistent.

JCE alternative

A participant with the JCE crypto provider keeps exportable keys in its vault. Decentralization Manager needs no AWS setup for such a participant. It does these steps each time it signs:

It exports the party Daml key over the Admin API with VaultService.ExportKeyPair.
It finds the Ed25519 private key in the export and checks it against the registered public key.
It signs each transaction hash in memory and verifies each signature locally.
It wipes the private key bytes from memory. It never stores the private key in its database or on disk.

Parties that JCE participants created before AWS KMS support hold Ed25519 keys. These parties continue to use the export path.

Property	JCE participant	KMS-backed participant
Daml key spec	Ed25519	EC-P256
Private key leaves the key store	Yes, into Decentralization Manager memory during signing	No
Who can sign with the key	Any caller with Admin API access to the participant	IAM principals with `kms:Sign` on the key
Setup in Decentralization Manager	None	AWS credentials and `kms:Sign`

Limits

Decentralization Manager supports AWS KMS only. A participant with another KMS driver also reports a KMS key ID. Signing then fails with a KMS error.
The AWS KMS signer supports EC-P256 keys only.

Technical sources

Next step

Deploy contracts with the new setup: Package and contract operations.