Policy Encryption Key Label

Policy Encryption Key Label

Policy Agent sets a POLICY_ENCRYPTION_KEY_LABEL environment variable on each function listed in AWS_PROTECT_FN_NAME during policy deployment. The protector and log forwarder use this value to identify the correct decryption key for the policy package.

The agent reads the existing environment variables from each function before updating them, ensuring all previously configured environment variables remain intact.

Key Rotation

Policy encryption uses AWS KMS asymmetric keys with key usage ENCRYPT_DECRYPT. Symmetric keys and signing/verification keys are not supported. AWS KMS automatic key rotation is not available for asymmetric keys, so key rotation is always a manual key replacement process.

When you create a new KMS key, the key ID changes. Because POLICY_ENCRYPTION_KEY_LABEL identifies the KMS key used to decrypt the policy package by its KMS key ID (a UUID such as 07017b86-83d6-4df7-aeb5-c7931f7b61c5), you must update the Policy Agent and all protector functions before the new policy can be decrypted. Follow the steps below when rotating keys.

Create a New KMS Key

1. In the AWS Console, navigate to KMS > Customer managed keys.
2. Click Create key and follow the wizard to create a new asymmetric encryption key. Policy encryption supports asymmetric keys only.
3. Record the new Key ID (UUID format, e.g. 07017b86-83d6-4df7-aeb5-c7931f7b61c5). This becomes the new POLICY_ENCRYPTION_KEY_LABEL value once the agent deploys with it.
4. Ensure the Policy Agent execution role has kms:GetPublicKey permission on the new key. See Create Agent Lambda IAM Policy.

Update the Policy Agent

1. Navigate to the Policy Agent Lambda function (Protegrity_Agent_<STACK_NAME>) in the AWS Console.
2. Select Configuration > Environment variables > Edit.
3. Update AWS_KMS_KEY_ID with the new KMS key ID or full ARN.
4. Save the changes.

Redeploy the Policy

Scheduled execution

Policy Agent can be configured to run on a schedule as described in Policy Agent Schedule. In this case, policy Lambda layer encrypted with the newly specified key and corresponding POLICY_ENCRYPTION_KEY_LABEL environment variable will be rolled out to specified protectors on the next scheduled Policy Agent execution.

Manual execution

1. Navigate to the Test tab on the Policy Agent Lambda and run a deployment.

2. Confirm the deployment succeeds and that POLICY_ENCRYPTION_KEY_LABEL has been updated to the new key ID on each function listed in AWS_PROTECT_FN_NAME.

   Important

   When DISABLE_DEPLOY=1, the Policy Agent will not update POLICY_ENCRYPTION_KEY_LABEL on any Protector or Log Forwarder function. You must manually apply both the new policy Lambda layer and the new POLICY_ENCRYPTION_KEY_LABEL value to each affected function — see the warning under Policy Encryption Key Label above for the recommended single-call procedure.

IAM Permissions

The Policy Agent requires the following Lambda permissions to manage function environment variables:

• lambda:GetFunctionConfiguration — read the current function configuration including existing environment variables.
• lambda:UpdateFunctionConfiguration — update the function with the new policy layer and environment variables.

Both permissions are included in the Create Agent Lambda IAM Policy section. Verify these permissions are present in the agent execution role.