AWS transcribe: Document customer-managed KMS key encryption for Transcribe resource artifacts
Summary
Adds a new section explaining how to encrypt custom vocabularies, vocabulary filters, and custom language models at rest using a customer-managed KMS key via the EncryptionConfiguration parameter, including KMSKey/KMSEncryptionContext fields, required DataAccessRoleArn permissions, a warning about disabling/deleting keys, and notes on decrypting download URIs with the AWS Encryption SDK.
Security assessment
The change documents a security feature (customer-managed KMS encryption at rest for resource artifacts) and the IAM permissions/role required to use the key, plus a warning that disabling or deleting the key or revoking role permissions can break jobs/resources. It is security best-practice/feature documentation rather than a fix for a specific vulnerability, so no CVE or incident is referenced.
Evidence
For additional control over encryption, you can use a customer-managed KMS key to encrypt the artifacts associated with your custom vocabularies, custom vocabulary filters, and custom language models.
Diff
diff --git a/transcribe/latest/dg/data-encryption.md b/transcribe/latest/dg/data-encryption.md index e6ae05609..9b8674def 100644 --- a//transcribe/latest/dg/data-encryption.md +++ b//transcribe/latest/dg/data-encryption.md @@ -7 +7 @@ -Encryption at restEncryption in transitKey managementAWS KMS encryption context +Encryption at restEncryption in transitKey managementEncrypting resource artifacts with a customer-managed keyAWS KMS encryption context @@ -18,0 +19,2 @@ When you use the [`StartTranscriptionJob`](https://docs.aws.amazon.com/transcrib +When you create or update custom vocabularies, custom vocabulary filters, or custom language models, you can specify a customer-managed KMS key to encrypt the associated resource artifacts at rest. If you do not provide a KMS key, Amazon Transcribe encrypts these artifacts using an AWS-owned key. For more information about encrypting resource artifacts with a customer-managed key, see Encrypting resource artifacts with a customer-managed key. + @@ -50 +52,3 @@ To use output encryption with the API, you must specify your KMS key using the ` -If using a key located in the **current** AWS account, you can specify your KMS key in one of four ways: +Specify your KMS key using the Amazon Resource Name (ARN) of the key. KMS key ARNs have the format `arn:`partition`:kms:`region`:`account-ID`:key/`key-id``. For example, `arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab`. + +Note that the entity making the request must have permission to use the specified KMS key. @@ -52 +56 @@ If using a key located in the **current** AWS account, you can specify your KMS - 1. Use the KMS key ID itself. For example, `1234abcd-12ab-34cd-56ef-1234567890ab`. +## Encrypting resource artifacts with a customer-managed key @@ -54 +58 @@ If using a key located in the **current** AWS account, you can specify your KMS - 2. Use an alias for the KMS key ID. For example, `alias/ExampleAlias`. +For additional control over encryption, you can use a customer-managed KMS key to encrypt the artifacts associated with your custom vocabularies, custom vocabulary filters, and custom language models. @@ -56 +60 @@ If using a key located in the **current** AWS account, you can specify your KMS - 3. Use the Amazon Resource Name (ARN) for the KMS key ID. For example, `arn:aws:kms:region:account-ID:key/1234abcd-12ab-34cd-56ef-1234567890ab`. +###### Warning @@ -58 +62 @@ If using a key located in the **current** AWS account, you can specify your KMS - 4. Use the ARN for the KMS key alias. For example, `arn:aws:kms:region:account-ID:alias/ExampleAlias`. +Do not disable or delete a customer-managed KMS key, or revoke the permissions granted to the data access role, while your resources are in use. If Amazon Transcribe cannot access the key during a transcription job, the job fails. If key access is lost during a resource update, the resource can become unusable. To recover, restore access to the key and call the corresponding Update operation (for example, `UpdateVocabulary`, `UpdateVocabularyFilter`, or `UpdateLanguageModel`). @@ -59,0 +64 @@ If using a key located in the **current** AWS account, you can specify your KMS +To configure encryption, include the `EncryptionConfiguration` parameter when calling the following operations: @@ -60,0 +66 @@ If using a key located in the **current** AWS account, you can specify your KMS + * [`CreateVocabulary`](https://docs.aws.amazon.com/transcribe/latest/APIReference/API_CreateVocabulary.html), [`UpdateVocabulary`](https://docs.aws.amazon.com/transcribe/latest/APIReference/API_UpdateVocabulary.html) @@ -61,0 +68 @@ If using a key located in the **current** AWS account, you can specify your KMS + * [`CreateVocabularyFilter`](https://docs.aws.amazon.com/transcribe/latest/APIReference/API_CreateVocabularyFilter.html), [`UpdateVocabularyFilter`](https://docs.aws.amazon.com/transcribe/latest/APIReference/API_UpdateVocabularyFilter.html) @@ -63 +70 @@ If using a key located in the **current** AWS account, you can specify your KMS -If using a key located in a **different** AWS account than the current AWS account, you can specify your KMS key in one of two ways: + * [`CreateLanguageModel`](https://docs.aws.amazon.com/transcribe/latest/APIReference/API_CreateLanguageModel.html), [`UpdateLanguageModel`](https://docs.aws.amazon.com/transcribe/latest/APIReference/API_UpdateLanguageModel.html) @@ -65 +71,0 @@ If using a key located in a **different** AWS account than the current AWS accou - 1. Use the ARN for the KMS key ID. For example, `arn:aws:kms:region:account-ID:key/1234abcd-12ab-34cd-56ef-1234567890ab`. @@ -67 +72,0 @@ If using a key located in a **different** AWS account than the current AWS accou - 2. Use the ARN for the KMS key alias. For example, `arn:aws:kms:region:account-ID:alias/ExampleAlias`. @@ -69,0 +75,6 @@ If using a key located in a **different** AWS account than the current AWS accou +The `EncryptionConfiguration` object contains the following fields: + + * `KMSKey` (required) – The Amazon Resource Name (ARN) of the KMS key to use for encryption. KMS key ARNs have the format `arn:`partition`:kms:`region`:`account-ID`:key/`key-id``. For example, `arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab`. + + * `KMSEncryptionContext` (optional) – A map of key:value pairs that provide an additional layer of security. For more information, see AWS KMS encryption context. + @@ -72 +83,10 @@ If using a key located in a **different** AWS account than the current AWS accou -Note that the entity making the request must have permission to use the specified KMS key. + +You must also provide a `DataAccessRoleArn` that references an IAM role with permissions to use the specified KMS key. For more information about the required AWS KMS permissions and an example policy, see [Permissions required for customer-managed key encryption](./security_iam_id-based-policy-examples.html#auth-role-cmk). + +###### Note + +You can change the KMS key used to encrypt a resource by calling the corresponding Update operation with a new `EncryptionConfiguration`. If you omit `EncryptionConfiguration` from an Update request, the resource artifacts are encrypted with an AWS-owned key. + +###### Note + +When a custom vocabulary or custom vocabulary filter is encrypted with a customer-managed key, the download URI returned by [`GetVocabulary`](https://docs.aws.amazon.com/transcribe/latest/APIReference/API_GetVocabulary.html) or [`GetVocabularyFilter`](https://docs.aws.amazon.com/transcribe/latest/APIReference/API_GetVocabularyFilter.html) points to encrypted data. To decrypt this data, use the [AWS Encryption SDK](https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/introduction.html) with the same KMS key that was used to encrypt the resource. Direct AWS KMS decryption is not supported. If no customer-managed key was specified, these URIs return unencrypted data. @@ -87,0 +108,2 @@ To use output encryption with the API, set the `KMSEncryptionContext` parameter +You can also specify encryption context when encrypting resource artifacts (custom vocabularies, custom vocabulary filters, and custom language models) by including the `KMSEncryptionContext` field in the `EncryptionConfiguration` parameter. For more information about encrypting resource artifacts with a customer-managed key, see Encrypting resource artifacts with a customer-managed key. +