How WorkSpaces uses Amazon KMS - Amazon Key Management Service
Overview of WorkSpaces encryption using Amazon KMSWorkSpaces encryption contextGiving WorkSpaces permission to use a KMS key on your behalf
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

How WorkSpaces uses Amazon KMS

You can use 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 Amazon KMS key to use for the encryption. You can choose the Amazon managed key for WorkSpaces (aws/workspaces) or a symmetric customer managed key.

Important

WorkSpaces supports only symmetric encryption KMS keys. You cannot use an asymmetric KMS key to encrypt the volumes in an WorkSpaces. For help determining whether a KMS key is symmetric or asymmetric, see Identifying asymmetric KMS keys.

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

Overview of WorkSpaces encryption using Amazon KMS

When you create WorkSpaces with encrypted volumes, WorkSpaces uses Amazon Elastic Block Store (Amazon EBS) to create and manage those volumes. Both services use your Amazon KMS key 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 KMS key to use for encryption as well as the WorkSpace's user and directory. This action creates a grant that allows WorkSpaces to use your KMS key only for this WorkSpace—that is, only for the WorkSpace associated with the specified user and directory.

  2. WorkSpaces creates an encrypted EBS volume for the WorkSpace and specifies the KMS key 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 KMS key 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 KMS key and specifies the WorkSpace user's Sid and directory ID as well as the volume ID as encryption context.

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

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

  6. Amazon KMS uses your KMS key 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 Amazon Web Services Management Console to remove a WorkSpace (or use the TerminateWorkspaces action in the WorkSpaces API), WorkSpaces and Amazon EBS retire the grants that allowed them to use your KMS key for that WorkSpace.

WorkSpaces encryption context

WorkSpaces doesn't use your Amazon KMS key directly for cryptographic operations (such as Encrypt, Decrypt, GenerateDataKey, etc.), which means WorkSpaces doesn't send requests to Amazon KMS that include an encryption context. However, when Amazon EBS requests an encrypted data key for the encrypted volumes of your WorkSpaces (Step 3 in the Overview of WorkSpaces encryption using Amazon 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 data (AAD) that Amazon KMS uses to ensure data integrity. The encryption context is also written to your Amazon CloudTrail log files, which can help you understand why a given Amazon KMS key was used. Amazon EBS uses the following for the encryption context:

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

  • The directory ID of the Amazon 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"
}

Giving WorkSpaces permission to use a KMS key on your behalf

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

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

  1. Add the WorkSpaces administrators to the list of key users in the KMS key's key policy

  2. Give the WorkSpaces administrators additional permissions with an IAM policy

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

Part 1: Adding WorkSpaces administrators to a KMS key's key users

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

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

  1. Sign in to the Amazon Web Services Management Console and open the Amazon Key Management Service (Amazon KMS) console at https://console.amazonaws.cn/kms.

  2. To change the Amazon Web Services 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 key

  5. Choose the Key policy tab. 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 KMS key (Amazon 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 KMS key.

Part 2: Giving WorkSpaces administrators extra permissions

If you are using a customer managed key to protect your 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 KMS key. Also, if they use the Amazon Web Services 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, see Managed Policies and 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 KMS key 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 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": "*"
    }
  ]
}