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 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 can be of any run time type (it is just required to be Cloneable). A clone of this key is returned on each call to getCreateKey() and getOpenKey(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 getOpenKey(boolean) by the same thread.

See Also:

Constant Field Values

invalidated

private final ThreadLocal<Long> invalidated

SafeKeyProvider

protected SafeKeyProvider()

getCreateKey

public final K getCreateKey()
                                        throws UnknownKeyException

Returns the key which should be used to create a new protected resource or entirely replace the contents of an already existing protected resource. Hence, this key is not going to be used to authenticate an existing resource by the client application.

Each call to this method returns an object which compares equal to the previously returned object, but is not necessarily the same.

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

Specified by:

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

Returns:

the key object.

Throws:

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

getCreateKeyImpl

@CheckForNull
protected K getCreateKeyImpl()
                                         throws UnknownKeyException

Returns the key which should be used to create a new protected resource or entirely replace the contents of an already existing protected resource.

Consecutive calls to this method may return the same object.

Returns:

A template for the key to clone or null.

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:

getCreateKey()

getOpenKey

public final K getOpenKey(boolean invalid)
                                      throws UnknownKeyException

Returns the key which should be used to open an existing protected resource in order to access its contents. This method is expected to be called consecutively until either the returned key is verified or an exception is thrown.

Unless invalid is true, each call to this method returns an object which compares equal to the previously returned object, but is not necessarily the same.

Important: From a client application's perspective, a KeyProvider is not trustworthy! Hence, the key returned by this method must not only get authenticated, but the client 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 getOpenKeyImpl(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:

getOpenKey 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 getOpenKeyImpl throws this exception or the returned key is null.

getOpenKeyImpl

@CheckForNull
protected K getOpenKeyImpl(boolean invalid)
                                       throws UnknownKeyException

Returns the key which should be used to open an existing protected resource in order to access its contents.

Returns:

A template for the key to use or null.

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.getCreateKey()

clone

@Nullable
protected K clone(@CheckForNull
                           K key)

Returns a clone of the given key.

Returns:

A clone of the given key.

reset

protected void reset(@CheckForNull
                     K key)

Resets the given key.

Parameters:

key - the key to reset.

enforceSuspensionPenalty

private void enforceSuspensionPenalty()