com.amazonaws.encryptionsdk.caching

Interface CryptoMaterialsCache

All Known Implementing Classes:

LocalCryptoMaterialsCache, NullCryptoMaterialsCache

public interface CryptoMaterialsCache

Represents a generic cache for cryptographic materials. MaterialsCaches store mappings from abstract bytestring identifiers to MaterialsResults and DecryptResults.

In general, the materials cache is concerned about the proper storage of these materials, and managing size limits on the cache. While it stores statistics about cache usage limits, the enforcement of these limits is left to the caller (typically, a CachingCryptoMaterialsManager).

For encrypt, a cache implementation may store multiple cache entries for the same identifier. This allows for usage limits to be enforced even when doing multiple streaming requests in parallel. However, the cache is permitted to set a limit on the number of such entries (even as low as only allowing one entry per identifier), and if it does so should evict the excess entries.

Being a cache, a CryptoMaterialsCache is permitted to evict entries at any time. However, a caller can explicitly hint the cache to invalidate an entry in the encrypt-side cache. This is generally done when usage limits are exceeded. The cache is not required to respect this invalidation hint.

Likewise, the CacheHint passed to the put calls on caches will indicate the maximum lifetime of entries; the cache is allowed - but not required - to evict entries automatically upon expiration of this lifetime.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	CryptoMaterialsCache.CacheHint Contains some additional information associated with a cache entry.
static interface	CryptoMaterialsCache.DecryptCacheEntry Represents an entry in the decrypt cache, and provides methods for manipulating the entry.
static interface	CryptoMaterialsCache.EncryptCacheEntry Represents an entry in the encrypt cache, and provides methods for manipulating the entry.
static class	CryptoMaterialsCache.UsageStats

Method Summary

Modifier and Type	Method and Description
CryptoMaterialsCache.DecryptCacheEntry	getEntryForDecrypt(byte[] cacheId) Searches for an entry in the encrypt cache matching a particular cache identifier, and returns one if found.
CryptoMaterialsCache.EncryptCacheEntry	getEntryForEncrypt(byte[] cacheId, CryptoMaterialsCache.UsageStats usageIncrement) Searches for an entry in the encrypt cache matching a particular cache identifier, and returns one if found.
void	putEntryForDecrypt(byte[] cacheId, DecryptionMaterials decryptionMaterials, CryptoMaterialsCache.CacheHint hint) Adds a new entry to the decrypt cache.
CryptoMaterialsCache.EncryptCacheEntry	putEntryForEncrypt(byte[] cacheId, EncryptionMaterials encryptionMaterials, CryptoMaterialsCache.CacheHint hint, CryptoMaterialsCache.UsageStats initialUsage) Attempts to add a new entry to the encrypt cache to be returned on subsequent getEntryForEncrypt(byte[], UsageStats) calls.

Method Detail

getEntryForEncrypt

CryptoMaterialsCache.EncryptCacheEntry getEntryForEncrypt(byte[] cacheId,
                                                          CryptoMaterialsCache.UsageStats usageIncrement)

Searches for an entry in the encrypt cache matching a particular cache identifier, and returns one if found.

Parameters:

cacheId - The identifier for the item in the cache

usageIncrement - The amount of usage to atomically add to the returned entry. This usage increment must be reflected in the getUsageStats() method on the returned cache entry.

Returns:

The entry, or null if not found or an error occurred

putEntryForEncrypt

CryptoMaterialsCache.EncryptCacheEntry putEntryForEncrypt(byte[] cacheId,
                                                          EncryptionMaterials encryptionMaterials,
                                                          CryptoMaterialsCache.CacheHint hint,
                                                          CryptoMaterialsCache.UsageStats initialUsage)

Attempts to add a new entry to the encrypt cache to be returned on subsequent getEntryForEncrypt(byte[], UsageStats) calls.

In the event that an error occurs when adding the entry to the cache, this function shall still return a EncryptCacheEntry instance, which shall act as if the cache entry was immediately evicted and/or invalidated.

Parameters:

cacheId - The identifier for the item in the cache

encryptionMaterials - The EncryptionMaterials to associate with this new entry

initialUsage - The initial usage stats for the cache entry

Returns:

A new, locked EncryptCacheEntry instance containing the given encryptionMaterials

getEntryForDecrypt

CryptoMaterialsCache.DecryptCacheEntry getEntryForDecrypt(byte[] cacheId)

Searches for an entry in the encrypt cache matching a particular cache identifier, and returns one if found.

In the event of an error accessing the cache, this function will return null.

Parameters:

cacheId - The identifier for the item in the cache

Returns:

The cached decryption result, or null if none was found or an error occurred.

putEntryForDecrypt

void putEntryForDecrypt(byte[] cacheId,
                        DecryptionMaterials decryptionMaterials,
                        CryptoMaterialsCache.CacheHint hint)

Adds a new entry to the decrypt cache. In the event of an error, this function will return silently without propagating the exception.

If an entry already exists for this cache ID, the cache may either overwrite the entry in its entirety, or update the creation timestamp for the existing entry, at its option.

Parameters:

cacheId - The identifier for the item in the cache

decryptionMaterials - The DecryptionMaterials to associate with the new entry.