diff --git a/changes/2024-TBD_cache-across-hierarchy-keyrings/change.md b/changes/2024-TBD_cache-across-hierarchy-keyrings/change.md index 46cc875e..d3dd0239 100644 --- a/changes/2024-TBD_cache-across-hierarchy-keyrings/change.md +++ b/changes/2024-TBD_cache-across-hierarchy-keyrings/change.md @@ -37,6 +37,13 @@ to manage cryptographic materials. An "MPL Consumer" MAY be using an AWS Crypto Tools product, such as the AWS Encryption SDK or AWS Database Encryption SDK. +By "KMS Relationship", we mean any or all of the following: + +- KMS Configuration +- Credentials used when creating the KMS Client, and thus used when calling KMS +- Other properties of the KMS Client, such as the region, or request headers + + ### Conventions used in this document The key words @@ -47,6 +54,32 @@ in this document are to be interpreted as described in ## Summary +To improve the MPL Consumer data key caching expierence, +when using the Hierarchical Keyring, +we need to allow caching across KeyStores/KMS Clients/KMS Keys. + +To facilitate Caching across KeyStores/KMS Clients/KMS Keys, +we MUST break the Cryptographic Materials Cache (CMC) +out of the Hierarchy Keyring. + +By allowing MPL Consumers to provide an already initialized CMC +to the Hierarchy Keyring at construction, +the CMC MAY cache Branch Keys protected by different +KMS Relationships. + +This simplifies Multiple KMS Relationship MPL Consumers, +as they do not need to stand up LRU Cache of Hierarchy Keyrings. + +Instead, they may maintain one CMC. +They still create a Hierarchy Keyring instance per KMS Relationship, +and they MUST use the correct Keyring to retrieve material +from the Cache. + +But they need not maintain many Keyrings; +only the common cache. + +## Motivation + The Hierarchy Keyring, and it's component the (Branch) Keystore, allow MPL Consumers to reduce their KMS Call volume @@ -111,42 +144,23 @@ is to make the Hierarchy Keyring "Easy to Use" in a multiple KMS Relationship environment. -To facilitate Caching across KeyStores/KMS Clients/KMS Keys, -we MUST break the Cryptographic Materials Cache (CMC) -out of the Hierarchy Keyring. - -By allowing MPL Consumers to provide an already initialized CMC -to the Hierarchy Keyring at construction, -the CMC MAY cache Branch Keys protected by different -KMS Relationships. +## Relating Cache Entries (Branch Keys) to KMS Relationships -This simplifies Multiple KMS Relationship MPL Consumers, -as they do not need to stand up LRU Cache of Hierarchy Keyrings. - -Instead, they may maintain one CMC. -They still create a Hierarchy Keyring instance per KMS Relationship, -and they MUST use the correct Keyring to retrieve material -from the Cache. - -But they need not maintain many Keyrings; -only the common cache. - -Cache misses will populate the cache via -the Hierarchy Keyring that requested the material. - -However, Cache Entries MUST only be served IF +For some MPL Consumers, +Cache Entries SHOULD only be served IF the request is being served under the same KMS Relationship, which is the most secure condition, as it prevents a Confused Deputy scenario (detailed in **Confused Deputy 1**). To facilitate this, -the Cache Entry Identifier MUST +the Cache Entry Identifier SHOULD describe the KMS Relationship, as well as the Logical Key Store Name, Branch Key ID, and Branch Key Name. +We can use exsisting features to accomplish this; The KeyStore constructor takes an optional [ID](../../framework/branch-key-store.md#keystore-id) parameter at construction. @@ -182,7 +196,7 @@ When the Hierarchical Keyring for `X` gets garbage collected, the cache entries MAY remain. But to retrieve an entry, -the MPL Consumer MUST recreate +the MPL Consumer SHOULD recreate > a KMS Client is created that respects relationship `X`, > which is then used to create KeyStore Identified as `X`, @@ -191,46 +205,27 @@ the MPL Consumer MUST recreate If the Cache Entry is still valid (the TTL has not expired), -it can be served. +it can be served without any KMS or DDB requests. If not, the recreated Hierarchy Keyring is used to refresh it. +### Potential Helper Function: Hierarchy Keyring For KMS Relationship + To push MPL Consumers in the correct direction, AWS Crypto Tools could write a helper method, that creates KeyStores with KMS Clients of a particular KMS Relationship, and sets the KeyStore's ID deterministically -on on the properties of the KMS Relationship. +on the properties of the KMS Relationship. -## Out of Scope - -TODO +## A Looser Cache Entries (Branch Keys) Restriction -## Motivation +Some MPL Consumers MAY not need such +## Out of Scope TODO -### Hierarchy Keyring Caching - -Currently, the Hierarchy Keyring creates its own cache. - -To facilitate Caching performance across Keystores/KMS Clients/KMS Keys, -we could (optionally) break the Cache out of the Hierarchy Keyring. - -The Hierarchy\* Keyring would instead take a constructed a Cache as -an argument during initialization. - -When writing to the Cache, -the Hierarchy Keyring would include the Keystore's ID, -which, ideally, uniquely identifies its KMS relationship. - -By KMS Relationship, we mean any or all of the following: - -- KMS Configuration -- Credentials used when creating the KMS Client, and thus used when calling KMS -- Other properties of the KMS Client, such as the region, or request headers - ## Operational Implications TODO