de.schlichtherle.truezip.key
Class SafeKeyProvider<K extends SafeKey<K>>

java.lang.Object
  de.schlichtherle.truezip.key.SafeKeyProvider<K>

Type Parameters:

K - The type of the keys.

All Implemented Interfaces:

KeyProvider<K>

Direct Known Subclasses:

PromptingKeyProvider

@DefaultAnnotation(value=edu.umd.cs.findbugs.annotations.NonNull.class)
@ThreadSafe
public abstract class SafeKeyProvider<K extends SafeKey<K>>
extends Object
implements KeyProvider<K>

Provides the base functionality required to implement a "safe" key provider. Each instance of this class maintains a single key which implements the interface SafeKey). A clone of this key is returned on each call to getWriteKey() and getReadKey(boolean).

Author:

Christian Schlichtherle

MIN_KEY_RETRY_DELAY

public static final int MIN_KEY_RETRY_DELAY

The minimum delay between subsequent attempts to verify a key in milliseconds. More specifically, this is the minimum delay between two calls to getReadKey(boolean) by the same thread.

See Also:

Constant Field Values

invalidated

private final ThreadLocal<Long> invalidated

SafeKeyProvider

protected SafeKeyProvider()

getWriteKey

public final K getWriteKey()
                                       throws UnknownKeyException

Returns the key for (over)writing the contents of a new or existing protected resource. So this key is not going to be used to authenticate an existing resource by the application.

Subsequent calls to this method return an object which at least compares equal to any previously returned object, but is not necessarily the same.

The implementation in SafeKeyProvider forwards the call to getWriteKeyImpl().

Specified by:

getWriteKey in interface KeyProvider<K extends SafeKey<K>>

Returns:

the key object.

Throws:

UnknownKeyException - If getWriteKeyImpl throws this exception or the returned key is null.

getWriteKeyImpl

@CheckForNull
protected abstract K getWriteKeyImpl()
                                                 throws UnknownKeyException

Returns the key for (over)writing the contents of a new or existing protected resource.

Subsequent calls to this method may return the same object.

Returns:

The key for (over)writing the contents of a new or existing protected resource.

Throws:

UnknownKeyException - if the required key is unknown for some reason, e.g. if prompting for the key has been disabled or cancelled by the user.

See Also:

getWriteKey()

getReadKey

public final K getReadKey(boolean invalid)
                                      throws UnknownKeyException

Returns the key for reading the contents of an existing protected resource. This method is expected to be called consecutively until either the returned key is verified or an exception is thrown.

Unless invalid is true, subsequent calls to this method return an object which at least compares equal to any previously returned object, but is not necessarily the same.

Important: From an application's perspective, a KeyProvider is not trustworthy! Hence, the key returned by this method must not only get authenticated, but the application should also throttle the pace for the return from a subsequent call to this method if the key is invalid in order to protect the client application from an exhaustive search for the correct key. As a rule of thumb, at least three seconds should pass between two consecutive calls to this method by the same thread. "Safe" implementations of this interface should enforce this behaviour in order to protect client applications which do not obeye these considerations against abuses of the key provider implementation.

The implementation in SafeKeyProvider forwards the call to getReadKeyImpl(boolean) and enforces a three seconds suspension penalty if invalid is true before returning. Because this method is final, this qualifies the implementation in this class as a "friendly" KeyProvider implementation, even when subclassed.

Specified by:

getReadKey in interface KeyProvider<K extends SafeKey<K>>

Parameters:

invalid - true iff a previous call to this method resulted in an invalid key.

Returns:

the key object.

Throws:

UnknownKeyException - If getReadKeyImpl throws this exception or the returned key is null.

getReadKeyImpl

@CheckForNull
protected abstract K getReadKeyImpl(boolean invalid)
                                                throws UnknownKeyException

Returns the key for reading the contents of an existing protected resource.

Subsequent calls to this method may return the same object.

Returns:

The key for reading the contents of an existing protected resource.

Throws:

UnknownKeyException - If the required key is unknown. At the subclasses discretion, this may mean that prompting for the key has been disabled or cancelled by the user.

See Also:

KeyProvider.getWriteKey()

clone

@Nullable
protected static <K extends SafeKey<K>> K clone(@CheckForNull
                                                         K key)

Returns a clone of the given key.

Returns:

A clone of the given key.

reset

protected static <K extends SafeKey<K>> void reset(@CheckForNull
                                                   K key)

Resets the given key.

Parameters:

key - the key to reset.

enforceSuspensionPenalty

private void enforceSuspensionPenalty()