Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

doc: improve KMS doco #2

Merged
merged 1 commit into from
Jun 12, 2024
Merged

doc: improve KMS doco #2

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 30 additions & 12 deletions docs/kms.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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
Expand Down