feat: Updating the CMC specification (#60)

Moving some of the interface
from the local CMC to the CMC Interface.

Using the CMC requires a consistent interface.
Currently the Caching CMM has an interface
that relies on the Local CMC.
This means that if a CMC was created according
to the specification it would not function correctly.

Author: seebees

framework/cryptographic-materials-cache.md

@@ -9,6 +9,8 @@
 
 ### Changelog
 
+- 0.4.0
+  - Updating the interface. Moving elements from the Local CMC to the interface.
 - 0.3.0
   - [Return Nothing from Put Cache Entry in Cryptographic Materials Cache](../changes/2020-07-20_put-cache-entry-returns-nothing/change.md)
 - 0.2.0
@@ -42,19 +44,25 @@ in this document are to be interpreted as described in [RFC 2119](https://tools.
 
 ### Cache Identifier
 
-The cache identifier used to uniquely identify a single cache entry in the cryptographic materials cache.
+The cache identifier used to uniquely identify a single cache entry
+in the cryptographic materials cache.
 
 ### Cache Entry
 
-A cache entry represents an entry in the cryptographic materials cache.
-A cache entry contains the cryptographic materials, [encryption](structures.md#encryption-materials) or [decryption](structures.md#decryption-materials)
-materials to be cached along with other metadata.
-Some implementations of the CMC have the following metadata:
+A cache entry represents an entry in the cryptographic materials cache
+and MUST have the following information.
 
+- [Materials](#materials)
 - [Creation Time](#creation-time)
 - [Expiry Time](#expiry-time)
 - [Usage Metadata](#usage-metadata)
 
+#### Materials
+
+The cryptographic materials,
+[encryption](structures.md#encryption-materials) or [decryption](structuresmd#decryption-materials)
+materials to be cached along with other metadata.
+
 #### Creation Time
 
 Timestamp when the cache entry was created.
@@ -70,13 +78,32 @@ The usage metadata is of the following two types:
 - [Messages Usage](#message-usage)
 - [Bytes Usage](#bytes-usage)
 
+Updating usage metadata SHOULD be atomic.
+
 ##### Message Usage
 
-The number of messages encrypted by the [encryption](structures.md#encryption-materials) materials cached in this cache entry.
+The number of messages encrypted
+by the [encryption materials](structures.md#encryption-materials)
+cached in this cache entry.
 
 ##### Bytes Usage
 
-The number of bytes encrypted by the [encryption](structures.md#encryption-materials) materials cached in this cache entry.
+The number of bytes encrypted by the [encryption materials](structures.md#encryption-materials)
+cached in this cache entry.
+
+### Time-to-live (TTL)
+
+Each cache entry has a time-to-live (TTL)
+that represents a point in time at which the cache entry
+MUST be considered invalid.
+This is generale the [expiry time](#expiry-time).
+After a cache entry's TTL has elapsed,
+we say that the entry is _TTL-expired_,
+and a CMC MUST NOT return the entry to any caller.
+
+However the [creation time](#creation-time) is also include
+in case a stricter view of TTL is enforced by a caller.
+This can be done by deleting the entry.
 
 ## Supported CMCs
 
@@ -86,19 +113,26 @@ It provides non-blocking, locking, [cache entries](#cache-entry) per [cache iden
 
 ## Behaviors
 
-The Cryptographic Materials Cache provides behaviours for putting cache entries, getting cache entries and deleting cache entries.
+The Cryptographic Materials Cache
+provides behaviors for putting cache entries,
+getting cache entries and deleting cache entries.
 
 ### Put Cache Entry
 
 Attempts to put a cache entry for the specified cache ID.
-If a cache entry for the given cache ID does not exists in the cache, the CMC creates a new cache entry.
+If a cache entry for the given cache ID does not exists in the cache,
+the CMC creates a new cache entry.
 This operation MUST NOT return the inserted cache entry.
+The cache entry MUST include all [usage metadata](#usage-metadata)
+since this information can not be updated after the put operation.
 
 ### Get Cache Entry
 
 Attempts to get a cache entry for the specified cache ID.
-The CMC MUST validate that the cache entry is valid prior to returning the cache entry.
-A successful call to Get Entry returns the [cache entry](#cache-entry) and an unsuccessful call returns a cache miss.
+The CMC MUST validate that the cache entry
+has not exceeded it's stored [TTL](#time-to-live-ttl).
+A successful call to Get Entry returns the [cache entry](#cache-entry)
+and an unsuccessful call returns a cache miss.
 
 ### Delete Cache Entry
 

framework/local-cryptographic-materials-cache.md

@@ -7,6 +7,10 @@
 
 ### Changelog
 
+- 0.2.0
+
+  - Updating the interface. Moving elements from the Local CMC to the interface.
+
 - 0.1.0
   - Initial record
   - [Refactor Cryptographic Materials Cache Specification](../changes/2020-07-14_refactor-cmc-spec/change.md)
@@ -36,14 +40,6 @@ per [cache identifier](cryptographic-materials-cache.md#cache-identifier).
 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL"
 in this document are to be interpreted as described in [RFC 2119](https://tools.ietf.org/html/rfc2119).
 
-### Time-to-live (TTL)
-
-Each cache entry has a time-to-live (TTL) field
-that represents a point in time at which the cache entry MUST be considered invalid.
-After a cache entry's TTL has elapsed,
-we say that the entry is _TTL-expired_,
-and the local CMC MUST NOT return the entry to any caller.
-
 ## Initialization
 
 On initialization of the local CMC,
@@ -74,18 +70,14 @@ for TTL-expired entries to evict.
 
 ### Put Cache Entry
 
-When calling the Put Cache Entry operation,
-the caller MUST provide a time delta value,
-which the local CMC uses to derive the cache entry's time-to-live (TTL) value.
-The local CMC MUST NOT return any TTL-expired entry.
-
 When performing a Put Cache Entry operation,
-the local CMC MUST [prune TTL-expired cache entries](#pruning).
+the local CMC should not [prune TTL-expired cache entries](#pruning).
+This is because an entry is added after a get miss.
+A prune happens during the get operation.
 
 While performing a Put Cache Entry operation,
 the local CMC MAY store more entries than the entry capacity.
-However, before returning the inserted cache entry,
-the local CMC MUST evict least-recently used entries
+However, before returning, the local CMC MUST evict least-recently used entries
 until the number of stored entries does not exceed the entry capacity.
 
 ### Get Cache Entry
@@ -100,6 +92,8 @@ To prune TTL-expired cache entries,
 the local CMC MUST evict all TTL-expired entries
 among the `N` least recently used entries,
 where `N` is the [Entry Pruning Tail Size](#entry-pruning-tail-size).
+This means that a maximum of `N` entries
+and a minimum of `0` entries will be evicted.
 
 The local CMC SHOULD also periodically evict all TTL-expired entries
 among the `N` least recently used entries.