Menu
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 your account's default CMK for Amazon WorkSpaces (use the alias aws/workspaces), or you can choose a custom CMK that you created separately in AWS KMS.

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 use your account's default customer master key (CMK) for Amazon WorkSpaces with the alias aws/workspaces, or you can use a custom CMK that you create. If you use the default CMK for Amazon WorkSpaces, you don't need to perform any steps to give Amazon WorkSpaces permission to use it. AWS KMS automatically specifies the necessary permissions in the key policy for the default CMK.

To use a custom CMK, the WorkSpaces administrators who create WorkSpaces with encrypted volumes must have permission to use the CMK. The WorkSpaces administrators don't use the CMK directly. Simply creating a WorkSpace with encrypted volumes implicitly creates the grant that gives Amazon WorkSpaces permission to use the CMK on the administrator's behalf.

Even though the WorkSpaces administrators don't use the CMK directly, they need permission to use the CMK because they can only grant permissions that they have. To give WorkSpaces administrators permission to use a CMK, do these things:

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 add WorkSpaces administrators to the list of key users in a CMK's key policy, you can use the AWS Management Console or the AWS Command Line Interface (AWS CLI).

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

  1. Open the Encryption Keys section of the Identity and Access Management (IAM) console at https://console.aws.amazon.com/iam/home#encryptionKeys.

  2. For Region, choose the appropriate AWS region. Do not use the region selector in the navigation bar (top right corner).

  3. Choose the alias of the CMK that WorkSpaces administrators will use.

  4. In the Key Policy section, under Key Users, choose Add.

  5. 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 (AWS CLI)

  1. Use the aws kms get-key-policy command to retrieve 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 aws kms put-key-policy command to apply the key policy to the CMK.

Part 2: Giving WorkSpaces Administrators Extra Permissions with an IAM Policy

In addition to the permissions in the key users section of the default key policy, WorkSpaces administrators need some permissions in an IAM user policy that applies to them. 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.

At minimum, WorkSpaces administrators need permission to create grants for the custom CMK(s) that they will use with Amazon WorkSpaces. To use the AWS Management Console to create WorkSpaces with encrypted volumes, WorkSpaces administrators also need permission to list aliases and list keys, which are actions that the console performs on behalf of WorkSpaces administrators to display a list of available CMKs.

To give these permissions to your WorkSpaces administrators, add an IAM policy similar to the following example to your WorkSpaces administrators. Replace arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab in the first policy statement with the ARN(s) of the CMK(s) that WorkSpaces administrators will use when they create WorkSpaces with encrypted volumes. If your WorkSpaces administrators will launch WorkSpaces with only the Amazon WorkSpaces API (not with the console), you can omit the second statement with the "kms:ListAliases" and "kms:ListKeys" permissions.

Copy
{ "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": "*" } ] }