AWS Key Management Service
Developer Guide

How Amazon WorkSpaces Uses AWS KMS

You can use Amazon WorkSpaces to provision a cloud-based desktop (a WorkSpace) for each of your end users. When you launch a new WorkSpace, you can choose to encrypt its volumes and decide which AWS KMS customer master key (CMK) to use for the encryption. You can choose the AWS managed CMK for Amazon WorkSpaces (aws/workspaces) or a customer managed CMK.

For more information about creating WorkSpaces with encrypted volumes, go to Encrypt a WorkSpace in the Amazon WorkSpaces Administration Guide.

Overview of Amazon WorkSpaces Encryption Using AWS KMS

When you create WorkSpaces with encrypted volumes, Amazon WorkSpaces uses Amazon Elastic Block Store (Amazon EBS) to create and manage those volumes. Both services use your KMS customer master key (CMK) to work with the encrypted volumes. For more information about EBS volume encryption, see the following documentation:

When you launch WorkSpaces with encrypted volumes, the end-to-end process works like this:

  1. You specify the CMK to use for encryption as well as the WorkSpace's user and directory. This action creates a grant that allows Amazon WorkSpaces to use your CMK only for this WorkSpace—that is, only for the WorkSpace associated with the specified user and directory.

  2. Amazon WorkSpaces creates an encrypted EBS volume for the WorkSpace and specifies the CMK to use as well as the volume's user and directory (the same information that you specified at Step 1). This action creates a grant that allows Amazon EBS to use your CMK only for this WorkSpace and volume—that is, only for the WorkSpace associated with the specified user and directory, and only for the specified volume.

  3. Amazon EBS requests a volume data key that is encrypted under your CMK and specifies the WorkSpace user's Sid and directory ID as well as the volume ID as encryption context.

  4. AWS KMS creates a new data key, encrypts it under your CMK, and then sends the encrypted data key to Amazon EBS.

  5. Amazon WorkSpaces uses Amazon EBS to attach the encrypted volume to your WorkSpace, at which time Amazon EBS sends the encrypted data key to AWS KMS with a Decrypt request and specifies the WorkSpace user's Sid and directory ID as well as the volume ID as encryption context.

  6. AWS KMS uses your CMK to decrypt the data key, and then sends the plaintext data key to Amazon EBS.

  7. Amazon EBS uses the plaintext data key to encrypt all data going to and from the encrypted volume. Amazon EBS keeps the plaintext data key in memory for as long as the volume is attached to the WorkSpace.

  8. Amazon EBS stores the encrypted data key (received at Step 4) with the volume metadata for future use in case you reboot or rebuild the WorkSpace.

  9. When you use the AWS Management Console to remove a WorkSpace (or use the TerminateWorkspaces action in the Amazon WorkSpaces API), Amazon WorkSpaces and Amazon EBS retire the grants that allowed them to use your CMK for that WorkSpace.

Amazon WorkSpaces Encryption Context

Amazon WorkSpaces doesn't use your customer master key (CMK) directly for cryptographic operations (such as Encrypt, Decrypt, GenerateDataKey, etc.), which means Amazon WorkSpaces doesn't send requests to AWS KMS that include encryption context. However, when Amazon EBS requests an encrypted data key for the encrypted volumes of your WorkSpaces (Step 3 in the Overview of Amazon WorkSpaces Encryption Using AWS KMS) and when it requests a plaintext copy of that data key (Step 5), it includes encryption context in the request. The encryption context provides additional authenticated information that AWS KMS uses to ensure data integrity. The encryption context is also written to your AWS CloudTrail log files, which can help you understand why a given customer master key (CMK) was used. Amazon EBS uses the following for the encryption context:

  • The sid of the AWS Directory Service user that is associated with the WorkSpace

  • The directory ID of the AWS Directory Service directory that is associated with the WorkSpace

  • The volume ID of the encrypted volume

The following example shows a JSON representation of the encryption context that Amazon EBS uses:

{ "aws:workspaces:sid-directoryid": "[S-1-5-21-277731876-1789304096-451871588-1107]@[d-1234abcd01]", "aws:ebs:id": "vol-1234abcd" }

For more information about encryption context, see Encryption Context.

Giving Amazon WorkSpaces Permission to Use A CMK On Your Behalf

You can protect your workspace data under the AWS managed CMK for Amazon WorkSpaces (aws/workspaces) or a customer managed CMK. If you use a customer managed CMK, you need to give Amazon WorkSpaces permission to use the CMK on behalf of the Amazon WorkSpaces administrators in your account. The AWS managed CMK for Amazon WorkSpaces has the required permissions by default.

To prepare your customer managed CMK for use with Amazon WorkSpaces, use the following procedure.

Amazon WorkSpaces administrators also need permission to use Amazon WorkSpaces. For more information about these permissions, go to Controlling Access to Amazon WorkSpaces Resources in the Amazon WorkSpaces Administration Guide.

Part 1: Adding WorkSpaces Administrators to a CMK's Key Users

To give Amazon WorkSpaces administrators the permissions that they require, you can use the AWS Management Console or the AWS KMS API.

To add WorkSpaces administrators as key users for a CMK (Console)

  1. Sign in to the AWS Management Console and open the AWS Key Management Service (AWS KMS) console at https://console.aws.amazon.com/kms.

  2. To change the AWS Region, use the Region selector in the upper-right corner of the page.

  3. In the navigation pane, choose Customer managed keys.

  4. Choose the key ID or alias of your preferred customer managed CMK.

  5. In the Key policy section, under Key users, choose Add.

  6. In the list of IAM users and roles, select the users and roles that correspond to your WorkSpaces administrators, and then choose Attach.

To add WorkSpaces administrators as key users for a CMK (KMS API)

  1. Use the GetKeyPolicy operation to get the existing key policy, and then save the policy document to a file.

  2. Open the policy document in your preferred text editor. Add the IAM users and roles that correspond to your WorkSpaces administrators to the policy statements that give permission to key users. Then save the file.

  3. Use the PutKeyPolicy operation to apply the key policy to the CMK.

Part 2: Giving WorkSpaces Administrators Extra Permissions

If you are using a customer managed CMK to protect your Amazon WorkSpaces data, in addition to the permissions in the key users section of the default key policy, WorkSpaces administrators need permission to create grants on the CMK. Also, if they use the AWS Management Console to create WorkSpaces with encrypted volumes, WorkSpaces administrators need permission to list aliases and list keys. For information about creating and editing IAM user policies, go to Working with Managed Policies and Working with Inline Policies in the IAM User Guide.

To give these permissions to your WorkSpaces administrators, use an IAM policy. Add an policy statement similar to the following example to the IAM policy for each WorkSpaces administrator. Replace the example CMK ARN (arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab) with a valid one. If your WorkSpaces administrators use only the Amazon WorkSpaces API (not the console), you can omit the second policy statement with the "kms:ListAliases" and "kms:ListKeys" permissions.

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "kms:CreateGrant", "Resource": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab" }, { "Effect": "Allow", "Action": [ "kms:ListAliases", "kms:ListKeys" ], "Resource": "*" } ] }