# Using encryption with voice analytics
Amazon Chime SDK voice analytics stores the audio files used to generate voice embedding. The files are encrypted using a symmetric customer managed key that you create, own, and manage. Because you have full control over this layer of encryption, you can perform such tasks as:
+ Establishing and maintaining key policies
+ Establishing and maintaining IAM policies and grants
+ Enabling and disabling key policies
+ Rotating key cryptographic material
+ Adding tags
+ Creating key aliases
+ Scheduling keys for deletion
For more information, see [ Customer managed keys ](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#customer-cmk) in the *AWS Key Management Service Developer Guide*.
# Understanding encryption at rest
By default, voice analytics encrypts all user data at rest. When creating a new voice profile domain, you must provide a symmetric customer managed key that the service uses to encrypt your data at rest. You own, manage and control the key.
The key only encrypts the audio files used to enroll speakers in voice embeddings.
Voice analytics accesses the key by creating grants. For more information about grants, see the next section.
# Understanding how voice analytics uses grants
Voice analytics requires a grant to use your customer managed key. When you create a voice profile domain, the associated Amazon Chime SDK Voice Connector creates a grant on your behalf by sending a `CreateGrant` request to the AWS KMS. The grant is required in order to use your key for the following internal operations:
+ Sending [https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeKey.html](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeKey.html) requests to AWS KMS to verify that the symmetric customer managed key ID provided is valid.
+ Sending [https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html) requests to KMS key to create data keys with which to encrypt objects.
+ Sending [https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html) requests to AWS KMS to decrypt the encrypted data keys so that they can be used to encrypt your data.
+ Sending [https://docs.aws.amazon.com/kms/latest/APIReference/API_RetireGrant.html](https://docs.aws.amazon.com/kms/latest/APIReference/API_RetireGrant.html) requests to AWS KMS to retire the grants used for a voice profile domain.
+ Storing files in Amazon S3 with server side encryption.
You can revoke access to the grant, or remove the service's access to your key at any time. If you do, voice analytics won't be able to access any of the data encrypted by the key. That affects all the operations that depend on that data, leading to `AccessDeniedException` errors and failures in the speaker search workflows.
# Key policy for voice analytics
Key policies control access to your customer managed key. Every customer managed key must have exactly one key policy, with policy statements that determine who can use the key and how they can use it. When you create your key, you can specify a key policy. For more information, see [ Working with key policies](https://docs.aws.amazon.com/kms/latest/developerguide/programming-key-policies.html) in the *AWS Key Management Service Developer Guide*.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "Allow key access to Chime SDK voice analytics.",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::111122223333:user/UserNameWithPath"
},
"Action": [
"kms:CreateGrant",
"kms:Decrypt",
"kms:DescribeKey"
],
"Resource": "*",
"Condition": {
"StringEquals": {
"kms:ViaService": [
"chime.us-east-1.amazonaws.com"
]
}
}
}
]
}
```
------
For information about specifying permissions in a policy, see [ Specifying KMS keys in IAM policy statements](https://docs.aws.amazon.com/kms/latest/developerguide/cmks-in-iam-policies.html) in the *AWS Key Management Service Developer Guide*.
For information about troubleshooting key access, see [Troubleshooting key access](https://docs.aws.amazon.com/kms/latest/developerguide/policy-evaluation.html) in the *AWS Key Management Service Developer Guide*.
# Using encryption context
An encryption context is an optional set of key-value pairs that contain additional contextual information about the data. AWS KMS uses the encryption context to support authenticated encryption.
When you include an encryption context in an encryption request, AWS KMS binds the encryption context to the encrypted data. To decrypt data, you include the same encryption context in the request.
Voice analytics uses the same encryption context in all AWS KMS cryptographic operations, where the key is `aws:chime:voice-profile-domain:arn` and the value is the resource Amazon Resource Name (ARN).
The following example shows a typical encryption context.
```
"encryptionContext": {
"aws:chime:voice-profile-domain:arn": "arn:aws:chime:us-west-2:111122223333:voice-profile-domain/sample-domain-id"
}
```
You can also use the encryption context in audit records and logs to identify how the customer managed key is being used. The encryption context also appears in logs generated by CloudTrail or CloudWatch Logs.
## Using encryption context to control access to your key
You can use the encryption context in key policies and IAM policies as conditions to control access to your symmetric customer managed key. You can also use encryption context constraints in a grant.
Voice analytics uses an encryption context constraint in grants to control access to the customer managed keys in your account or Region. The grant constraint requires that the operations that the grant allows use the specified encryption context.
The following example key policy statements grant access to a customer managed key for a specific encryption context. The condition in the policy statement requires that the grants have an encryption context constraint that specifies the encryption context.
```
{
"Sid": "Enable DescribeKey",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::111122223333:role/ExampleReadOnlyRole"
},
"Action": "kms:DescribeKey",
"Resource": "*"
},
{
"Sid": "Enable CreateGrant",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::111122223333:role/ExampleReadOnlyRole"
},
"Action": "kms:CreateGrant",
"Resource": "*",
"Condition": {
"StringEquals": {
"kms:EncryptionContext:aws:chime:voice-profile-domain:arn": "arn:aws:chime:us-west-2:111122223333:voice-profile-domain/sample-domain-id"
}
}
}
```
# Monitoring encryption keys
Amazon Chime SDK Voice Connectors send requests to AWS KMS, and you can track those requests in CloudTrail or CloudWatch logs.
------
#### [ CreateGrant ]
When you use a customer managed key to create a voice profile domain resource, the associated Voice Connector sends a `CreateGrant` request on your behalf to access the KMS key in your AWS account. The grant that the Voice Connector creates is specific to the resource associated with the customer managed key. The Voice Connector also uses the `RetireGrant` operation to remove a grant when you delete a resource.
The following example records a `CreateGrant` operation.
```
{
"eventVersion": "1.08",
"userIdentity": {
"type": "AssumedRole",
"principalId": "AROAIGDTESTANDEXAMPLE:Sampleuser01",
"arn": "arn:aws:sts::111122223333:assumed-role/Admin/Sampleuser01",
"accountId": "111122223333",
"accessKeyId": "AKIAIOSFODNN7EXAMPLE3",
"sessionContext": {
"sessionIssuer": {
"type": "Role",
"principalId": "AROAIGDTESTANDEXAMPLE:Sampleuser01",
"arn": "arn:aws:sts::111122223333:assumed-role/Admin/Sampleuser01",
"accountId": "111122223333",
"userName": "Admin"
},
"webIdFederationData": {},
"attributes": {
"mfaAuthenticated": "false",
"creationDate": "2021-04-22T17:02:00Z"
}
},
"invokedBy": "AWS Internal"
},
"eventTime": "2021-04-22T17:07:02Z",
"eventSource": "kms.amazonaws.com",
"eventName": "CreateGrant",
"awsRegion": "us-west-2",
"sourceIPAddress": "172.12.34.56",
"userAgent": "ExampleDesktop/1.0 (V1; OS)",
"requestParameters": {
"constraints": {
"encryptionContextSubset": {
"aws:chime:voice-profile-domain:arn": "arn:aws:chime:us-west-2:111122223333:voice-profile-domain/sample-domain-id"
}
},
"retiringPrincipal": "chimevoiceconnector.region.amazonaws.com",
"operations": [
"GenerateDataKey",
"Decrypt",
"DescribeKey",
"RetireGrant"
],
"keyId": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-123456SAMPLE",
"granteePrincipal": "chimevoiceconnector.region.amazonaws.com",
"retiringPrincipal": "chimevoiceconnector.region.amazonaws.com"
},
"responseElements": {
"grantId": "0ab0ac0d0b000f00ea00cc0a0e00fc00bce000c000f0000000c0bc0a0000aaafSAMPLE"
},
"requestID": "ff000af-00eb-00ce-0e00-ea000fb0fba0SAMPLE",
"eventID": "ff000af-00eb-00ce-0e00-ea000fb0fba0SAMPLE",
"readOnly": false,
"resources": [
{
"accountId": "111122223333",
"type": "AWS::KMS::Key",
"ARN": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-123456SAMPLE"
}
],
"eventType": "AwsApiCall",
"managementEvent": true,
"eventCategory": "Management",
"recipientAccountId": "111122223333"
}
```
------
#### [ GenerateDataKey ]
When you create a voice profile domain and assign a customer managed key to the domain, the associated Voice Connector creates a unique data key to encrypt each speaker’s enrollment audio. The Voice Connector sends a `GenerateDataKey` request to AWS KMS that specifies the key for the resource.
The following example records a `GenerateDataKey` operation.
```
{
"eventVersion": "1.08",
"userIdentity": {
"type": "AWSService",
"invokedBy": "AWS Internal"
},
"eventTime": "2021-04-22T17:07:02Z",
"eventSource": "kms.amazonaws.com",
"eventName": "GenerateDataKey",
"awsRegion": "us-west-2",
"sourceIPAddress": "172.12.34.56",
"userAgent": "ExampleDesktop/1.0 (V1; OS)",
"requestParameters": {
"encryptionContext": {
"aws:chime:voice-profile-domain:arn": "arn:aws:chime:us-west-2:111122223333:voice-profile-domain/sample-domain-id"
},
"keySpec": "AES_256",
"keyId": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-123456SAMPLE"
},
"responseElements": null,
"requestID": "ff000af-00eb-00ce-0e00-ea000fb0fba0SAMPLE",
"eventID": "ff000af-00eb-00ce-0e00-ea000fb0fba0SAMPLE",
"readOnly": true,
"resources": [
{
"accountId": "111122223333",
"type": "AWS::KMS::Key",
"ARN": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-123456SAMPLE"
}
],
"eventType": "AwsApiCall",
"managementEvent": true,
"eventCategory": "Management",
"recipientAccountId": "111122223333",
"sharedEventID": "57f5dbee-16da-413e-979f-2c4c6663475e"
}
```
------
#### [ Decrypt ]
When a voice profile in a voice profile domain needs to have its voice print upgraded because of a newer voice recognition model, the associated Voice Connector calls the `Decrypt` operation to use the stored encrypted data key to access the encrypted data.
The following example records a `Decrypt` operation.
```
{
"eventVersion": "1.08",
"userIdentity": {
"type": "AWSService",
"invokedBy": "AWS Internal"
},
"eventTime": "2021-10-12T23:59:34Z",
"eventSource": "kms.amazonaws.com",
"eventName": "Decrypt",
"awsRegion": "us-west-2",
"sourceIPAddress": "172.12.34.56",
"userAgent": "ExampleDesktop/1.0 (V1; OS)",
"requestParameters": {
"encryptionContext": {
"keyId": "arn:aws:kms:us-west-2:111122223333:key/44444444-3333-2222-1111-EXAMPLE11111",
"encryptionContext": {
"aws:chime:voice-profile-domain:arn": "arn:aws:chime:us-west-2:111122223333:voice-profile-domain/sample-domain-id"
},
"encryptionAlgorithm": "SYMMETRIC_DEFAULT"
},
"responseElements": null,
"requestID": "ed0fe4ab-305b-4388-8adf-7e8e3a4e80fe",
"eventID": "31d0d7c6-ce5b-4caf-901f-025bf71241f6",
"readOnly": true,
"resources": [{
"accountId": "111122223333",
"type": "AWS::KMS::Key",
"ARN": "arn:aws:kms:us-west-2:111122223333:key/00000000-1111-2222-3333-9999999999999"
}],
"eventType": "AwsApiCall",
"managementEvent": true,
"recipientAccountId": "111122223333",
"sharedEventID": "35d58aa1-26b2-427a-908f-025bf71241f6",
"eventCategory": "Management"
}
```
------
#### [ DescribeKey ]
Voice Connectors use the `DescribeKey` operation to verify that the key associated with a voice profile domain exists in the account and Region.
The following example records a `DescribeKey` operation.
```
{
"eventVersion": "1.08",
"userIdentity": {
"type": "AssumedRole",
"principalId": "AROAIGDTESTANDEXAMPLE:Sampleuser01",
"arn": "arn:aws:sts::111122223333:assumed-role/Admin/Sampleuser01",
"accountId": "111122223333",
"accessKeyId": "AKIAIOSFODNN7EXAMPLE3",
"sessionContext": {
"sessionIssuer": {
"type": "Role",
"principalId": "AROAIGDTESTANDEXAMPLE:Sampleuser01",
"arn": "arn:aws:sts::111122223333:assumed-role/Admin/Sampleuser01",
"accountId": "111122223333",
"userName": "Admin"
},
"webIdFederationData": {},
"attributes": {
"mfaAuthenticated": "false",
"creationDate": "2021-04-22T17:02:00Z"
}
},
"invokedBy": "AWS Internal"
},
"eventTime": "2021-04-22T17:07:02Z",
"eventSource": "kms.amazonaws.com",
"eventName": "DescribeKey",
"awsRegion": "us-west-2",
"sourceIPAddress": "172.12.34.56",
"userAgent": "ExampleDesktop/1.0 (V1; OS)",
"requestParameters": {
"keyId": "00dd0db0-0000-0000-ac00-b0c000SAMPLE"
},
"responseElements": null,
"requestID": "ff000af-00eb-00ce-0e00-ea000fb0fba0SAMPLE",
"eventID": "ff000af-00eb-00ce-0e00-ea000fb0fba0SAMPLE",
"readOnly": true,
"resources": [
{
"accountId": "111122223333",
"type": "AWS::KMS::Key",
"ARN": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-123456SAMPLE"
}
],
"eventType": "AwsApiCall",
"managementEvent": true,
"eventCategory": "Management",
"recipientAccountId": "111122223333"
}
```
------