de.schlichtherle.key
Interface KeyProvider

All Known Subinterfaces:

AesKeyProvider

All Known Implementing Classes:

AbstractKeyProvider, PromptingAesKeyProvider, PromptingKeyProvider, SharedKeyProvider

public interface KeyProvider

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(), followed by a call to invalidOpenKey() if the authentication of the returned key failed for some reason.

If the same resource is accessed multiple times, these basic operations are guaranteed to return a key which compares equal, but is not necessarily the same. In fact, the standard implementations in this package try to return a clone of the key wherever possible for maximum security. Failing that, the same key is returned.

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.

As you can see in the last example, it is at the discretion of the key provider whether or not getCreateKey() returns a key which compares equal to the key returned by getOpenKey() or returns a completely different (new) key. Ideally, a brave provider implementation would allow the user to control this. In fact, this is the behaviour of the PromptingKeyProvider in this package and its user interface class(es).

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

Since:

TrueZIP 6.0

Version:

TrueZIP 6.7

Author:

Christian Schlichtherle

See Also:

KeyManager

Field Summary

static int

MIN_KEY_RETRY_DELAY The minimum delay between subsequent attempts to authenticate a key in milliseconds.

Method Summary

Object	getCreateKey() Returns the key which may be used to create a new protected resource or entirely replace the contents of an already existing protected resource.
Object	getOpenKey() Returns the key which may be used to open an existing protected resource in order to access its contents.
void	invalidOpenKey() Called to indicate that authentication of the key returned by getOpenKey() has failed and to request an entirely different key.

Field Detail

MIN_KEY_RETRY_DELAY

static final int MIN_KEY_RETRY_DELAY

The minimum delay between subsequent attempts to authenticate a key in milliseconds. More specifically, this is the minimum delay between the call to invalidOpenKey() and a subsequent getOpenKey() by the same thread.

See Also:

Constant Field Values

Method Detail

getCreateKey

Object getCreateKey()
                    throws UnknownKeyException

Returns the key which may be used to create a new protected resource or entirely replace the contents of an already existing protected resource. Hence, the key does not need to be authenticated.

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

Returns:

A clone of the key object. If the key does not support cloning or cloning fails for some reason, the key object itself is returned. null is never returned.

Throws:

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

getOpenKey

Object getOpenKey()
                  throws UnknownKeyException

Returns the key which may be used to open an existing protected resource in order to access its contents. Hence, the key needs to be authenticated. If the authentication fails, invalidOpenKey() must be called immediately to indicate this situation.

Unless invalidOpenKey() is called, on each call to this method an object is returned 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 the immediate call to invalidOpenKey() and the return from the subsequent call to this method. "Friendly" implementations of this interface should duplicate this behaviour in order to protect client applications which do not obeye these considerations against abuses of the key provider implementation. Note that invalidOpenKey() must still be called immediately by the client application, so that other threads are not negatively affected by the suspension penalty. For the same reason, "friendly" implementations should enforce the suspension penalty for the local thread only.

Returns:

A clone of the key object. If the key does not support cloning or cloning fails for some reason, the key object itself is returned. null is never returned.

Throws:

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

See Also:

MIN_KEY_RETRY_DELAY

invalidOpenKey

void invalidOpenKey()

Called to indicate that authentication of the key returned by getOpenKey() has failed and to request an entirely different key. Whether or not an entirely different key is provided on the next call to getOpenKey() is at the discretion of the provider's implementation and its instance's state.