From 02fb73f79927ee7dfe13a50d4b94a9997cfbc765 Mon Sep 17 00:00:00 2001 From: James Telfer <792299+jamestelfer@users.noreply.github.com> Date: Wed, 12 Jun 2024 19:41:59 +1000 Subject: [PATCH] doc: improve KMS doco somewhat --- docs/kms.md | 42 ++++++++++++++++++++++++++++++------------ 1 file changed, 30 insertions(+), 12 deletions(-) diff --git a/docs/kms.md b/docs/kms.md index b3cea4f..2ee6342 100644 --- a/docs/kms.md +++ b/docs/kms.md @@ -24,10 +24,10 @@ It is more secure (though more complicated) to provide Chinmina with an AWS KMS 4. Create an alias for the KMS key to allow for easy [manual key rotation][aws-manual-key-rotation]. - > [!IMPORTANT] - > A key alias is essential to allow for key rotation. Unless you're stopped - > by environmental policy, use the alias. The key will be able to be rotated - > without any service downtime. +> [!IMPORTANT] +> A key alias is essential to allow for key rotation. Unless you're stopped +> by environmental policy, use the alias. The key will be able to be rotated +> without any service downtime. 5. Ensure that the key policy has a statement allowing Chinmina to access the key. The specified role should be the role that the Chinmina process has access to at runtime. @@ -47,19 +47,37 @@ It is more secure (though more complicated) to provide Chinmina with an AWS KMS } ``` - > [!IMPORTANT] - > Chinmina does not assume a role to access the key. It assumes valid - > credentials are present for the AWS SDK to use. +> [!INFO] +> Chinmina does not assume a role to access the key. It assumes valid +> credentials are present for the AWS SDK to use. ## Configuring the Chinmina service 1. Set the environment variable `GITHUB_APP_PRIVATE_KEY_ARN` to the ARN of the **alias** that has just been created. -2. Update IAM for your key. - 1. Key resource policy - 2. Alias policy? - 3. IAM policy for Chinmina process (i.e. the AWS role available to Chinmina - when it runs) +2. Update IAM for your key + 1. The KMS key resource policy needs to allow the service to use the key + _for signing only_. + 2. The IAM policy for the Chinmina process (i.e. the AWS role available to + Chinmina when it runs) needs to be able to use the _alias_ created for + the private key. This is done with a condition in the policy element: + + ```json + { + "Action": "kms:Sign", + "Effect": "Allow", + "Resource": "*", + "Condition": { + "StringEquals": { + "kms:RequestAlias": "alias/chinmina-signing", + }, + }, + } + ``` + + Using the `kms:RequestAlias` condition instead of the fully qualified + key ARN in the `resource` attribute allows for transparent key rotation + without service interruption. [github-key-generate]: https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/managing-private-keys-for-github-apps#generating-private-keys [aws-import-key-material]: https://docs.aws.amazon.com/kms/latest/developerguide/importing-keys.html