Macros | |
| #define | AWS_CRYPTOSDK_CACHE_MAX_LIMIT_MESSAGES ((uint64_t)1 << 32) |
Functions | |
| struct aws_cryptosdk_materials_cache * | aws_cryptosdk_materials_cache_local_new (struct aws_allocator *alloc, size_t capacity) |
| size_t | aws_cryptosdk_materials_cache_entry_count (const struct aws_cryptosdk_materials_cache *cache) |
| void | aws_cryptosdk_materials_cache_clear (struct aws_cryptosdk_materials_cache *cache) |
| struct aws_cryptosdk_materials_cache * | aws_cryptosdk_materials_cache_retain (struct aws_cryptosdk_materials_cache *materials_cache) |
| void | aws_cryptosdk_materials_cache_release (struct aws_cryptosdk_materials_cache *materials_cache) |
| struct aws_cryptosdk_cmm * | aws_cryptosdk_caching_cmm_new_from_cmm (struct aws_allocator *alloc, struct aws_cryptosdk_materials_cache *materials_cache, struct aws_cryptosdk_cmm *upstream, const struct aws_byte_buf *partition_id, uint64_t cache_limit_ttl, enum aws_timestamp_unit cache_limit_ttl_units) |
| struct aws_cryptosdk_cmm * | aws_cryptosdk_caching_cmm_new_from_keyring (struct aws_allocator *alloc, struct aws_cryptosdk_materials_cache *materials_cache, struct aws_cryptosdk_keyring *keyring, const struct aws_byte_buf *partition_id, uint64_t cache_limit_ttl, enum aws_timestamp_unit cache_limit_ttl_units) |
| int | aws_cryptosdk_caching_cmm_set_ttl (struct aws_cryptosdk_cmm *cmm, uint64_t ttl, enum aws_timestamp_unit ttl_units) |
| int | aws_cryptosdk_caching_cmm_set_limit_bytes (struct aws_cryptosdk_cmm *cmm, uint64_t limit_bytes) |
| int | aws_cryptosdk_caching_cmm_set_limit_messages (struct aws_cryptosdk_cmm *cmm, uint64_t limit_messages) |
Detailed Description
The caching CMM caches the results of encryption and decryption operations to reduce the number of calls made to backing keyrings (e.g. KMS).
To use the caching API, construct a local cache (using aws_cryptosdk_materials_cache_local_new) and pass it to the constructor of a caching cmm (aws_cryptosdk_caching_cmm_new), along with a delegate CMM that generates the encryption and decryption materials that are cached.
When constructing a caching CMM, you are required to set a time-to-live (TTL) for data keys in the cache. We also recommend setting one of the two additional security thresholds using aws_cryptosdk_caching_cmm_set_limit_bytes or aws_cryptosdk_caching_cmm_set_limit_messages to ensure that data keys expire and are refreshed periodically.
As with CMMs and keyrings, the local cache is reference-counted. In simple use cases where there is only one local cache and one CMM, you can immediately call aws_cryptosdk_materials_cache_release on the local cache after constructing the CMM.
Multiple caching CMMs can share the same local cache, but by default will not use each other's entries. (They share the entry count limit, but otherwise are partitioned from each other.) This is to avoid unexpected behavior in case the cache-miss delegate CMMs are different. If you want two caching CMMs to share their entries, pass the same partition ID to both calls to aws_cryptosdk_caching_cmm_new .
Macro Definition Documentation
◆ AWS_CRYPTOSDK_CACHE_MAX_LIMIT_MESSAGES
| #define AWS_CRYPTOSDK_CACHE_MAX_LIMIT_MESSAGES ((uint64_t)1 << 32) |
Function Documentation
◆ aws_cryptosdk_caching_cmm_new_from_cmm()
| struct aws_cryptosdk_cmm * aws_cryptosdk_caching_cmm_new_from_cmm | ( | struct aws_allocator * | alloc, |
| struct aws_cryptosdk_materials_cache * | materials_cache, | ||
| struct aws_cryptosdk_cmm * | upstream, | ||
| const struct aws_byte_buf * | partition_id, | ||
| uint64_t | cache_limit_ttl, | ||
| enum aws_timestamp_unit | cache_limit_ttl_units ) |
Creates a new instance of the caching crypto materials manager. This CMM will intercept requests for encrypt and decrypt materials, and forward them to the provided materials cache.
If multiple caching CMMs are attached to the same materials_cache, they will share entries if and only if the partition_id parameter is set to the same string. Unless you need to use this feature, we recommend passing NULL, in which case the caching CMM will internally generate a random partition ID to ensure it does not collide with any other CMM.
Parameters:
- Parameters
-
alloc The allocator to use for the caching CMM itself (not for cache entries, however) materials_cache The backing cache upstream The upstream CMM to query on a cache miss partition_id The partition ID to use to avoid collisions with other CMMs. This string need not remain valid once this function returns. If NULL, a random partition ID will be generated and used. cache_limit_ttl The amount of time that a data key can be used for. cache_limit_ttl_units The units of cache_limit_ttl. Allowable values are defined in aws/common/clock.h
◆ aws_cryptosdk_caching_cmm_new_from_keyring()
| struct aws_cryptosdk_cmm * aws_cryptosdk_caching_cmm_new_from_keyring | ( | struct aws_allocator * | alloc, |
| struct aws_cryptosdk_materials_cache * | materials_cache, | ||
| struct aws_cryptosdk_keyring * | keyring, | ||
| const struct aws_byte_buf * | partition_id, | ||
| uint64_t | cache_limit_ttl, | ||
| enum aws_timestamp_unit | cache_limit_ttl_units ) |
Creates a new instance of the caching crypto materials manager. This CMM will intercept requests for encrypt and decrypt materials, and forward them to the provided materials cache.
If multiple caching CMMs are attached to the same materials_cache, they will share entries if and only if the partition_id parameter is set to the same string. Unless you need to use this feature, we recommend passing NULL, in which case the caching CMM will internally generate a random partition ID to ensure it does not collide with any other CMM.
Parameters:
- Parameters
-
alloc The allocator to use for the caching CMM itself (not for cache entries, however) materials_cache The backing cache keyring The keyring that will encrypt or decrypt data keys on a cache miss. This function uses a default CMM that is configured with the provided keyring as the upstream CMM. partition_id The partition ID to use to avoid collisions with other CMMs. This string need not remain valid once this function returns. If NULL, a random partition ID will be generated and used. cache_limit_ttl The amount of time that a data key can be used for. cache_limit_ttl_units The units of cache_limit_ttl. Allowable values are defined in aws/common/clock.h
◆ aws_cryptosdk_caching_cmm_set_limit_bytes()
| int aws_cryptosdk_caching_cmm_set_limit_bytes | ( | struct aws_cryptosdk_cmm * | cmm, |
| uint64_t | limit_bytes ) |
Configures the maximum number of bytes that may be encrypted by a single data key. This value has a maximum of 2^63 - 1 (i.e., INT64_MAX, not UINT64_MAX)
◆ aws_cryptosdk_caching_cmm_set_limit_messages()
| int aws_cryptosdk_caching_cmm_set_limit_messages | ( | struct aws_cryptosdk_cmm * | cmm, |
| uint64_t | limit_messages ) |
Configures the maximum number of messages that may be encrypted by a single data key. This value cannot be zero and has a maximum of 2^32 (i.e., AWS_CRYPTOSDK_CACHE_MAX_LIMIT_MESSAGES)
◆ aws_cryptosdk_caching_cmm_set_ttl()
| int aws_cryptosdk_caching_cmm_set_ttl | ( | struct aws_cryptosdk_cmm * | cmm, |
| uint64_t | ttl, | ||
| enum aws_timestamp_unit | ttl_units ) |
Configures the amount of time that a data key can be used for. This value must be greater than zero.
◆ aws_cryptosdk_materials_cache_clear()
| void aws_cryptosdk_materials_cache_clear | ( | struct aws_cryptosdk_materials_cache * | cache | ) |
◆ aws_cryptosdk_materials_cache_entry_count()
| size_t aws_cryptosdk_materials_cache_entry_count | ( | const struct aws_cryptosdk_materials_cache * | cache | ) |
◆ aws_cryptosdk_materials_cache_local_new()
| struct aws_cryptosdk_materials_cache * aws_cryptosdk_materials_cache_local_new | ( | struct aws_allocator * | alloc, |
| size_t | capacity ) |
Creates a new instance of the built-in local materials cache. This cache is thread safe, and uses a simple LRU policy (with capacity shared between encrypt and decrypt) to evict entries.
◆ aws_cryptosdk_materials_cache_release()
| void aws_cryptosdk_materials_cache_release | ( | struct aws_cryptosdk_materials_cache * | materials_cache | ) |
◆ aws_cryptosdk_materials_cache_retain()
Generated by
1.13.2