Options for encryption at rest Encrypting data at rest using a customer managed key Monitoring Web Functions interaction with AWS KMS

Encryption at rest for Web Functions

AWS Lambda encrypts the data for your Lambda Web Functions at rest on the server side. This page explains the encryption options available to you and how to configure a customer managed key.

Options for encryption at rest

Encryption at rest is always on. Lambda encrypts your Web Function code artifact and environment variables on the server side, and you cannot turn this encryption off. By default, Lambda uses an AWS owned key. You can configure a customer managed key instead.

You have two options for the AWS KMS key that protects your data:

AWS owned key (default): By default, Lambda encrypts your data with an AWS owned key. AWS owns and manages this key. You cannot view, manage, or audit its use. If this default behavior suits your needs, no additional setup is required.
Customer managed key: You can optionally configure your own AWS KMS customer managed key. Use a customer managed key when you need to control key rotation, audit key use through CloudTrail, manage key access through a key policy, or meet organizational compliance requirements. With a customer managed key, only principals you authorize can access the encrypted code and environment variables. Customer managed keys incur AWS KMS charges. For more information, see AWS Key Management Service pricing.

Encrypting data at rest using a customer managed key

The following sections explain how Web Functions use a customer managed key, how to configure the key and its permissions, and how to scope down access to it.

How Web Functions use a customer managed key

When you specify a customer managed key, Lambda uses envelope encryption. This means that Lambda encrypts the revision's data with a data key, and your KMS key encrypts that data key. Lambda gets the data key from AWS KMS and decrypts it with your KMS key when it needs to read the data. Only principals with access to the KMS key can access the revision's code and environment variables.

Lambda encrypts the following Web Function resources with your customer managed key:

Resource	What is encrypted
Revision	The code artifact built from your Amazon S3 deployment package, and the revision's environment variables.

Lambda doesn't use AWS KMS grants for Web Functions. Access is authorized through the key policy and the calling principal's IAM permissions.

Lambda calls AWS KMS while creating and launching revision resources and can cache decrypted material in active execution environments. Revoking key access is not an immediate traffic-containment mechanism because existing environments can continue using cached material for an unspecified period.

After a key-policy change, test the expected behavior and monitor revision and endpoint health. For emergency containment, stop routing traffic to affected revisions or disable the endpoint rather than relying only on key revocation.

Lambda sets the following encryption context on all AWS KMS operations for Web Functions:

aws:lambda:WebFunctionRevisionArn – The Amazon Resource Name (ARN) of the Web Function revision.

You can use this encryption context in key policies to scope access to specific Web Functions or revisions. For more information, see Scoping down access to your KMS key.

Configuring a customer managed key

The AWS KMS key must be a symmetric encryption key (key spec SYMMETRIC_DEFAULT, key usage ENCRYPT_DECRYPT). You can't use asymmetric keys.

Web Functions support multi-Region keys. The type of key you need depends on your endpoint configuration:

HomeRegion endpoint – You can use a single-Region key or a multi-Region key.
MultiRegion or PerRegion endpoint – You must use a multi-Region key with replicas in every AWS Region that the endpoint serves. If a Region lacks a replica of the key, replication to that Region fails.

For information about creating multi-Region keys, see Create multi-Region primary keys in the AWS Key Management Service Developer Guide.

Because AWS KMS does not copy or synchronize key policies between related multi-Region keys, you must configure each key policy separately. Configure the key policy on the primary key and on every replica key. At minimum, every replica key's policy must allow the Lambda service principal to call kms:Decrypt. This permission allows Lambda to decrypt the data key in that Region. For more information, see Authorizing use of multi-Region keys in the AWS Key Management Service Developer Guide.

Note

When you create multi-Region replica keys, they can take from a few seconds to a few minutes to become available in all Regions. Confirm that the replica key is available in every target Region before you create the revision or endpoint.

Configuring permissions to use a customer managed key

To create a revision with a customer managed key, you need the following permissions on the AWS KMS key:

