com.croftsoft.core.util.cache.secure
Class SecureCache

java.lang.Object
  com.croftsoft.core.util.cache.secure.SecureCache

All Implemented Interfaces:

Cache, Serializable

public final class SecureCache
extends Object
implements Cache, Serializable

Cache implementation that securely stores and retrieves content using digests.

Applications where a SecureCache may be useful include when

• it is desired to be able to retrieve content from the cache even though originally copied and stored from an unknown and potentially untrusted source, so long as the content is bit-for-bit identical to what is currently required;

• multiple entities want to share the same cache without the need to worry that the activities of another, potentially untrusted, entity might modify the stored content to be something other than what is expected;

• the cache is stored on an insecure medium which may be accessed directly and corrupted by another entity; and

• it is desired to detect changes to content stored elsewhere by comparing the digests and then, if necessary, updating the copy in the cache to match.

The security is based upon the use of cryptographically secure content digests which have the property that it is computationally infeasible to find two non-identical instances of content that generate digests with the same value.

The SecureCache wraps around a delegate Cache, which itself may or may not be secure. Multiple digest algorithms may be simultaneously used by "chaining" SecureCache objects.

Note further that an insecure implementation of the Cache interface which validates content using the more traditional mechanisms, e.g., comparing values of content length, freshness date, version number, semi-unique identifier, etc., may be secured by using a SecureCache as a delegate. For example, an insecure Cache that validates content using URL or path/filename, content length, and/or last modified date may map an Id object storing those values to a SecureId object to be passed to a delegate SecureCache.

The Serializable interface is implemented to support persistence. To use this feature, the delegateCache and delegateIdMap must also be Serializable. Reference

& Sun Microsystems, "Java Cryptography Architecture API Specification & Reference", "Message Digest", 1998-10-30.

Version:

1999-04-20

See Also:

MessageDigest, SecureId, com.orbs.open.a.mpl.util.id.Id, com.orbs.open.a.mpl.util.cache.Cache, com.orbs.open.a.mpl.util.cache.ContentAccessor, com.orbs.open.a.mpl.util.cache.WeakCache, com.orbs.open.a.mpl.util.SoftHashMap, Serialized Form

Author:

David Wallace Croft

Constructor Summary

SecureCache()
This example zero argument constructor caches the content in memory, dumps the content when memory runs low, identifies the content using the NIST Secure Hash Algorithm (SHA), and verifies the content digest upon retrieval.

SecureCache(Cache delegateCache, Map delegateIdMap, String algorithm, boolean doVerification)
Creates a new SecureCache that stores content to a delegate Cache.

Method Summary

boolean	isAvailable(Id secureId) Determines if the content with a matching digest is available in the delegateCache.
InputStream	retrieve(Id secureId) Retrieves content with a matching content digest from the delegateCache.
Id	store(InputStream inputStream) Stores the content to the delegateCache and returns a SecureId object which may be used to retrieve it.
Id	validate(Id secureId, ContentAccessor contentAccessor) "Validates" the content by confirming that identical content already exists in the cache; or, if otherwise necessary, storing a new copy of the content in the cache.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SecureCache

public SecureCache(Cache delegateCache,
                   Map delegateIdMap,
                   String algorithm,
                   boolean doVerification)
            throws NoSuchAlgorithmException

Creates a new SecureCache that stores content to a delegate Cache.

Parameters:

delegateCache - Where the content is actually relayed to and from. This may be an insecure Cache or another chained SecureCache.

delegateIdMap - A Map of delegateCache Id objects keyed by SecureId objects generated by this SecureCache.

algorithm - The secure message digest algorithm to use.

doVerification - If true, the content digest will be recalculated upon retrieval to confirm that it has not been altered while in the delegateCache. This is especially recommended if the delegateCache is stored on an insecure medium such as a disk drive.

If false, it is up to the caller to verify that the digest of the returned content is the same. If the delegateCache medium is reasonably secure, such as a shared memory area with exclusive access only through this SecureCache, the caller may be reasonably secure without needing to take the extra verification step.

Note that the doVerification parameter only applies to retrieval; the digest is always calculated from the content during storage.

Throws:

NoSuchAlgorithmException

SecureCache

public SecureCache()
            throws NoSuchAlgorithmException

This example zero argument constructor caches the content in memory, dumps the content when memory runs low, identifies the content using the NIST Secure Hash Algorithm (SHA), and verifies the content digest upon retrieval.

 this ( new WeakCache ( ), new SoftHashMap ( ), "SHA", true );

 

Throws:

NoSuchAlgorithmException

Method Detail

validate

public Id validate(Id secureId,
                   ContentAccessor contentAccessor)
            throws IOException

"Validates" the content by

1. confirming that identical content already exists in the cache; or, if otherwise necessary,
2. storing a new copy of the content in the cache.

Specified by:

validate in interface Cache

Parameters:

secureId - The content identifier passed to isAvailable() to determine if the content is already valid. The parameter may be any SecureId with potentially matching algorithm and digest values.

contentAccessor - An object capable of making content accessible via an InputStream. For example, a ContentAccessor might retrieve content from a website via a URL, a database or file storage, a remote object such as another cache, or even dynamically generate the content upon demand. As yet another possibility, a ContentAccessor object may potentially attempt to access the content from several different sources sequentially until it is successful.

Returns:

Returns a SecureId object for the validated content which may be used later for retrieval.

If valid content was already available in the cache, the returned SecureId object will be the secureId parameter.

If valid content was not already available and the content could not be accessed and stored via the contentAccessor, the returned value will be null.

If valid content was not already available and the content could be accessed and stored via the contentAccessor, the returned value will be a new SecureId object with a digest that may or may not match that of the secureId object parameter, depending on the actual content available via the contentAccessor.

Throws:

IOException

store

public Id store(InputStream inputStream)
         throws IOException

Stores the content to the delegateCache and returns a SecureId object which may be used to retrieve it.

Specified by:

store in interface Cache

Parameters:

inputStream - Any finite ordered sequence of bits. The inputStream will be read until completion by the delegateCache before return.

Returns:

Returns a SecureId object with a digest calculated from the content inputStream.

Throws:

IOException

retrieve

public InputStream retrieve(Id secureId)
                     throws IOException

Retrieves content with a matching content digest from the delegateCache.

If the SecureCache instance variable doVerification is set to true, the digest will be recalculated via a SecureInputStream while the content is being read from the delegateCache. When the last byte is read, the newly calculated digest will be compared to that of the SecureId parameter object. If the digests differ, an IOException will be thrown to prevent use of the corrupted content.

Specified by:

retrieve in interface Cache

Parameters:

secureId - Any SecureId object with a potentially matching content digest.

Returns:

Returns null if the content was not or is no longer available.

Throws:

IOException

isAvailable

public boolean isAvailable(Id secureId)

Determines if the content with a matching digest is available in the delegateCache.

Specified by:

isAvailable in interface Cache

Parameters:

secureId - An Id object to be used to retrieve the content.

Returns:

Returns false if the content was not or is no longer available.