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 to create or open a protected resource. Both the key and the protected resources may be virtually anything: The minimum requirement for a key is just that it's an Object. Protected resources are 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. Because the protected resource is not modelled within this interface, it is at the discretion of the provider implementation whether its instances may or may not be shared among protected resources. If they do, then all associated protected resources share the same key.

For the following examples, it helps if you think of the protected resource being an encrypted file and the key being a password. Of course, this interface also works with certificate based encryption.

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

1. A key is required 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 getCreateKey().
2. A key is required 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 getOpenKey(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 the first basic operation is applied.
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. In this case, just the first basic operation is applied.
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 the second basic operation is applied.
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. In this case, just the second basic operation is applied.
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, the second and then the first operation is applied.

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

getCreateKey

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.

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.

getOpenKey

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.

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.