Skip to content

Document KMS key policy requirements for SOPS decryption #127

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

Draft
Copilot wants to merge 4 commits into
base: main
Choose a base branch
from
Draft

Document KMS key policy requirements for SOPS decryption #127

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
0b0bc96
Initial plan
Copilot Jun 25, 2025
aa091c9
Add comprehensive KMS key policy documentation
Copilot Jun 25, 2025
d9054b9
Clarify minimum KMS permissions requirement
Copilot Jun 25, 2025
8da4c3b
Restructure KMS key policy documentation from simplest to most secure…
Copilot Jun 25, 2025
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
79 changes: 79 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -84,6 +84,85 @@ is uploaded to S3 as an asset _as is_, still encoded. The custom
resource Lambda then decodes the secrets (in memory, never on disk)
and puts them into the SecretsManager secret.

## KMS Key Policy Requirements

For the Lambda function to successfully decrypt SOPS files, the KMS key used for encryption must have a key policy that allows the Lambda execution role to perform decryption operations. While this CDK construct grants the Lambda broad KMS permissions via IAM policies (`kms:*`), KMS key policies are resource-based policies that can override IAM permissions.

Both the IAM policy (granted by this construct) AND the KMS key policy must allow the Lambda execution role to use the key.

@plumdog plumdog Jun 25, 2025

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Add here the simplest approach, which is to just delegate all permissions for the KMS key over to IAM, then suggest the others as more refined alternatives. So work from simplest (and least secure) to more complex (but more secure).

Copilot AI Jun 25, 2025

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Restructured the KMS key policy documentation to start with the simplest approach (delegating all permissions to IAM) and progress to more secure alternatives. The three approaches are now ordered from least to most secure with clear security considerations for each. (commit: c5d45f2)

### Approach 1: Delegate All Permissions to IAM (Simplest)

The simplest approach is to configure your KMS key policy to delegate all access control decisions to IAM policies. This allows the IAM permissions granted by this CDK construct to take full effect:

```json
{
"Sid": "DelegateToIAM",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::ACCOUNT-ID:root"
},
"Action": "kms:*",
"Resource": "*"
}
```

Replace `ACCOUNT-ID` with your AWS account ID. This approach is the least secure as it grants broad KMS permissions to all principals in your account, relying entirely on IAM policies for access control.

### Approach 2: Grant Specific Role Access (More Secure)

A more secure approach is to explicitly grant only the necessary permissions to the specific Lambda execution role:

```json
{
"Sid": "AllowSopsSecretsManagerLambda",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::ACCOUNT-ID:role/LAMBDA-EXECUTION-ROLE-NAME"
},
"Action": [
"kms:Decrypt",
"kms:DescribeKey"
],
"Resource": "*"
}
```

Replace `ACCOUNT-ID` with your AWS account ID and `LAMBDA-EXECUTION-ROLE-NAME` with the actual name of the Lambda execution role created by this CDK construct.

#### Finding the Lambda Execution Role ARN

The Lambda execution role is created automatically by this CDK construct. You can find its ARN by:

1. Looking in the AWS IAM console for roles with names containing your stack name and "sops-secrets-manager"
2. Checking the CloudFormation stack outputs or resources
3. Using the AWS CLI: `aws iam list-roles --path-prefix /` and filtering for the relevant role

### Approach 3: Use Conditions for Flexible Access (Most Secure)

The most refined approach uses conditions to allow access while maintaining security constraints:

```json
{
"Sid": "AllowSopsSecretsManagerLambda",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::ACCOUNT-ID:root"
},
"Action": [
"kms:Decrypt",
"kms:DescribeKey"
],
"Resource": "*",
"Condition": {
"StringEquals": {
"kms:ViaService": "lambda.REGION.amazonaws.com"
}
}
}
```

Replace `ACCOUNT-ID` with your AWS account ID and `REGION` with your AWS region. This approach ensures that the key can only be used by Lambda functions in your account and region, providing a good balance between security and flexibility.

## Integration testing

Run the following to deploy a test stack named
Expand Down