kms:DescribeKey – Required when you create a Web Function or revision with the key.
kms:GenerateDataKey – Lambda calls this operation to generate the data key that encrypts the revision's code artifact and environment variables.
kms:Decrypt – Lambda calls this operation to validate that the key is usable when you create the revision. Principals that read a revision with GetWebFunctionRevision also need kms:Decrypt on the key to see its environment variables.

The creation request fails if the key is missing, disabled, not a symmetric encryption key, or inaccessible with the required permissions.

Note

You do not need kms:Encrypt permission. Lambda uses envelope encryption with GenerateDataKey, which returns both a plaintext and encrypted copy of the data key without requiring a separate encrypt call.

The AWS KMS key policy must also allow the Lambda service principal (lambda.amazonaws.com) to call kms:Decrypt. Lambda uses this permission to decrypt the data key when it launches execution environments for the revision. The service principal does not need kms:DescribeKey. The principal that creates the Web Function or revision needs that permission.

Example key policy

The following key policy contains the three statements that Web Functions require, each scoped down with the conditions described in Scoping down access to your KMS key. The first statement grants the Lambda service principal the permissions it needs when it launches execution environments. The second and third grant the principal that creates revisions the permissions it needs at creation time.

kms:DescribeKey is in a separate statement because it is a metadata operation that carries no encryption context. An encryption context condition would never match a DescribeKey request, so that condition applies only to the statement that grants kms:GenerateDataKey and kms:Decrypt.

This example shows only the statements that Lambda requires for Web Functions. Add these statements to your existing key policy rather than replacing it, and keep the statements that grant your administrators access to manage the key.

Example Key policy for Web Function encryption


{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "Allow Lambda to decrypt the data key for Web Function revisions",
            "Effect": "Allow",
            "Principal": { "Service": "lambda.amazonaws.com" },
            "Action": "kms:Decrypt",
            "Resource": "*",
            "Condition": {
                "StringLike": {
                    "kms:EncryptionContext:aws:lambda:WebFunctionRevisionArn": "arn:aws:lambda:us-east-1:111122223333:web-function/my-function/revision/*",
                    "aws:SourceArn": "arn:aws:lambda:us-east-1:111122223333:web-function/my-function/revision/*"
                }
            }
        },
        {
            "Sid": "Allow the revision creator to generate and validate data keys",
            "Effect": "Allow",
            "Principal": { "AWS": "arn:aws:iam::111122223333:role/MyWebFunctionDeployRole" },
            "Action": [
                "kms:GenerateDataKey",
                "kms:Decrypt"
            ],
            "Resource": "*",
            "Condition": {
                "StringLike": {
                    "kms:EncryptionContext:aws:lambda:WebFunctionRevisionArn": "arn:aws:lambda:us-east-1:111122223333:web-function/my-function/revision/*"
                },
                "StringEquals": {
                    "kms:ViaService": "lambda.us-east-1.amazonaws.com"
                }
            }
        },
        {
            "Sid": "Allow the revision creator to describe the key",
            "Effect": "Allow",
            "Principal": { "AWS": "arn:aws:iam::111122223333:role/MyWebFunctionDeployRole" },
            "Action": "kms:DescribeKey",
            "Resource": "*",
            "Condition": {
                "StringEquals": {
                    "kms:ViaService": "lambda.us-east-1.amazonaws.com"
                }
            }
        }
    ]
}

For more information about AWS KMS key policies, see Key policies in AWS KMS in the AWS Key Management Service Developer Guide.

Creating a Web Function revision with a customer managed key

To encrypt a revision with a customer managed key, specify the key ARN in the kmsKeyArn parameter of the revision configuration. You can set this parameter when you call CreateWebFunction or CreateWebFunctionRevision. If you omit kmsKeyArn, Lambda encrypts the revision with the AWS owned key.

To create a Web Function with a customer managed key (AWS CLI)

Run the following command to create a Web Function with a customer managed key.


