Admin Login
HomeGuidesAPI ReferenceChangelogBlockdaemon Main Docs
Log In
Guides

Encryptor Master Password Key Ceremony

Wrap each Policy Node Encryptor Master Password under split custody.

Each Policy Node recovers its Encryptor Master Password only inside that node. Three custodians each own one node. No person or automation identity uses more than one custodian's wrap key or ciphertext.

Objectives

  • One custodian owns one node: that node's wrap key and ciphertext.
  • The only durable copy of an Encryptor Master Password is ciphertext. Plaintext exists only while it is generated and wrapped, and later inside that Policy Node.
  • Identities that deploy the workload can store and fetch ciphertext. Unwrap runs only inside that Policy Node.

Ceremony record

We recommend that each custodian keep a written ceremony record for their node, stored where every custodian and the security function can read it, and retained for the life of the wallet. The record lets a later reviewer confirm what was done without relying on memory. Include:

  • The ceremony type (new or rotation) and date, the custodian, the node index, and the node's AWS account.
  • The key store and the key that encrypted the password: the account, region, CMK alias, and CMK key ARN. Record the ARN, not only the alias. An alias is a pointer and can name a different key later.
  • The secret name, the secret version written, and the ciphertext digest. The digest is the SHA-256 of the stored ciphertext, so anyone can later confirm the stored value has not changed.
  • Hashes of the CMK key policy before and after the change. Together they show that only that node's Nitro role can decrypt, and that the policy changed only as approved.
  • Every aborted run and how it was resolved, for example a denied encrypt or a key ARN that did not match the approved ARN.
  • The name, role, and time of each person who signed the record.

Example: AWS Nitro

Run this once per node, from that node's custodian, after the secret shell exists. The command generates the password, encrypts it under the node CMK, and writes the ciphertext into that shell. It prints neither the password nor the ciphertext.

The default infrastructure setup uses these names:

  • Secret: bd-wallet.{namespace}.{env}.policy-node{N}.encryptor-master-password
  • CMK alias: alias/{env}-{namespace}-node{N}-nitro
  • Secret account and region: the caller's account and --region

The caller needs kms:Encrypt and kms:DescribeKey on that CMK. DescribeKey resolves the key ARN printed as kmsKeyArn. On the secret, the caller needs secretsmanager:DescribeSecret, secretsmanager:GetSecretValue, and secretsmanager:UpdateSecret. UpdateSecret keeps the shell's existing KMS key, so the caller also needs kms:Decrypt and kms:GenerateDataKey on that key through Secrets Manager. The shell's KMS key must not be the node CMK. Decrypt of the wrapped password stays on that node's Nitro role. Leave kms:Decrypt off the ceremony caller for the node CMK.

An empty shell is filled. A value that is already present is left in place. Pass --rotate only when replacing that value is an approved ceremony step.

Before the run, the security function gives the custodian the approved node CMK ARN from the infrastructure output. The command prints the resolved ARN as kmsKeyArn. If it does not match the approved ARN, stop and record the mismatch.

emp-key-ceremony init aws-nitro \
  --namespace acme \
  --env prod \
  --node-index 2 \
  --region us-east-1 \
  --json
emp-key-ceremony init aws-nitro node=2 ns=acme env=prod
{
  "status": "ok",
  "provider": "aws-nitro",
  "expandTemplate": "{{ enclaveSecret `bd-wallet.acme.prod.policy-node2.encryptor-master-password` | tomlEscape }}",
  "nodeIndex": 2,
  "namespace": "acme",
  "env": "prod",
  "region": "us-east-1",
  "policyNodeAccountId": "123456789012",
  "secretManagerAccountId": "123456789012",
  "secretManagerRegion": "us-east-1",
  "secretName": "bd-wallet.acme.prod.policy-node2.encryptor-master-password",
  "secretArn": "arn:aws:secretsmanager:us-east-1:123456789012:secret:bd-wallet.acme.prod.policy-node2.encryptor-master-password",
  "kmsKeyAlias": "alias/prod-acme-node2-nitro",
  "kmsKeyArn": "arn:aws:kms:us-east-1:123456789012:key/11111111-2222-3333-4444-555555555555",
  "secretWritten": true,
  "alreadyExists": false,
  "ciphertextVersion": "8af99b61-9a57-4e81-86e0-544bfe1b8138",
  "ciphertextDigest": "529566bfd6f262308854b8dc63c578e47702aa8e571e570b25c32d272c9a7eca",
  "callerArn": "arn:aws:sts::123456789012:assumed-role/policy-node-2-custodian/operator",
  "callerRole": "policy-node-2-custodian"
}

ciphertextVersion is the Secrets Manager version id. ciphertextDigest is the hex SHA-256 of the stored ciphertext string. Copy both into the ceremony record. Confirm that policyNodeAccountId is this node's account and that callerRole is this node's custodian role.

Repeat the command for node indexes 0 and 1 under the other two custodians.

For each node, set EncryptorMasterPassword in that node's config file to the expandTemplate value from that node's output. For node 2:

[Secrets]
EncryptorMasterPassword = "{{ enclaveSecret `bd-wallet.acme.prod.policy-node2.encryptor-master-password` | tomlEscape }}"

The Policy Node replaces this placeholder at startup with the password it unwraps inside the enclave. The config file never contains the password.


Did this page help you?