void encrypt_with_caching(
uint8_t *ciphertext, // output will go here (assumes ciphertext_capacity bytes already allocated)
size_t *ciphertext_len, // length of output will go here
size_t ciphertext_capacity,
const char *kms_key_arn,
int max_entry_age,
int cache_capacity) {
const uint64_t MAX_ENTRY_MSGS = 100;
struct aws_allocator *allocator = aws_default_allocator();
// Load error strings for debugging
aws_cryptosdk_load_error_strings();
// Create a keyring
struct aws_cryptosdk_keyring *kms_keyring = Aws::Cryptosdk::KmsKeyring::Builder().Build(kms_key_arn);
// Create a cache
struct aws_cryptosdk_materials_cache *cache = aws_cryptosdk_materials_cache_local_new(allocator, cache_capacity);
// Create a caching CMM
struct aws_cryptosdk_cmm *caching_cmm = aws_cryptosdk_caching_cmm_new_from_keyring(
allocator, cache, kms_keyring, NULL, max_entry_age, AWS_TIMESTAMP_SECS);
if (!caching_cmm) abort();
if (aws_cryptosdk_caching_cmm_set_limit_messages(caching_cmm, MAX_ENTRY_MSGS)) abort();
// Create a session
struct aws_cryptosdk_session *session =
aws_cryptosdk_session_new_from_cmm_2(allocator, AWS_CRYPTOSDK_ENCRYPT, caching_cmm);
if (!session) abort();
// Encryption context
struct aws_hash_table *enc_ctx = aws_cryptosdk_session_get_enc_ctx_ptr_mut(session);
if (!enc_ctx) abort();
AWS_STATIC_STRING_FROM_LITERAL(enc_ctx_key, "purpose");
AWS_STATIC_STRING_FROM_LITERAL(enc_ctx_value, "test");
if (aws_hash_table_put(enc_ctx, enc_ctx_key, (void *)enc_ctx_value, NULL)) abort();
// Plaintext data to be encrypted
const char *my_data = "My plaintext data";
size_t my_data_len = strlen(my_data);
if (aws_cryptosdk_session_set_message_size(session, my_data_len)) abort();
// When the session uses a caching CMM, the encryption operation uses the data key cache
// specified in the caching CMM.
size_t bytes_read;
if (aws_cryptosdk_session_process(
session,
ciphertext,
ciphertext_capacity,
ciphertext_len,
(const uint8_t *)my_data,
my_data_len,
&bytes_read))
abort();
if (!aws_cryptosdk_session_is_done(session) || bytes_read != my_data_len) abort();
aws_cryptosdk_session_destroy(session);
aws_cryptosdk_cmm_release(caching_cmm);
aws_cryptosdk_materials_cache_release(cache);
aws_cryptosdk_keyring_release(kms_keyring);
}
```
------
#### [ Java ]
The following example uses version 2.*x* of the AWS Encryption SDK for Java. Version 3.*x* of the AWS Encryption SDK for Java deprecates the data key caching CMM. With version 3.*x*, you can also use the [AWS KMS Hierarchical keyring](use-hierarchical-keyring.md), an alternative cryptographic materials caching solution.
```
// Copyright Amazon.com Inc. or its affiliates. All Rights Reserved.
// SPDX-License-Identifier: Apache-2.0
package com.amazonaws.crypto.examples;
import com.amazonaws.encryptionsdk.AwsCrypto;
import com.amazonaws.encryptionsdk.CryptoMaterialsManager;
import com.amazonaws.encryptionsdk.MasterKeyProvider;
import com.amazonaws.encryptionsdk.caching.CachingCryptoMaterialsManager;
import com.amazonaws.encryptionsdk.caching.CryptoMaterialsCache;
import com.amazonaws.encryptionsdk.caching.LocalCryptoMaterialsCache;
import com.amazonaws.encryptionsdk.kmssdkv2.KmsMasterKey;
import com.amazonaws.encryptionsdk.kmssdkv2.KmsMasterKeyProvider;
import java.nio.charset.StandardCharsets;
import java.util.Collections;
import java.util.Map;
import java.util.concurrent.TimeUnit;
/**
*
* Encrypts a string using an &KMS; key and data key caching
*
*
* Arguments:
*
* - KMS Key ARN: To find the Amazon Resource Name of your &KMS; key,
* see 'Find the key ID and ARN' at https://docs.aws.amazon.com/kms/latest/developerguide/find-cmk-id-arn.html
*
- Max entry age: Maximum time (in seconds) that a cached entry can be used
*
- Cache capacity: Maximum number of entries in the cache
*
*/
public class SimpleDataKeyCachingExample {
/*
* Security thresholds
* Max entry age is required.
* Max messages (and max bytes) per data key are optional
*/
private static final int MAX_ENTRY_MSGS = 100;
public static byte[] encryptWithCaching(String kmsKeyArn, int maxEntryAge, int cacheCapacity) {
// Plaintext data to be encrypted
byte[] myData = "My plaintext data".getBytes(StandardCharsets.UTF_8);
// Encryption context
// Most encrypted data should have an associated encryption context
// to protect integrity. This sample uses placeholder values.
// For more information see:
// blogs.aws.amazon.com/security/post/Tx2LZ6WBJJANTNW/How-to-Protect-the-Integrity-of-Your-Encrypted-Data-by-Using-AWS-Key-Management
final Map encryptionContext = Collections.singletonMap("purpose", "test");
// Create a master key provider
MasterKeyProvider keyProvider = KmsMasterKeyProvider.builder()
.buildStrict(kmsKeyArn);
// Create a cache
CryptoMaterialsCache cache = new LocalCryptoMaterialsCache(cacheCapacity);
// Create a caching CMM
CryptoMaterialsManager cachingCmm =
CachingCryptoMaterialsManager.newBuilder().withMasterKeyProvider(keyProvider)
.withCache(cache)
.withMaxAge(maxEntryAge, TimeUnit.SECONDS)
.withMessageUseLimit(MAX_ENTRY_MSGS)
.build();
// When the call to encryptData specifies a caching CMM,
// the encryption operation uses the data key cache
final AwsCrypto encryptionSdk = AwsCrypto.standard();
return encryptionSdk.encryptData(cachingCmm, myData, encryptionContext).getResult();
}
}
```
------
#### [ JavaScript Browser ]
```
// Copyright Amazon.com Inc. or its affiliates. All Rights Reserved.
// SPDX-License-Identifier: Apache-2.0
/* This is a simple example of using a caching CMM with a KMS keyring
* to encrypt and decrypt using the AWS Encryption SDK for Javascript in a browser.
*/
import {
KmsKeyringBrowser,
KMS,
getClient,
buildClient,
CommitmentPolicy,
WebCryptoCachingMaterialsManager,
getLocalCryptographicMaterialsCache,
} from '@aws-crypto/client-browser'
import { toBase64 } from '@aws-sdk/util-base64-browser'
/* This builds the client with the REQUIRE_ENCRYPT_REQUIRE_DECRYPT commitment policy,
* which enforces that this client only encrypts using committing algorithm suites
* and enforces that this client
* will only decrypt encrypted messages
* that were created with a committing algorithm suite.
* This is the default commitment policy
* if you build the client with `buildClient()`.
*/
const { encrypt, decrypt } = buildClient(
CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
)
/* This is injected by webpack.
* The webpack.DefinePlugin or @aws-sdk/karma-credential-loader will replace the values when bundling.
* The credential values are pulled from @aws-sdk/credential-provider-node
* Use any method you like to get credentials into the browser.
* See kms.webpack.config
*/
declare const credentials: {
accessKeyId: string
secretAccessKey: string
sessionToken: string
}
/* This is done to facilitate testing. */
export async function testCachingCMMExample() {
/* This example uses an &KMS; keyring. The generator key in a &KMS; keyring generates and encrypts the data key.
* The caller needs kms:GenerateDataKey permission on the &KMS; key in generatorKeyId.
*/
const generatorKeyId =
'arn:aws:kms:us-west-2:658956600833:alias/EncryptDecrypt'
/* Adding additional KMS keys that can decrypt.
* The caller must have kms:Encrypt permission for every &KMS; key in keyIds.
* You might list several keys in different AWS Regions.
* This allows you to decrypt the data in any of the represented Regions.
* In this example, the generator key
* and the additional key are actually the same &KMS; key.
* In `generatorId`, this &KMS; key is identified by its alias ARN.
* In `keyIds`, this &KMS; key is identified by its key ARN.
* In practice, you would specify different &KMS; keys,
* or omit the `keyIds` parameter.
* This is *only* to demonstrate how the &KMS; key ARNs are configured.
*/
const keyIds = [
'arn:aws:kms:us-west-2:658956600833:key/b3537ef1-d8dc-4780-9f5a-55776cbb2f7f',
]
/* Need a client provider that will inject correct credentials.
* The credentials here are injected by webpack from your environment bundle is created
* The credential values are pulled using @aws-sdk/credential-provider-node.
* See kms.webpack.config
* You should inject your credential into the browser in a secure manner
* that works with your application.
*/
const { accessKeyId, secretAccessKey, sessionToken } = credentials
/* getClient takes a KMS client constructor
* and optional configuration values.
* The credentials can be injected here,
* because browsers do not have a standard credential discovery process the way Node.js does.
*/
const clientProvider = getClient(KMS, {
credentials: {
accessKeyId,
secretAccessKey,
sessionToken,
},
})
/* You must configure the KMS keyring with your &KMS; keys */
const keyring = new KmsKeyringBrowser({
clientProvider,
generatorKeyId,
keyIds,
})
/* Create a cache to hold the data keys (and related cryptographic material).
* This example uses the local cache provided by the Encryption SDK.
* The `capacity` value represents the maximum number of entries
* that the cache can hold.
* To make room for an additional entry,
* the cache evicts the oldest cached entry.
* Both encrypt and decrypt requests count independently towards this threshold.
* Entries that exceed any cache threshold are actively removed from the cache.
* By default, the SDK checks one item in the cache every 60 seconds (60,000 milliseconds).
* To change this frequency, pass in a `proactiveFrequency` value
* as the second parameter. This value is in milliseconds.
*/
const capacity = 100
const cache = getLocalCryptographicMaterialsCache(capacity)
/* The partition name lets multiple caching CMMs share the same local cryptographic cache.
* By default, the entries for each CMM are cached separately. However, if you want these CMMs to share the cache,
* use the same partition name for both caching CMMs.
* If you don't supply a partition name, the Encryption SDK generates a random name for each caching CMM.
* As a result, sharing elements in the cache MUST be an intentional operation.
*/
const partition = 'local partition name'
/* maxAge is the time in milliseconds that an entry will be cached.
* Elements are actively removed from the cache.
*/
const maxAge = 1000 * 60
/* The maximum number of bytes that will be encrypted under a single data key.
* This value is optional,
* but you should configure the lowest practical value.
*/
const maxBytesEncrypted = 100
/* The maximum number of messages that will be encrypted under a single data key.
* This value is optional,
* but you should configure the lowest practical value.
*/
const maxMessagesEncrypted = 10
const cachingCMM = new WebCryptoCachingMaterialsManager({
backingMaterials: keyring,
cache,
partition,
maxAge,
maxBytesEncrypted,
maxMessagesEncrypted,
})
/* Encryption context is a *very* powerful tool for controlling
* and managing access.
* When you pass an encryption context to the encrypt function,
* the encryption context is cryptographically bound to the ciphertext.
* If you don't pass in the same encryption context when decrypting,
* the decrypt function fails.
* The encryption context is ***not*** secret!
* Encrypted data is opaque.
* You can use an encryption context to assert things about the encrypted data.
* The encryption context helps you to determine
* whether the ciphertext you retrieved is the ciphertext you expect to decrypt.
* For example, if you are are only expecting data from 'us-west-2',
* the appearance of a different AWS Region in the encryption context can indicate malicious interference.
* See: https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/concepts.html#encryption-context
*
* Also, cached data keys are reused ***only*** when the encryption contexts passed into the functions are an exact case-sensitive match.
* See: https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/data-caching-details.html#caching-encryption-context
*/
const encryptionContext = {
stage: 'demo',
purpose: 'simple demonstration app',
origin: 'us-west-2',
}
/* Find data to encrypt. */
const plainText = new Uint8Array([1, 2, 3, 4, 5])
/* Encrypt the data.
* The caching CMM only reuses data keys
* when it know the length (or an estimate) of the plaintext.
* However, in the browser,
* you must provide all of the plaintext to the encrypt function.
* Therefore, the encrypt function in the browser knows the length of the plaintext
* and does not accept a plaintextLength option.
*/
const { result } = await encrypt(cachingCMM, plainText, { encryptionContext })
/* Log the plain text
* only for testing and to show that it works.
*/
console.log('plainText:', plainText)
document.write('plainText:' + plainText + '')
/* Log the base64-encoded result
* so that you can try decrypting it with another AWS Encryption SDK implementation.
*/
const resultBase64 = toBase64(result)
console.log(resultBase64)
document.write(resultBase64)
/* Decrypt the data.
* NOTE: This decrypt request will not use the data key
* that was cached during the encrypt operation.
* Data keys for encrypt and decrypt operations are cached separately.
*/
const { plaintext, messageHeader } = await decrypt(cachingCMM, result)
/* Grab the encryption context so you can verify it. */
const { encryptionContext: decryptedContext } = messageHeader
/* Verify the encryption context.
* If you use an algorithm suite with signing,
* the Encryption SDK adds a name-value pair to the encryption context that contains the public key.
* Because the encryption context might contain additional key-value pairs,
* do not include a test that requires that all key-value pairs match.
* Instead, verify that the key-value pairs that you supplied to the `encrypt` function are included in the encryption context that the `decrypt` function returns.
*/
Object.entries(encryptionContext).forEach(([key, value]) => {
if (decryptedContext[key] !== value)
throw new Error('Encryption Context does not match expected values')
})
/* Log the clear message
* only for testing and to show that it works.
*/
document.write('Decrypted:' + plaintext)
console.log(plaintext)
/* Return the values to make testing easy. */
return { plainText, plaintext }
}
```
------
#### [ JavaScript Node.js ]
```
// Copyright Amazon.com Inc. or its affiliates. All Rights Reserved.
// SPDX-License-Identifier: Apache-2.0
import {
KmsKeyringNode,
buildClient,
CommitmentPolicy,
NodeCachingMaterialsManager,
getLocalCryptographicMaterialsCache,
} from '@aws-crypto/client-node'
/* This builds the client with the REQUIRE_ENCRYPT_REQUIRE_DECRYPT commitment policy,
* which enforces that this client only encrypts using committing algorithm suites
* and enforces that this client
* will only decrypt encrypted messages
* that were created with a committing algorithm suite.
* This is the default commitment policy
* if you build the client with `buildClient()`.
*/
const { encrypt, decrypt } = buildClient(
CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
)
export async function cachingCMMNodeSimpleTest() {
/* An &KMS; key is required to generate the data key.
* You need kms:GenerateDataKey permission on the &KMS; key in generatorKeyId.
*/
const generatorKeyId =
'arn:aws:kms:us-west-2:658956600833:alias/EncryptDecrypt'
/* Adding alternate &KMS; keys that can decrypt.
* Access to kms:Encrypt is required for every &KMS; key in keyIds.
* You might list several keys in different AWS Regions.
* This allows you to decrypt the data in any of the represented Regions.
* In this example, the generator key
* and the additional key are actually the same &KMS; key.
* In `generatorId`, this &KMS; key is identified by its alias ARN.
* In `keyIds`, this &KMS; key is identified by its key ARN.
* In practice, you would specify different &KMS; keys,
* or omit the `keyIds` parameter.
* This is *only* to demonstrate how the &KMS; key ARNs are configured.
*/
const keyIds = [
'arn:aws:kms:us-west-2:658956600833:key/b3537ef1-d8dc-4780-9f5a-55776cbb2f7f',
]
/* The &KMS; keyring must be configured with the desired &KMS; keys
* This example passes the keyring to the caching CMM
* instead of using it directly.
*/
const keyring = new KmsKeyringNode({ generatorKeyId, keyIds })
/* Create a cache to hold the data keys (and related cryptographic material).
* This example uses the local cache provided by the Encryption SDK.
* The `capacity` value represents the maximum number of entries
* that the cache can hold.
* To make room for an additional entry,
* the cache evicts the oldest cached entry.
* Both encrypt and decrypt requests count independently towards this threshold.
* Entries that exceed any cache threshold are actively removed from the cache.
* By default, the SDK checks one item in the cache every 60 seconds (60,000 milliseconds).
* To change this frequency, pass in a `proactiveFrequency` value
* as the second parameter. This value is in milliseconds.
*/
const capacity = 100
const cache = getLocalCryptographicMaterialsCache(capacity)
/* The partition name lets multiple caching CMMs share the same local cryptographic cache.
* By default, the entries for each CMM are cached separately. However, if you want these CMMs to share the cache,
* use the same partition name for both caching CMMs.
* If you don't supply a partition name, the Encryption SDK generates a random name for each caching CMM.
* As a result, sharing elements in the cache MUST be an intentional operation.
*/
const partition = 'local partition name'
/* maxAge is the time in milliseconds that an entry will be cached.
* Elements are actively removed from the cache.
*/
const maxAge = 1000 * 60
/* The maximum amount of bytes that will be encrypted under a single data key.
* This value is optional,
* but you should configure the lowest value possible.
*/
const maxBytesEncrypted = 100
/* The maximum number of messages that will be encrypted under a single data key.
* This value is optional,
* but you should configure the lowest value possible.
*/
const maxMessagesEncrypted = 10
const cachingCMM = new NodeCachingMaterialsManager({
backingMaterials: keyring,
cache,
partition,
maxAge,
maxBytesEncrypted,
maxMessagesEncrypted,
})
/* Encryption context is a *very* powerful tool for controlling
* and managing access.
* When you pass an encryption context to the encrypt function,
* the encryption context is cryptographically bound to the ciphertext.
* If you don't pass in the same encryption context when decrypting,
* the decrypt function fails.
* The encryption context is ***not*** secret!
* Encrypted data is opaque.
* You can use an encryption context to assert things about the encrypted data.
* The encryption context helps you to determine
* whether the ciphertext you retrieved is the ciphertext you expect to decrypt.
* For example, if you are are only expecting data from 'us-west-2',
* the appearance of a different AWS Region in the encryption context can indicate malicious interference.
* See: https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/concepts.html#encryption-context
*
* Also, cached data keys are reused ***only*** when the encryption contexts passed into the functions are an exact case-sensitive match.
* See: https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/data-caching-details.html#caching-encryption-context
*/
const encryptionContext = {
stage: 'demo',
purpose: 'simple demonstration app',
origin: 'us-west-2',
}
/* Find data to encrypt. A simple string. */
const cleartext = 'asdf'
/* Encrypt the data.
* The caching CMM only reuses data keys
* when it know the length (or an estimate) of the plaintext.
* If you do not know the length,
* because the data is a stream
* provide an estimate of the largest expected value.
*
* If your estimate is smaller than the actual plaintext length
* the AWS Encryption SDK will throw an exception.
*
* If the plaintext is not a stream,
* the AWS Encryption SDK uses the actual plaintext length
* instead of any length you provide.
*/
const { result } = await encrypt(cachingCMM, cleartext, {
encryptionContext,
plaintextLength: 4,
})
/* Decrypt the data.
* NOTE: This decrypt request will not use the data key
* that was cached during the encrypt operation.
* Data keys for encrypt and decrypt operations are cached separately.
*/
const { plaintext, messageHeader } = await decrypt(cachingCMM, result)
/* Grab the encryption context so you can verify it. */
const { encryptionContext: decryptedContext } = messageHeader
/* Verify the encryption context.
* If you use an algorithm suite with signing,
* the Encryption SDK adds a name-value pair to the encryption context that contains the public key.
* Because the encryption context might contain additional key-value pairs,
* do not include a test that requires that all key-value pairs match.
* Instead, verify that the key-value pairs that you supplied to the `encrypt` function are included in the encryption context that the `decrypt` function returns.
*/
Object.entries(encryptionContext).forEach(([key, value]) => {
if (decryptedContext[key] !== value)
throw new Error('Encryption Context does not match expected values')
})
/* Return the values so the code can be tested. */
return { plaintext, result, cleartext, messageHeader }
}
```
------
#### [ Python ]
```
# Copyright 2017 Amazon.com, Inc. or its affiliates. All Rights Reserved.
#
# Licensed under the Apache License, Version 2.0 (the "License"). You
# may not use this file except in compliance with the License. A copy of
# the License is located at
#
# http://aws.amazon.com/apache2.0/
#
# or in the "license" file accompanying this file. This file is
# distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
# ANY KIND, either express or implied. See the License for the specific
# language governing permissions and limitations under the License.
"""Example of encryption with data key caching."""
import aws_encryption_sdk
from aws_encryption_sdk import CommitmentPolicy
def encrypt_with_caching(kms_key_arn, max_age_in_cache, cache_capacity):
"""Encrypts a string using an &KMS; key and data key caching.
:param str kms_key_arn: Amazon Resource Name (ARN) of the &KMS; key
:param float max_age_in_cache: Maximum time in seconds that a cached entry can be used
:param int cache_capacity: Maximum number of entries to retain in cache at once
"""
# Data to be encrypted
my_data = "My plaintext data"
# Security thresholds
# Max messages (or max bytes per) data key are optional
MAX_ENTRY_MESSAGES = 100
# Create an encryption context
encryption_context = {"purpose": "test"}
# Set up an encryption client with an explicit commitment policy. Note that if you do not explicitly choose a
# commitment policy, REQUIRE_ENCRYPT_REQUIRE_DECRYPT is used by default.
client = aws_encryption_sdk.EncryptionSDKClient(commitment_policy=CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT)
# Create a master key provider for the &KMS; key
key_provider = aws_encryption_sdk.StrictAwsKmsMasterKeyProvider(key_ids=[kms_key_arn])
# Create a local cache
cache = aws_encryption_sdk.LocalCryptoMaterialsCache(cache_capacity)
# Create a caching CMM
caching_cmm = aws_encryption_sdk.CachingCryptoMaterialsManager(
master_key_provider=key_provider,
cache=cache,
max_age=max_age_in_cache,
max_messages_encrypted=MAX_ENTRY_MESSAGES,
)
# When the call to encrypt data specifies a caching CMM,
# the encryption operation uses the data key cache specified
# in the caching CMM
encrypted_message, _header = client.encrypt(
source=my_data, materials_manager=caching_cmm, encryption_context=encryption_context
)
return encrypted_message
```
------
# Setting cache security thresholds
When you implement data key caching, you need to configure the security thresholds that the [caching CMM](data-caching-details.md#caching-cmm) enforces.
The security thresholds help you to limit how long each cached data key is used and how much data is protected under each data key. The caching CMM returns cached data keys only when the cache entry conforms to all of the security thresholds. If the cache entry exceeds any threshold, the entry is not used for the current operation and it is evicted from the cache as soon as possible. The first use of each data key (before caching) is exempt from these thresholds.
As a rule, use the minimum amount of caching that is required to meet your cost and performance goals.
The AWS Encryption SDK only caches data keys that are encrypted by using a [key derivation function](https://en.wikipedia.org/wiki/Key_derivation_function). Also, it establishes upper limits for some of the threshold values. These restrictions ensure that data keys are not reused beyond their cryptographic limits. However, because your plaintext data keys are cached (in memory, by default), try to minimize the time that the keys are saved . Also, try to limit the data that might be exposed if a key is compromised.
For examples of setting cache security thresholds, see [AWS Encryption SDK: How to Decide if Data Key Caching is Right for Your Application](https://aws.amazon.com/blogs/security/aws-encryption-sdk-how-to-decide-if-data-key-caching-is-right-for-your-application/) in the AWS Security Blog.
**Note**
The caching CMM enforces all of the following thresholds. If you do not specify an optional value, the caching CMM uses the default value.
To disable data key caching temporarily, the Java and Python implementations of the AWS Encryption SDK provide a *null cryptographic materials cache* (null cache). The null cache returns a miss for every `GET` request and does not respond to `PUT` requests. We recommend that you use the null cache instead of setting the [cache capacity](data-caching-details.md#simplecache) or security thresholds to 0. For more information, see the null cache in [Java](https://aws.github.io/aws-encryption-sdk-java/com/amazonaws/encryptionsdk/caching/NullCryptoMaterialsCache.html) and [Python](https://aws-encryption-sdk-python.readthedocs.io/en/latest/generated/aws_encryption_sdk.caches.null.html).
**Maximum age (required)**
Determines how long a cached entry can be used, beginning when it was added. This value is required. Enter a value greater than 0. The AWS Encryption SDK does not limit the maximum age value.
All language implementations of the AWS Encryption SDK define the maximum age in seconds, except for the AWS Encryption SDK for JavaScript, which uses milliseconds.
Use the shortest interval that still allows your application to benefit from the cache. You can use the maximum age threshold like a key rotation policy. Use it to limit reuse of data keys, minimize exposure of cryptographic materials, and evict data keys whose policies might have changed while they were cached.
**Maximum messages encrypted (optional)**
Specifies the maximum number of messages that a cached data key can encrypt. This value is optional. Enter a value between 1 and 2^32 messages. The default value is 2^32 messages.
Set the number of messages protected by each cached key to be large enough to get value from reuse, but small enough to limit the number of messages that might be exposed if a key is compromised.
**Maximum bytes encrypted (optional)**
Specifies the maximum number of bytes that a cached data key can encrypt. This value is optional. Enter a value between 0 and 2^63 - 1. The default value is 2^63 - 1. A value of 0 lets you use data key caching only when you are encrypting empty message strings.
The bytes in the current request are included when evaluating this threshold. If the bytes processed, plus current bytes, exceed the threshold, the cached data key is evicted from the cache, even though it might have been used on a smaller request.
# Data key caching details
Most applications can use the default implementation of data key caching without writing custom code. This section describes the default implementation and some details about options.
**Topics**
+ [How data key caching works](#how-caching-works)
+ [Creating a cryptographic materials cache](#simplecache)
+ [Creating a caching cryptographic materials manager](#caching-cmm)
+ [What is in a data key cache entry?](#cache-entries)
+ [Encryption context: How to select cache entries](#caching-encryption-context)
+ [Is my application using cached data keys?](#caching-effect)
## How data key caching works
When you use data key caching in a request to encrypt or decrypt data, the AWS Encryption SDK first searches the cache for a data key that matches the request. If it finds a valid match, it uses the cached data key to encrypt the data. Otherwise, it generates a new data key, just as it would without the cache.
Data key caching is not used for data of unknown size, such as streamed data. This allows the caching CMM to properly enforce the [maximum bytes threshold](thresholds.md). To avoid this behavior, add the message size to the encryption request.
In addition to a cache, data key caching uses a [caching cryptographic materials manager](#caching-cmm) (caching CMM). The caching CMM is a specialized [cryptographic materials manager (CMM)](concepts.md#crypt-materials-manager) that interacts with a [cache](#simplecache) and an underlying [CMM](concepts.md#crypt-materials-manager). (When you specify a [master key provider](concepts.md#master-key-provider) or keyring, the AWS Encryption SDK creates a default CMM for you.) The caching CMM caches the data keys that its underlying CMM returns. The caching CMM also enforces cache security thresholds that you set.
To prevent the wrong data key from being selected from the cache, all compatible caching CMMs require that the following properties of the cached cryptographic materials match the materials request.
+ [Algorithm suite](concepts.md#crypto-algorithm)
+ [Encryption context](#caching-encryption-context) (even when empty)
+ Partition name (a string that identifies the caching CMM)
+ (Decryption only) Encrypted data keys
**Note**
The AWS Encryption SDK caches data keys only when the [algorithm suite](concepts.md#crypto-algorithm) uses a [key derivation function](https://en.wikipedia.org/wiki/Key_derivation_function).
The following workflows show how a request to encrypt data is processed with and without data key caching. They show how the caching components that you create, including the cache and the caching CMM, are used in the process.
### Encrypt data without caching
To get encryption materials without caching:
1. An application asks the AWS Encryption SDK to encrypt data.
The request specifies a master key provider or keyring. The AWS Encryption SDK creates a default CMM that interacts with your master key provider or keyring.
1. The AWS Encryption SDK asks the CMM for encryption materials (get cryptographic materials).
1. The CMM asks its [keyring](concepts.md#keyring) (C and JavaScript) or [master key provider](concepts.md#master-key-provider) (Java and Python) for cryptographic materials. This might involve a call to a cryptographic service, such as AWS Key Management Service (AWS KMS). The CMM returns the encryption materials to the AWS Encryption SDK.
1. The AWS Encryption SDK uses the plaintext data key to encrypt the data. It stores the encrypted data and encrypted data keys in an [encrypted message](concepts.md#message), which it returns to the user.
![\[Encrypt data without caching\]](http://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/images/encrypt-workflow-no-cache.png)
### Encrypt data with caching
To get encryption materials with data key caching:
1. An application asks the AWS Encryption SDK to encrypt data.
The request specifies a [caching cryptographic materials manager (caching CMM)](#caching-cmm) that is associated with a underlying cryptographic materials manager (CMM). When you specify a master key provider or keyring, the AWS Encryption SDK creates a default CMM for you.
1. The SDK asks the specified caching CMM for encryption materials.
1. The caching CMM requests encryption materials from the cache.
1. If the cache finds a match, it updates the age and use values of the matched cache entry, and returns the cached encryption materials to the caching CMM.
If the cache entry conforms to its [security thresholds](thresholds.md), the caching CMM returns it to the SDK. Otherwise, it tells the cache to evict the entry and proceeds as though there was no match.
1. If the cache cannot find a valid match, the caching CMM asks its underlying CMM to generate a new data key.
The underlying CMM gets the cryptographic materials from its keyring (C and JavaScript) or master key provider (Java and Python). This might involve a call to a service, such as AWS Key Management Service. The underlying CMM returns the plaintext and encrypted copies of the data key to the caching CMM.
The caching CMM saves the new encryption materials in the cache.
1. The caching CMM returns the encryption materials to the AWS Encryption SDK.
1. The AWS Encryption SDK uses the plaintext data key to encrypt the data. It stores the encrypted data and encrypted data keys in an [encrypted message](concepts.md#message), which it returns to the user.
![\[Encrypt data with data key caching\]](http://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/images/encrypt-workflow-with-cache.png)
## Creating a cryptographic materials cache
The AWS Encryption SDK defines the requirements for a cryptographic materials cache used in data key caching. It also provides a local cache, which is a configurable, in-memory, [least recently used (LRU) cache](https://en.wikipedia.org/wiki/Cache_replacement_policies#Least_Recently_Used_.28LRU.29). To create an instance of the local cache, use the `LocalCryptoMaterialsCache` constructor in Java and Python, the getLocalCryptographicMaterialsCache function in JavaScript, or the `aws_cryptosdk_materials_cache_local_new` constructor in C.
The local cache includes logic for basic cache management, including adding, evicting, and matching cached entries, and maintaining the cache. You don't need to write any custom cache management logic. You can use the local cache as is, customize it, or substitute any compatible cache.
When you create a local cache, you set its *capacity*, that is, the maximum number of entries that the cache can hold. This setting helps you to design an efficient cache with limited data key reuse.
The AWS Encryption SDK for Java and the AWS Encryption SDK for Python also provide a *null cryptographic materials cache* (NullCryptoMaterialsCache). The NullCryptoMaterialsCache returns a miss for all `GET` operations and does not respond to `PUT` operations. You can use the NullCryptoMaterialsCache in testing or to temporarily disable caching in an application that includes caching code.
In the AWS Encryption SDK, each cryptographic materials cache is associated with a [caching cryptographic materials manager](#caching-cmm) (caching CMM). The caching CMM gets data keys from the cache, puts data keys in the cache, and enforces [security thresholds](thresholds.md) that you set. When you create a caching CMM, you specify the cache that it uses and the underlying CMM or master key provider that generates the data keys that it caches.
## Creating a caching cryptographic materials manager
To enable data key caching, you create a [cache](#simplecache) and a *caching cryptographic materials manager* (caching CMM). Then, in your requests to encrypt or decrypt data, you specify a caching CMM, instead of a standard [cryptographic materials manager (CMM)](concepts.md#crypt-materials-manager), or [master key provider](concepts.md#master-key-provider) or [keyring](concepts.md#keyring).
There are two types of CMMs. Both get data keys (and related cryptographic material), but in different ways, as follows:
+ A CMM is associated with a keyring (C or JavaScript) or a master key provider (Java and Python). When the SDK asks the CMM for encryption or decryption materials, the CMM gets the materials from its keyring or master key provider. In Java and Python, the CMM uses the master keys to generate, encrypt, or decrypt the data keys. In C and JavaScript, the keyring generates, encrypts, and returns the cryptographic materials.
+ A caching CMM is associated with one cache, such as a [local cache](#simplecache), and an underlying CMM. When the SDK asks the caching CMM for cryptographic materials, the caching CMM tries to get them from the cache. If it cannot find a match, the caching CMM asks its underlying CMM for the materials. Then, it caches the new cryptographic materials before returning them to the caller.
The caching CMM also enforces [security thresholds](thresholds.md) that you set for each cache entry. Because the security thresholds are set in and enforced by the caching CMM, you can use any compatible cache, even if the cache is not designed for sensitive material.
## What is in a data key cache entry?
Data key caching stores data keys and related cryptographic materials in a cache. Each entry includes the elements listed below. You might find this information useful when you're deciding whether to use the data key caching feature, and when you're setting security thresholds on a caching cryptographic materials manager (caching CMM).
**Cached Entries for Encryption Requests**
The entries that are added to a data key cache as a result of a encryption operation include the following elements:
+ Plaintext data key
+ Encrypted data keys (one or more)
+ [Encryption context](#caching-encryption-context)
+ Message signing key (if one is used)
+ [Algorithm suite](concepts.md#crypto-algorithm)
+ Metadata, including usage counters for enforcing security thresholds
**Cached Entries for Decryption Requests**
The entries that are added to a data key cache as a result of a decryption operation include the following elements:
+ Plaintext data key
+ Signature verification key (if one is used)
+ Metadata, including usage counters for enforcing security thresholds
## Encryption context: How to select cache entries
You can specify an encryption context in any request to encrypt data. However, the encryption context plays a special role in data key caching. It lets you create subgroups of data keys in your cache, even when the data keys originate from the same caching CMM.
An [encryption context](concepts.md#encryption-context) is a set of key-value pairs that contain arbitrary nonsecret data. During encryption, the encryption context is cryptographically bound to the encrypted data so that the same encryption context is required to decrypt the data. In the AWS Encryption SDK, the encryption context is stored in the [encrypted message](concepts.md#message) with the encrypted data and data keys.
When you use a data key cache, you can also use the encryption context to select particular cached data keys for your encryption operations. The encryption context is saved in the cache entry with the data key (it's part of the cache entry ID). Cached data keys are reused only when their encryption contexts match. If you want to reuse certain data keys for an encryption request, specify the same encryption context. If you want to avoid those data keys, specify a different encryption context.
The encryption context is always optional, but recommended. If you don't specify an encryption context in your request, an empty encryption context is included in the cache entry identifier and matched to each request.
## Is my application using cached data keys?
Data key caching is an optimization strategy that is very effective for certain applications and workloads. However, because it entails some risk, it's important to determine how effective it is likely to be for your situation, and then decide whether the benefits outweigh the risks.
Because data key caching reuses data keys, the most obvious effect is reducing the number of calls to generate new data keys. When data key caching is implemented, the AWS Encryption SDK calls the AWS KMS `GenerateDataKey` operation only to create the initial data key and when the cache misses. But, caching improves performance perceptibly only in applications that generate numerous data keys with the same characteristics, including the same encryption context and algorithm suite.
To determine whether your implementation of the AWS Encryption SDK is actually using data keys from the cache, try the following techniques.
+ In the logs of your master key infrastructure, check the frequency of calls to create new data keys. When data key caching is effective, the number of calls to create new keys should drop perceptibly. For example, if you are using a AWS KMS master key provider or keyring, search the CloudTrail logs for [GenerateDataKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html) calls.
+ Compare the [encrypted messages](concepts.md#message) that the AWS Encryption SDK returns in response to different encrypt requests. For example, if you are using the AWS Encryption SDK for Java, compare the [ParsedCiphertext](https://aws.github.io/aws-encryption-sdk-java/com/amazonaws/encryptionsdk/ParsedCiphertext.html) object from different encrypt calls. In the AWS Encryption SDK for JavaScript, compare the contents of the `encryptedDataKeys` property of the [MessageHeader](https://github.com/aws/aws-encryption-sdk-javascript/blob/master/modules/serialize/src/types.ts#L21). When data keys are reused, the encrypted data keys in the encrypted message are identical.
# Data key caching example
This example uses [data key caching](data-key-caching.md) with a [local cache](data-caching-details.md#simplecache) to speed up an application in which data generated by multiple devices is encrypted and stored in different Regions.
In this scenario, multiple data producers generate data, encrypt it, and write to a [Kinesis stream](https://aws.amazon.com/kinesis/streams/) in each Region. [AWS Lambda](https://aws.amazon.com/lambda/) functions (consumers) decrypt the streams and write plaintext data to a DynamoDB table in the Region. Data producers and consumers use the AWS Encryption SDK and an [AWS KMS master key provider](concepts.md#master-key-provider). To reduce calls to KMS, each producer and consumer has their own local cache.
You can find the source code for these examples in [Java and Python](sample-cache-example-code.md). The sample also includes a CloudFormation template that defines the resources for the samples.
![\[This diagram shows how data producers and consumers use the AWS KMS, Amazon Kinesis Data Streams, and Amazon DynamoDB.\]](http://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/images/simplecache-example.png)
## Local cache results
The following table shows that a local cache reduces the total calls to KMS (per second per Region) in this example to 1% of its original value.
**Producer requests**
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/sample-cache-example.html)
**Consumer requests**
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/sample-cache-example.html)
# Data key caching example code
This code sample creates a simple implementation of data key caching with a [local cache](data-caching-details.md#simplecache) in Java and Python. The code creates two instances of a local cache: one for [data producers](#caching-producer) that are encrypting data and another for [data consumers](#caching-consumer) (AWS Lambda functions) that are decrypting data. For details about the implementation of data key caching in each language, see the [Javadoc](https://aws.github.io/aws-encryption-sdk-java/) and [Python documentation](https://aws-encryption-sdk-python.readthedocs.io/en/latest/) for the AWS Encryption SDK.
Data key caching is available for all [programming languages](programming-languages.md) that the AWS Encryption SDK supports.
For complete and tested examples of using data key caching in the AWS Encryption SDK, see:
+ C/C\$1\$1: [caching\$1cmm.cpp](https://github.com/aws/aws-encryption-sdk-c/blob/master/examples/caching_cmm.cpp)
+ Java: [SimpleDataKeyCachingExample.java](https://github.com/aws/aws-encryption-sdk-java/blob/master/src/examples/java/com/amazonaws/crypto/examples/v2/SimpleDataKeyCachingExample.java)
+ JavaScript Browser: [caching\$1cmm.ts](https://github.com/aws/aws-encryption-sdk-javascript/blob/master/modules/example-browser/src/caching_cmm.ts)
+ JavaScript Node.js: [caching\$1cmm.ts](https://github.com/aws/aws-encryption-sdk-javascript/blob/master/modules/example-node/src/caching_cmm.ts)
+ Python: [data\$1key\$1caching\$1basic.py](https://github.com/aws/aws-encryption-sdk-python/blob/master/examples/src/legacy/data_key_caching_basic.py)
## Producer
The producer gets a map, converts it to JSON, uses the AWS Encryption SDK to encrypt it, and pushes the ciphertext record to a [Kinesis stream](https://aws.amazon.com/kinesis/streams/) in each AWS Region.
The code defines a [caching cryptographic materials manager](data-caching-details.md#caching-cmm) (caching CMM) and associates it with a [local cache](data-caching-details.md#simplecache) and an underlying [AWS KMS master key provider](concepts.md#master-key-provider). The caching CMM caches the data keys (and [related cryptographic materials](data-caching-details.md#cache-entries)) from the master key provider. It also interacts with the cache on behalf of the SDK and enforces security thresholds that you set.
Because the call to the encrypt method specifies a caching CMM, instead of a regular [cryptographic materials manager (CMM)](concepts.md#crypt-materials-manager) or master key provider, the encryption will use data key caching.
------
#### [ Java ]
The following example uses version 2.*x* of the AWS Encryption SDK for Java. Version 3.*x* of the AWS Encryption SDK for Java deprecates the data key caching CMM. With version 3.*x*, you can also use the [AWS KMS Hierarchical keyring](use-hierarchical-keyring.md), an alternative cryptographic materials caching solution.
```
/*
* Copyright 2017 Amazon.com, Inc. or its affiliates. All Rights Reserved.
*
* Licensed under the Apache License, Version 2.0 (the "License"). You may not use this file except
* in compliance with the License. A copy of the License is located at
*
* http://aws.amazon.com/apache2.0
*
* or in the "license" file accompanying this file. This file is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
* specific language governing permissions and limitations under the License.
*/
package com.amazonaws.crypto.examples.kinesisdatakeycaching;
import com.amazonaws.encryptionsdk.AwsCrypto;
import com.amazonaws.encryptionsdk.CommitmentPolicy;
import com.amazonaws.encryptionsdk.CryptoResult;
import com.amazonaws.encryptionsdk.MasterKeyProvider;
import com.amazonaws.encryptionsdk.caching.CachingCryptoMaterialsManager;
import com.amazonaws.encryptionsdk.caching.LocalCryptoMaterialsCache;
import com.amazonaws.encryptionsdk.kmssdkv2.KmsMasterKey;
import com.amazonaws.encryptionsdk.kmssdkv2.KmsMasterKeyProvider;
import com.amazonaws.encryptionsdk.multi.MultipleProviderFactory;
import com.amazonaws.util.json.Jackson;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
import java.util.UUID;
import java.util.concurrent.TimeUnit;
import software.amazon.awssdk.auth.credentials.AwsCredentialsProvider;
import software.amazon.awssdk.auth.credentials.DefaultCredentialsProvider;
import software.amazon.awssdk.core.SdkBytes;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.kinesis.KinesisClient;
import software.amazon.awssdk.services.kms.KmsClient;
/**
* Pushes data to Kinesis Streams in multiple Regions.
*/
public class MultiRegionRecordPusher {
private static final long MAX_ENTRY_AGE_MILLISECONDS = 300000;
private static final long MAX_ENTRY_USES = 100;
private static final int MAX_CACHE_ENTRIES = 100;
private final String streamName_;
private final ArrayList kinesisClients_;
private final CachingCryptoMaterialsManager cachingMaterialsManager_;
private final AwsCrypto crypto_;
/**
* Creates an instance of this object with Kinesis clients for all target Regions and a cached
* key provider containing KMS master keys in all target Regions.
*/
public MultiRegionRecordPusher(final Region[] regions, final String kmsAliasName,
final String streamName) {
streamName_ = streamName;
crypto_ = AwsCrypto.builder()
.withCommitmentPolicy(CommitmentPolicy.RequireEncryptRequireDecrypt)
.build();
kinesisClients_ = new ArrayList<>();
AwsCredentialsProvider credentialsProvider = DefaultCredentialsProvider.builder().build();
// Build KmsMasterKey and AmazonKinesisClient objects for each target region
List masterKeys = new ArrayList<>();
for (Region region : regions) {
kinesisClients_.add(KinesisClient.builder()
.credentialsProvider(credentialsProvider)
.region(region)
.build());
KmsMasterKey regionMasterKey = KmsMasterKeyProvider.builder()
.defaultRegion(region)
.builderSupplier(() -> KmsClient.builder().credentialsProvider(credentialsProvider))
.buildStrict(kmsAliasName)
.getMasterKey(kmsAliasName);
masterKeys.add(regionMasterKey);
}
// Collect KmsMasterKey objects into single provider and add cache
MasterKeyProvider masterKeyProvider = MultipleProviderFactory.buildMultiProvider(
KmsMasterKey.class,
masterKeys
);
cachingMaterialsManager_ = CachingCryptoMaterialsManager.newBuilder()
.withMasterKeyProvider(masterKeyProvider)
.withCache(new LocalCryptoMaterialsCache(MAX_CACHE_ENTRIES))
.withMaxAge(MAX_ENTRY_AGE_MILLISECONDS, TimeUnit.MILLISECONDS)
.withMessageUseLimit(MAX_ENTRY_USES)
.build();
}
/**
* JSON serializes and encrypts the received record data and pushes it to all target streams.
*/
public void putRecord(final Map data) {
String partitionKey = UUID.randomUUID().toString();
Map encryptionContext = new HashMap<>();
encryptionContext.put("stream", streamName_);
// JSON serialize data
String jsonData = Jackson.toJsonString(data);
// Encrypt data
CryptoResult result = crypto_.encryptData(
cachingMaterialsManager_,
jsonData.getBytes(),
encryptionContext
);
byte[] encryptedData = result.getResult();
// Put records to Kinesis stream in all Regions
for (KinesisClient regionalKinesisClient : kinesisClients_) {
regionalKinesisClient.putRecord(builder ->
builder.streamName(streamName_)
.data(SdkBytes.fromByteArray(encryptedData))
.partitionKey(partitionKey));
}
}
}
```
------
#### [ Python ]
```
"""
Copyright 2017 Amazon.com, Inc. or its affiliates. All Rights Reserved.
Licensed under the Apache License, Version 2.0 (the "License"). You may not use this file except
in compliance with the License. A copy of the License is located at
https://aws.amazon.com/apache-2-0/
or in the "license" file accompanying this file. This file is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
specific language governing permissions and limitations under the License.
"""
import json
import uuid
from aws_encryption_sdk import EncryptionSDKClient, StrictAwsKmsMasterKeyProvider, CachingCryptoMaterialsManager, LocalCryptoMaterialsCache, CommitmentPolicy
from aws_encryption_sdk.key_providers.kms import KMSMasterKey
import boto3
class MultiRegionRecordPusher(object):
"""Pushes data to Kinesis Streams in multiple Regions."""
CACHE_CAPACITY = 100
MAX_ENTRY_AGE_SECONDS = 300.0
MAX_ENTRY_MESSAGES_ENCRYPTED = 100
def __init__(self, regions, kms_alias_name, stream_name):
self._kinesis_clients = []
self._stream_name = stream_name
# Set up EncryptionSDKClient
_client = EncryptionSDKClient(CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT)
# Set up KMSMasterKeyProvider with cache
_key_provider = StrictAwsKmsMasterKeyProvider(kms_alias_name)
# Add MasterKey and Kinesis client for each Region
for region in regions:
self._kinesis_clients.append(boto3.client('kinesis', region_name=region))
regional_master_key = KMSMasterKey(
client=boto3.client('kms', region_name=region),
key_id=kms_alias_name
)
_key_provider.add_master_key_provider(regional_master_key)
cache = LocalCryptoMaterialsCache(capacity=self.CACHE_CAPACITY)
self._materials_manager = CachingCryptoMaterialsManager(
master_key_provider=_key_provider,
cache=cache,
max_age=self.MAX_ENTRY_AGE_SECONDS,
max_messages_encrypted=self.MAX_ENTRY_MESSAGES_ENCRYPTED
)
def put_record(self, record_data):
"""JSON serializes and encrypts the received record data and pushes it to all target streams.
:param dict record_data: Data to write to stream
"""
# Kinesis partition key to randomize write load across stream shards
partition_key = uuid.uuid4().hex
encryption_context = {'stream': self._stream_name}
# JSON serialize data
json_data = json.dumps(record_data)
# Encrypt data
encrypted_data, _header = _client.encrypt(
source=json_data,
materials_manager=self._materials_manager,
encryption_context=encryption_context
)
# Put records to Kinesis stream in all Regions
for client in self._kinesis_clients:
client.put_record(
StreamName=self._stream_name,
Data=encrypted_data,
PartitionKey=partition_key
)
```
------
## Consumer
The data consumer is an [AWS Lambda](https://aws.amazon.com/lambda/) function that is triggered by [Kinesis](https://aws.amazon.com/kinesis/) events. It decrypts and deserializes each record, and writes the plaintext record to an [Amazon DynamoDB](https://aws.amazon.com/dynamodb/) table in the same Region.
Like the producer code, the consumer code enables data key caching by using a caching cryptographic materials manager (caching CMM) in calls to the decrypt method.
The Java code builds a master key provider in *strict mode* with a specified AWS KMS key. Strict mode isn't required when decrypting, but it's a [best practice](best-practices.md#strict-discovery-mode). The Python code uses *discovery mode*, which lets the AWS Encryption SDK use any wrapping key that encrypted a data key to decrypt it.
------
#### [ Java ]
The following example uses version 2.*x* of the AWS Encryption SDK for Java. Version 3.*x* of the AWS Encryption SDK for Java deprecates the data key caching CMM. With version 3.*x*, you can also use the [AWS KMS Hierarchical keyring](use-hierarchical-keyring.md), an alternative cryptographic materials caching solution.
This code creates a master key provider for decrypting in strict mode. The AWS Encryption SDK can use only the AWS KMS keys you specify to decrypt your message.
```
/*
* Copyright 2017 Amazon.com, Inc. or its affiliates. All Rights Reserved.
*
* Licensed under the Apache License, Version 2.0 (the "License"). You may not use this file except
* in compliance with the License. A copy of the License is located at
*
* http://aws.amazon.com/apache2.0
*
* or in the "license" file accompanying this file. This file is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
* specific language governing permissions and limitations under the License.
*/
package com.amazonaws.crypto.examples.kinesisdatakeycaching;
import com.amazonaws.encryptionsdk.AwsCrypto;
import com.amazonaws.encryptionsdk.CommitmentPolicy;
import com.amazonaws.encryptionsdk.CryptoResult;
import com.amazonaws.encryptionsdk.caching.CachingCryptoMaterialsManager;
import com.amazonaws.encryptionsdk.caching.LocalCryptoMaterialsCache;
import com.amazonaws.encryptionsdk.kmssdkv2.KmsMasterKeyProvider;
import com.amazonaws.services.lambda.runtime.Context;
import com.amazonaws.services.lambda.runtime.events.KinesisEvent;
import com.amazonaws.services.lambda.runtime.events.KinesisEvent.KinesisEventRecord;
import com.amazonaws.util.BinaryUtils;
import java.io.UnsupportedEncodingException;
import java.nio.ByteBuffer;
import java.nio.charset.StandardCharsets;
import java.util.concurrent.TimeUnit;
import software.amazon.awssdk.enhanced.dynamodb.DynamoDbEnhancedClient;
import software.amazon.awssdk.enhanced.dynamodb.DynamoDbTable;
import software.amazon.awssdk.enhanced.dynamodb.TableSchema;
/**
* Decrypts all incoming Kinesis records and writes records to DynamoDB.
*/
public class LambdaDecryptAndWrite {
private static final long MAX_ENTRY_AGE_MILLISECONDS = 600000;
private static final int MAX_CACHE_ENTRIES = 100;
private final CachingCryptoMaterialsManager cachingMaterialsManager_;
private final AwsCrypto crypto_;
private final DynamoDbTable- table_;
/**
* Because the cache is used only for decryption, the code doesn't set the max bytes or max
* message security thresholds that are enforced only on on data keys used for encryption.
*/
public LambdaDecryptAndWrite() {
String kmsKeyArn = System.getenv("CMK_ARN");
cachingMaterialsManager_ = CachingCryptoMaterialsManager.newBuilder()
.withMasterKeyProvider(KmsMasterKeyProvider.builder().buildStrict(kmsKeyArn))
.withCache(new LocalCryptoMaterialsCache(MAX_CACHE_ENTRIES))
.withMaxAge(MAX_ENTRY_AGE_MILLISECONDS, TimeUnit.MILLISECONDS)
.build();
crypto_ = AwsCrypto.builder()
.withCommitmentPolicy(CommitmentPolicy.RequireEncryptRequireDecrypt)
.build();
String tableName = System.getenv("TABLE_NAME");
DynamoDbEnhancedClient dynamodb = DynamoDbEnhancedClient.builder().build();
table_ = dynamodb.table(tableName, TableSchema.fromClass(Item.class));
}
/**
* @param event
* @param context
*/
public void handleRequest(KinesisEvent event, Context context)
throws UnsupportedEncodingException {
for (KinesisEventRecord record : event.getRecords()) {
ByteBuffer ciphertextBuffer = record.getKinesis().getData();
byte[] ciphertext = BinaryUtils.copyAllBytesFrom(ciphertextBuffer);
// Decrypt and unpack record
CryptoResult plaintextResult = crypto_.decryptData(cachingMaterialsManager_,
ciphertext);
// Verify the encryption context value
String streamArn = record.getEventSourceARN();
String streamName = streamArn.substring(streamArn.indexOf("/") + 1);
if (!streamName.equals(plaintextResult.getEncryptionContext().get("stream"))) {
throw new IllegalStateException("Wrong Encryption Context!");
}
// Write record to DynamoDB
String jsonItem = new String(plaintextResult.getResult(), StandardCharsets.UTF_8);
System.out.println(jsonItem);
table_.putItem(Item.fromJSON(jsonItem));
}
}
private static class Item {
static Item fromJSON(String jsonText) {
// Parse JSON and create new Item
return new Item();
}
}
}
```
------
#### [ Python ]
This Python code decrypts with a master key provider in discovery mode. It lets the AWS Encryption SDK use any wrapping key that encrypted a data key to decrypt it. Strict mode, in which you specify the wrapping keys that can be used for decryption, is a [best practice](best-practices.md#strict-discovery-mode).
```
"""
Copyright 2017 Amazon.com, Inc. or its affiliates. All Rights Reserved.
Licensed under the Apache License, Version 2.0 (the "License"). You may not use this file except
in compliance with the License. A copy of the License is located at
https://aws.amazon.com/apache-2-0/
or in the "license" file accompanying this file. This file is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
specific language governing permissions and limitations under the License.
"""
import base64
import json
import logging
import os
from aws_encryption_sdk import EncryptionSDKClient, DiscoveryAwsKmsMasterKeyProvider, CachingCryptoMaterialsManager, LocalCryptoMaterialsCache, CommitmentPolicy
import boto3
_LOGGER = logging.getLogger(__name__)
_is_setup = False
CACHE_CAPACITY = 100
MAX_ENTRY_AGE_SECONDS = 600.0
def setup():
"""Sets up clients that should persist across Lambda invocations."""
global encryption_sdk_client
encryption_sdk_client = EncryptionSDKClient(CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT)
global materials_manager
key_provider = DiscoveryAwsKmsMasterKeyProvider()
cache = LocalCryptoMaterialsCache(capacity=CACHE_CAPACITY)
# Because the cache is used only for decryption, the code doesn't set
# the max bytes or max message security thresholds that are enforced
# only on on data keys used for encryption.
materials_manager = CachingCryptoMaterialsManager(
master_key_provider=key_provider,
cache=cache,
max_age=MAX_ENTRY_AGE_SECONDS
)
global table
table_name = os.environ.get('TABLE_NAME')
table = boto3.resource('dynamodb').Table(table_name)
global _is_setup
_is_setup = True
def lambda_handler(event, context):
"""Decrypts all incoming Kinesis records and writes records to DynamoDB."""
_LOGGER.debug('New event:')
_LOGGER.debug(event)
if not _is_setup:
setup()
with table.batch_writer() as batch:
for record in event.get('Records', []):
# Record data base64-encoded by Kinesis
ciphertext = base64.b64decode(record['kinesis']['data'])
# Decrypt and unpack record
plaintext, header = encryption_sdk_client.decrypt(
source=ciphertext,
materials_manager=materials_manager
)
item = json.loads(plaintext)
# Verify the encryption context value
stream_name = record['eventSourceARN'].split('/', 1)[1]
if stream_name != header.encryption_context['stream']:
raise ValueError('Wrong Encryption Context!')
# Write record to DynamoDB
batch.put_item(Item=item)
```
------
# Data key caching example: CloudFormation template
This CloudFormation template sets up all the necessary AWS resources to reproduce the [data key caching example](sample-cache-example.md).
------
#### [ JSON ]
```
{
"Parameters": {
"SourceCodeBucket": {
"Type": "String",
"Description": "S3 bucket containing Lambda source code zip files"
},
"PythonLambdaS3Key": {
"Type": "String",
"Description": "S3 key containing Python Lambda source code zip file"
},
"PythonLambdaObjectVersionId": {
"Type": "String",
"Description": "S3 version id for S3 key containing Python Lambda source code zip file"
},
"JavaLambdaS3Key": {
"Type": "String",
"Description": "S3 key containing Python Lambda source code zip file"
},
"JavaLambdaObjectVersionId": {
"Type": "String",
"Description": "S3 version id for S3 key containing Python Lambda source code zip file"
},
"KeyAliasSuffix": {
"Type": "String",
"Description": "Suffix to use for KMS key Alias (ie: alias/KeyAliasSuffix)"
},
"StreamName": {
"Type": "String",
"Description": "Name to use for Kinesis Stream"
}
},
"Resources": {
"InputStream": {
"Type": "AWS::Kinesis::Stream",
"Properties": {
"Name": {
"Ref": "StreamName"
},
"ShardCount": 2
}
},
"PythonLambdaOutputTable": {
"Type": "AWS::DynamoDB::Table",
"Properties": {
"AttributeDefinitions": [
{
"AttributeName": "id",
"AttributeType": "S"
}
],
"KeySchema": [
{
"AttributeName": "id",
"KeyType": "HASH"
}
],
"ProvisionedThroughput": {
"ReadCapacityUnits": 1,
"WriteCapacityUnits": 1
}
}
},
"PythonLambdaRole": {
"Type": "AWS::IAM::Role",
"Properties": {
"AssumeRolePolicyDocument": {
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "lambda.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
},
"ManagedPolicyArns": [
"arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole"
],
"Policies": [
{
"PolicyName": "PythonLambdaAccess",
"PolicyDocument": {
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"dynamodb:DescribeTable",
"dynamodb:BatchWriteItem"
],
"Resource": {
"Fn::Sub": "arn:aws:dynamodb:${AWS::Region}:${AWS::AccountId}:table/${PythonLambdaOutputTable}"
}
},
{
"Effect": "Allow",
"Action": [
"dynamodb:PutItem"
],
"Resource": {
"Fn::Sub": "arn:aws:dynamodb:${AWS::Region}:${AWS::AccountId}:table/${PythonLambdaOutputTable}*"
}
},
{
"Effect": "Allow",
"Action": [
"kinesis:GetRecords",
"kinesis:GetShardIterator",
"kinesis:DescribeStream",
"kinesis:ListStreams"
],
"Resource": {
"Fn::Sub": "arn:aws:kinesis:${AWS::Region}:${AWS::AccountId}:stream/${InputStream}"
}
}
]
}
}
]
}
},
"PythonLambdaFunction": {
"Type": "AWS::Lambda::Function",
"Properties": {
"Description": "Python consumer",
"Runtime": "python2.7",
"MemorySize": 512,
"Timeout": 90,
"Role": {
"Fn::GetAtt": [
"PythonLambdaRole",
"Arn"
]
},
"Handler": "aws_crypto_examples.kinesis_datakey_caching.consumer.lambda_handler",
"Code": {
"S3Bucket": {
"Ref": "SourceCodeBucket"
},
"S3Key": {
"Ref": "PythonLambdaS3Key"
},
"S3ObjectVersion": {
"Ref": "PythonLambdaObjectVersionId"
}
},
"Environment": {
"Variables": {
"TABLE_NAME": {
"Ref": "PythonLambdaOutputTable"
}
}
}
}
},
"PythonLambdaSourceMapping": {
"Type": "AWS::Lambda::EventSourceMapping",
"Properties": {
"BatchSize": 1,
"Enabled": true,
"EventSourceArn": {
"Fn::Sub": "arn:aws:kinesis:${AWS::Region}:${AWS::AccountId}:stream/${InputStream}"
},
"FunctionName": {
"Ref": "PythonLambdaFunction"
},
"StartingPosition": "TRIM_HORIZON"
}
},
"JavaLambdaOutputTable": {
"Type": "AWS::DynamoDB::Table",
"Properties": {
"AttributeDefinitions": [
{
"AttributeName": "id",
"AttributeType": "S"
}
],
"KeySchema": [
{
"AttributeName": "id",
"KeyType": "HASH"
}
],
"ProvisionedThroughput": {
"ReadCapacityUnits": 1,
"WriteCapacityUnits": 1
}
}
},
"JavaLambdaRole": {
"Type": "AWS::IAM::Role",
"Properties": {
"AssumeRolePolicyDocument": {
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "lambda.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
},
"ManagedPolicyArns": [
"arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole"
],
"Policies": [
{
"PolicyName": "JavaLambdaAccess",
"PolicyDocument": {
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"dynamodb:DescribeTable",
"dynamodb:BatchWriteItem"
],
"Resource": {
"Fn::Sub": "arn:aws:dynamodb:${AWS::Region}:${AWS::AccountId}:table/${JavaLambdaOutputTable}"
}
},
{
"Effect": "Allow",
"Action": [
"dynamodb:PutItem"
],
"Resource": {
"Fn::Sub": "arn:aws:dynamodb:${AWS::Region}:${AWS::AccountId}:table/${JavaLambdaOutputTable}*"
}
},
{
"Effect": "Allow",
"Action": [
"kinesis:GetRecords",
"kinesis:GetShardIterator",
"kinesis:DescribeStream",
"kinesis:ListStreams"
],
"Resource": {
"Fn::Sub": "arn:aws:kinesis:${AWS::Region}:${AWS::AccountId}:stream/${InputStream}"
}
}
]
}
}
]
}
},
"JavaLambdaFunction": {
"Type": "AWS::Lambda::Function",
"Properties": {
"Description": "Java consumer",
"Runtime": "java8",
"MemorySize": 512,
"Timeout": 90,
"Role": {
"Fn::GetAtt": [
"JavaLambdaRole",
"Arn"
]
},
"Handler": "com.amazonaws.crypto.examples.kinesisdatakeycaching.LambdaDecryptAndWrite::handleRequest",
"Code": {
"S3Bucket": {
"Ref": "SourceCodeBucket"
},
"S3Key": {
"Ref": "JavaLambdaS3Key"
},
"S3ObjectVersion": {
"Ref": "JavaLambdaObjectVersionId"
}
},
"Environment": {
"Variables": {
"TABLE_NAME": {
"Ref": "JavaLambdaOutputTable"
},
"CMK_ARN": {
"Fn::GetAtt": [
"RegionKinesisCMK",
"Arn"
]
}
}
}
}
},
"JavaLambdaSourceMapping": {
"Type": "AWS::Lambda::EventSourceMapping",
"Properties": {
"BatchSize": 1,
"Enabled": true,
"EventSourceArn": {
"Fn::Sub": "arn:aws:kinesis:${AWS::Region}:${AWS::AccountId}:stream/${InputStream}"
},
"FunctionName": {
"Ref": "JavaLambdaFunction"
},
"StartingPosition": "TRIM_HORIZON"
}
},
"RegionKinesisCMK": {
"Type": "AWS::KMS::Key",
"Properties": {
"Description": "Used to encrypt data passing through Kinesis Stream in this region",
"Enabled": true,
"KeyPolicy": {
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": {
"Fn::Sub": "arn:aws:iam::${AWS::AccountId}:root"
}
},
"Action": [
"kms:Encrypt",
"kms:GenerateDataKey",
"kms:CreateAlias",
"kms:DeleteAlias",
"kms:DescribeKey",
"kms:DisableKey",
"kms:EnableKey",
"kms:PutKeyPolicy",
"kms:ScheduleKeyDeletion",
"kms:UpdateAlias",
"kms:UpdateKeyDescription"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Principal": {
"AWS": [
{
"Fn::GetAtt": [
"PythonLambdaRole",
"Arn"
]
},
{
"Fn::GetAtt": [
"JavaLambdaRole",
"Arn"
]
}
]
},
"Action": "kms:Decrypt",
"Resource": "*"
}
]
}
}
},
"RegionKinesisCMKAlias": {
"Type": "AWS::KMS::Alias",
"Properties": {
"AliasName": {
"Fn::Sub": "alias/${KeyAliasSuffix}"
},
"TargetKeyId": {
"Ref": "RegionKinesisCMK"
}
}
}
}
}
```
------
#### [ YAML ]
```
Parameters:
SourceCodeBucket:
Type: String
Description: S3 bucket containing Lambda source code zip files
PythonLambdaS3Key:
Type: String
Description: S3 key containing Python Lambda source code zip file
PythonLambdaObjectVersionId:
Type: String
Description: S3 version id for S3 key containing Python Lambda source code zip file
JavaLambdaS3Key:
Type: String
Description: S3 key containing Python Lambda source code zip file
JavaLambdaObjectVersionId:
Type: String
Description: S3 version id for S3 key containing Python Lambda source code zip file
KeyAliasSuffix:
Type: String
Description: 'Suffix to use for KMS CMK Alias (ie: alias/)'
StreamName:
Type: String
Description: Name to use for Kinesis Stream
Resources:
InputStream:
Type: AWS::Kinesis::Stream
Properties:
Name: !Ref StreamName
ShardCount: 2
PythonLambdaOutputTable:
Type: AWS::DynamoDB::Table
Properties:
AttributeDefinitions:
-
AttributeName: id
AttributeType: S
KeySchema:
-
AttributeName: id
KeyType: HASH
ProvisionedThroughput:
ReadCapacityUnits: 1
WriteCapacityUnits: 1
PythonLambdaRole:
Type: AWS::IAM::Role
Properties:
AssumeRolePolicyDocument:
Version: 2012-10-17
Statement:
-
Effect: Allow
Principal:
Service: lambda.amazonaws.com
Action: sts:AssumeRole
ManagedPolicyArns:
- arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole
Policies:
-
PolicyName: PythonLambdaAccess
PolicyDocument:
Version: 2012-10-17
Statement:
-
Effect: Allow
Action:
- dynamodb:DescribeTable
- dynamodb:BatchWriteItem
Resource: !Sub arn:aws:dynamodb:${AWS::Region}:${AWS::AccountId}:table/${PythonLambdaOutputTable}
-
Effect: Allow
Action:
- dynamodb:PutItem
Resource: !Sub arn:aws:dynamodb:${AWS::Region}:${AWS::AccountId}:table/${PythonLambdaOutputTable}*
-
Effect: Allow
Action:
- kinesis:GetRecords
- kinesis:GetShardIterator
- kinesis:DescribeStream
- kinesis:ListStreams
Resource: !Sub arn:aws:kinesis:${AWS::Region}:${AWS::AccountId}:stream/${InputStream}
PythonLambdaFunction:
Type: AWS::Lambda::Function
Properties:
Description: Python consumer
Runtime: python2.7
MemorySize: 512
Timeout: 90
Role: !GetAtt PythonLambdaRole.Arn
Handler: aws_crypto_examples.kinesis_datakey_caching.consumer.lambda_handler
Code:
S3Bucket: !Ref SourceCodeBucket
S3Key: !Ref PythonLambdaS3Key
S3ObjectVersion: !Ref PythonLambdaObjectVersionId
Environment:
Variables:
TABLE_NAME: !Ref PythonLambdaOutputTable
PythonLambdaSourceMapping:
Type: AWS::Lambda::EventSourceMapping
Properties:
BatchSize: 1
Enabled: true
EventSourceArn: !Sub arn:aws:kinesis:${AWS::Region}:${AWS::AccountId}:stream/${InputStream}
FunctionName: !Ref PythonLambdaFunction
StartingPosition: TRIM_HORIZON
JavaLambdaOutputTable:
Type: AWS::DynamoDB::Table
Properties:
AttributeDefinitions:
-
AttributeName: id
AttributeType: S
KeySchema:
-
AttributeName: id
KeyType: HASH
ProvisionedThroughput:
ReadCapacityUnits: 1
WriteCapacityUnits: 1
JavaLambdaRole:
Type: AWS::IAM::Role
Properties:
AssumeRolePolicyDocument:
Version: 2012-10-17
Statement:
-
Effect: Allow
Principal:
Service: lambda.amazonaws.com
Action: sts:AssumeRole
ManagedPolicyArns:
- arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole
Policies:
-
PolicyName: JavaLambdaAccess
PolicyDocument:
Version: 2012-10-17
Statement:
-
Effect: Allow
Action:
- dynamodb:DescribeTable
- dynamodb:BatchWriteItem
Resource: !Sub arn:aws:dynamodb:${AWS::Region}:${AWS::AccountId}:table/${JavaLambdaOutputTable}
-
Effect: Allow
Action:
- dynamodb:PutItem
Resource: !Sub arn:aws:dynamodb:${AWS::Region}:${AWS::AccountId}:table/${JavaLambdaOutputTable}*
-
Effect: Allow
Action:
- kinesis:GetRecords
- kinesis:GetShardIterator
- kinesis:DescribeStream
- kinesis:ListStreams
Resource: !Sub arn:aws:kinesis:${AWS::Region}:${AWS::AccountId}:stream/${InputStream}
JavaLambdaFunction:
Type: AWS::Lambda::Function
Properties:
Description: Java consumer
Runtime: java8
MemorySize: 512
Timeout: 90
Role: !GetAtt JavaLambdaRole.Arn
Handler: com.amazonaws.crypto.examples.kinesisdatakeycaching.LambdaDecryptAndWrite::handleRequest
Code:
S3Bucket: !Ref SourceCodeBucket
S3Key: !Ref JavaLambdaS3Key
S3ObjectVersion: !Ref JavaLambdaObjectVersionId
Environment:
Variables:
TABLE_NAME: !Ref JavaLambdaOutputTable
CMK_ARN: !GetAtt RegionKinesisCMK.Arn
JavaLambdaSourceMapping:
Type: AWS::Lambda::EventSourceMapping
Properties:
BatchSize: 1
Enabled: true
EventSourceArn: !Sub arn:aws:kinesis:${AWS::Region}:${AWS::AccountId}:stream/${InputStream}
FunctionName: !Ref JavaLambdaFunction
StartingPosition: TRIM_HORIZON
RegionKinesisCMK:
Type: AWS::KMS::Key
Properties:
Description: Used to encrypt data passing through Kinesis Stream in this region
Enabled: true
KeyPolicy:
Version: 2012-10-17
Statement:
-
Effect: Allow
Principal:
AWS: !Sub arn:aws:iam::${AWS::AccountId}:root
Action:
# Data plane actions
- kms:Encrypt
- kms:GenerateDataKey
# Control plane actions
- kms:CreateAlias
- kms:DeleteAlias
- kms:DescribeKey
- kms:DisableKey
- kms:EnableKey
- kms:PutKeyPolicy
- kms:ScheduleKeyDeletion
- kms:UpdateAlias
- kms:UpdateKeyDescription
Resource: '*'
-
Effect: Allow
Principal:
AWS:
- !GetAtt PythonLambdaRole.Arn
- !GetAtt JavaLambdaRole.Arn
Action: kms:Decrypt
Resource: '*'
RegionKinesisCMKAlias:
Type: AWS::KMS::Alias
Properties:
AliasName: !Sub alias/${KeyAliasSuffix}
TargetKeyId: !Ref RegionKinesisCMK
```
------