Feature Request: Generate Policy to Decrypt Environment Variables

[chrisoverzero]

Describe your idea/feature/enhancement

In much of SAM, opting into an ability automatically confers the permissions required in IAM to perform that ability. This is not the case for the property KmsKeyArn, which encrypts a Function's environment variables and requires particular permissions (kms:Decrypt) to use. The SAM Managed Policy KMSDecryptPolicy exists, but is a very blunt instrument – it confers the ability to decrypt anything in all contexts using that key. Setting up the AWS::IAM::Policy is verbose (especially for templates with more than a handful of Functions) and requires use of a generated logical ID to avoid circular references – which is fine, but could be better.

Proposal

When a Function specifies that its environment variables be encrypted via KmsKeyArn, whether it's directly on the Function or in the Globals section, a corresponding policy should be created allowing that Function to decrypt its environment variables. This policy should be as restrictive as it is possible to make it by adding the following Conditions:

• StringEquals
  • kms:ViaService: lambda.amazonaws.com
• ForAnyValue:ArnEquals
  • kms:EncryptionContext:aws:lambda:FunctionArn
    • [the ARN of the Function]

Things to consider: [x] The SAM documentation will need to be updated (for the new generated CloudFormation resource)

Additional Details

I've been running Functions with this policy in place (per Function) for months, so it is known to be correct. This would only add the SAM generation, in keeping with other places where permissions are conferred. This fulfills one part of #1959 (which I have removed from that request).

I have the code changes for this ready to go and passing tests, and will create an MR soon after this is posted.