more spec

changes/2024-TBD_cache-across-hierarchy-keyrings/change.md

@@ -50,9 +50,9 @@ in this document are to be interpreted as described in
 The Hierarchy Keyring,
 and it's component the (Branch) Keystore,
 allow MPL Consumers to reduce their KMS Call volume
-by persiting KMS protected cryptographic materials into
+by persisting KMS protected cryptographic materials into
 an avabile medium
-(currently, only a DynamoDB table is avabile as persitance medium).
+(currently, only a DynamoDB table is avabile as persistence medium).
 
 We call these cryptographic materials Branch Keys.
 
@@ -81,16 +81,16 @@ However,
 the Hierarchy Keyring,
 and it's Keystore,
 have a runtime cost,
-exceting memory pressure
+exerting memory pressure
 and, without manual optimization,
 requiring at least 2 TLS handshakes
 when first serving a request
 (TLS to KMS & TLS to DDB).
 
 Additionally,
 the local Cryptographic Materials Cache
-excerts some runtime cost,
-particualry in a multi-threaded enviorment,
+exerts some runtime cost,
+particularly in a multi-threaded environment,
 when a background worker thread MAY be refreshing
 or pruning entries of the cache.
 
@@ -109,18 +109,18 @@ in these conditions,
 The objective, with these changes,
 is to make the Hierarchy Keyring
 "Easy to Use" in a multiple KMS Relationship
-enviorment.
+environment.
 
-To facilitate 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 intialized CMC
+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 Mutliple KMS Relationship MPL Consumers,
+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.
@@ -134,7 +134,74 @@ only the common cache.
 Cache misses will populate the cache via
 the Hierarchy Keyring that requested the material.
 
-Again, cache entries MUST ONLY be
+However, Cache Entries MUST 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
+describe the KMS Relationship,
+as well as the Logical Key Store Name,
+Branch Key ID,
+and Branch Key Name.
+
+The KeyStore constructor takes an optional [ID](../../framework/branch-key-store.md#keystore-id)
+parameter at construction.
+
+We can use this [ID](../../framework/branch-key-store.md#keystore-id)
+to label the KMS Relationship of a particular KeyStore instance.
+
+MPL Consumers who want to garbage collect KeyStore instances,
+but still retain the ability to serve cached results,
+MAY then set this [ID](../../framework/branch-key-store.md#keystore-id)
+intelligently.
+
+For example, imagine we have `N` KMS Relationships,
+one of which is `X`,
+which are used when retrieving Branch Keys, `n'`,
+one of which is `x'`.
+
+A common Cryptographic Materials Cache is established
+across all `N` Hierarchical Keyrings used to serve `n'`.
+
+But the Keyrings are routinely garbage collected,
+only the common cache remains "in scope" indefinitely.
+
+Whenever `x'` is needed,
+a new KMS Client is created that respects relationship `X`,
+which is then used to create KeyStore Identified as `X`,
+and the KeyStore is used to create a Hierarchical Keyring
+that uses the common Cache.
+
+All entries in this common Cache from that hierarchal Keyring
+MUST have a cache identifier that uniquely represents `X`.
+
+When the Hierarchical Keyring for `X` gets garbage collected,
+the cache entries MAY remain.
+
+But to retrieve an entry,
+the MPL Consumer MUST recreate
+
+> a KMS Client is created that respects relationship `X`,
+> which is then used to create KeyStore Identified as `X`,
+> and the KeyStore is used to create a Hierarchical Keyring
+> that uses the common Cache.
+
+If the Cache Entry is still valid
+(the TTL has not expired),
+it can be served.
+
+If not, the recreated Hierarchy Keyring
+is used to refresh it.
+
+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.
 
 ## Out of Scope
 
@@ -151,8 +218,8 @@ 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 Hierarhcy Keyring would instead take a constructed a Cache as
-an arguement during initialization.
+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,
@@ -164,16 +231,13 @@ By KMS Relationship, we mean any or all of the following:
 - 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
 
-The changes proposed (and comitted to) here
-do not include such a Cache refactoring,
-as that would not address the stated goal
-of allowing one Keystore to work across multiple
-KMS ARNs.
-
 ## Operational Implications
 
 TODO
 
 ## Reference-level Explanation
 
 TODO
+
+<!--  LocalWords:  KeyStores KeyStore's TODO Keystores
+ -->