aws lambda-web create-web-function \
    --function-name my-web-app \
    --revision-config '{
      "kmsKeyArn": "arn:aws:kms:us-east-1:111122223333:key/key-id",
      "buildConfig": {
        "codeConfig": {
          "s3Object": { "bucket": "amzn-s3-demo-bucket", "key": "my-app.zip" }
        },
        "runtimeConfig": { "runtime": "nodejs24.x" }
      },
      "serviceConfig": {
        "executionRoleArn": "arn:aws:iam::111122223333:role/my-web-function-role"
      }
    }' \
    --endpoint-config '{
      "endpointName": "my-endpoint",
      "endpointType": "HomeRegion",
      "authType": "ApplicationManaged"
    }'

Changing the encryption configuration of an existing Web Function

The kmsKeyArn parameter is fixed for the life of a revision. Because revisions are immutable, you cannot change the key that protects an existing revision. To change the encryption configuration, create a new revision that specifies the new key, and then route traffic to that revision.

Web Functions support the following key transitions:

AWS owned key to customer managed key – Create a new revision that specifies kmsKeyArn.
One customer managed key to a different customer managed key – Create a new revision that specifies the new key ARN.
Customer managed key to AWS owned key – Create a new revision without kmsKeyArn. Lambda then protects that revision with the AWS owned key, which is the default.

Lambda does not re-encrypt existing revisions when you create a new revision with a different key. Each revision remains encrypted with the key that you specified when you created it. This means that as long as an earlier revision can still receive traffic, its original key must remain enabled and accessible to the Lambda service principal. Before you disable or delete a key, confirm that no revision encrypted with that key is still referenced by an endpoint's revision weights.

To create a new revision with a different customer managed key (AWS CLI)

Run the following command to create a revision that uses a different key.


aws lambda-web create-web-function-revision \
    --function-name my-web-app \
    --kms-key-arn arn:aws:kms:us-east-1:111122223333:key/new-key-id \
    --build-config '{
      "codeConfig": { "s3Object": { "bucket": "my-bucket", "key": "my-app-v2.zip" } },
      "runtimeConfig": { "runtime": "nodejs24.x" }
    }' \
    --service-config '{
      "executionRoleArn": "arn:aws:iam::111122223333:role/my-web-function-role"
    }'

Update the endpoint's revision weights to route traffic to the new revision. For more information, see Deployment patterns.

Scoping down access to your KMS key

The key policy in Example key policy restricts access with the following condition keys. Each one limits how the key can be used, so that access to the key is no broader than the Web Function needs.

Encryption context

Lambda sets the encryption context aws:lambda:WebFunctionRevisionArn on every AWS KMS request for a revision. Use a StringLike condition on kms:EncryptionContext:aws:lambda:WebFunctionRevisionArn to restrict the key to revisions of a specific Web Function. Apply this condition to both the creator statement and the Lambda service principal statement.

Do not apply this condition to a statement that grants kms:DescribeKey. That operation carries no encryption context, so the condition would deny it.

The following example shows the creator statement with the encryption context condition.


{
    "Sid": "Allow the revision creator to generate and validate data keys",
    "Effect": "Allow",
    "Principal": { "AWS": "arn:aws:iam::111122223333:role/MyWebFunctionDeployRole" },
    "Action": [
        "kms:GenerateDataKey",
        "kms:Decrypt"
    ],
    "Resource": "*",
    "Condition": {
        "StringLike": {
            "kms:EncryptionContext:aws:lambda:WebFunctionRevisionArn": "arn:aws:lambda:us-east-1:111122223333:web-function/my-function/revision/*"
        }
    }
}

kms:ViaService condition

The kms:ViaService condition restricts the key so that only requests that Lambda makes on your behalf can use it. The value is Region-specific: lambda.us-east-1.amazonaws.com.

With this condition, AWS KMS denies direct calls made with the same credentials (for example, running aws kms generate-data-key yourself), but creating a Web Function succeeds because Lambda makes the AWS KMS calls for you.

AWS KMS does not share key policies between related multi-Region keys. Each replica key has its own policy. When you use the kms:ViaService condition with a multi-Region key, use the Regional service name that matches each key's Region (for example,