de.schlichtherle.truezip.key
Interface KeyProvider<K>

Type Parameters:

K - The type of the keys.

All Known Implementing Classes:

PromptingKeyProvider, SafeKeyProvider

@DefaultAnnotation(value=edu.umd.cs.findbugs.annotations.NonNull.class)
public interface KeyProvider<K>

A general purpose interface used by client applications to retrieve a key which is required for write or read access to a protected resource. Both the key and the protected resource may be virtually anything: The minimum requirement for a key is just that it's an Object. The protected resource is not even explicitly modelled in this interface. So in order to use it, an instance must be associated with a protected resource by a third party - this is the job of the KeyManager class.

Once an instance has been associated to a protected resource, the client application is assumed to use the key for two basic operations:

1. The key is used in order to create a new protected resource or entirely replace its contents. This implies that the key does not need to be authenticated. For this purpose, client applications call the method getWriteKey().
2. The key is used in order to open an already existing protected resource for access to its contents. This implies that the key needs to be authenticated by the client application. For this purpose, client applications call the method getReadKey(boolean).

From a client application's perspective, the two basic operations may be executed in no particular order. Following are some typical use cases:

1. A new protected resource needs to be created. In this case, just getWriteKey() needs to get called.
2. The contents of an already existing protected resource need to be completely replaced. Hence there is no need to retrieve and authenticate the existing key. Again, just getWriteKey() needs to get called.
3. The contents of an already existing protected resource need to be read, but not changed. This implies that the existing key needs to be retrieved and authenticated. In this case, just getReadKey(boolean) needs to get called.
4. The contents of an already existing protected resource need to be read and then only partially updated with new contents. This implies that the existing key needs to be retrieved and authenticated. Because the contents are only partially updated, changing the key is not possible. Again, just getReadKey(boolean) needs to get called.
5. The contents of an already existing protected resource need to be read and then entirely replaced with new contents. This implies that the existing key needs to be retrieved and authenticated before it is probably (at the provider's discretion) replaced with a new key. In this case, first getReadKey(boolean) and then getWriteKey() need to get called.

Note that provider implementations must be thread-safe. This allows clients to use the same provider by multiple threads concurrently.

Author:

Christian Schlichtherle

See Also:

KeyManager

getWriteKey

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.

Returns:

the key object.

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.

getReadKey

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.

Parameters:

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

Returns:

the key object.

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.

setKey

void setKey(@CheckForNull
            K key)

Sets the key programmatically.

Parameters:

key - the key. If this is null, this key provider is set to a state as if prompting for the key had been disabled or cancelled.