de.schlichtherle.truezip.key

Interface KeyProvider<K>

Type Parameters:

K - The type of the secret keys.

All Known Implementing Classes:

PromptingKeyProvider, SafeKeyProvider

@ThreadSafe
public interface KeyProvider<K>

Manages the life cycle of a generic secret key for reading and writing protected resources. A key provider is usually (but not necessarily) associated to one or more protected resources by a KeyManager.

Clients typically use the secret key for the encryption and authentication of protected resources. However, neither the protected resources nor their encryption or authentication operations are modelled by this interface. Instead, clients are assumed to use it for the following purposes:

1. The method getWriteKey() returns the secret key for writing a protected resource. This implies that the secret key does not need to get validated by the client.
2. The method getReadKey(boolean) returns the secret key for reading a protected resource. This implies that the secret key needs to get validated by the client.
3. The method setKey(K) sets the secret key programmatically. This can get used after a call to getReadKey(boolean) in order to update some properties of the secret key after it has been validated by the client.

The methods of this interface may get executed in arbitrary order. Calling the same method subsequently is guaranteed to return a key which at least compares equal, but is not necessarily the same.

Following are some typical use cases:

1. A new protected resource needs to get created. In this case, getWriteKey() needs to get called.
2. The contents of an already existing protected resource need to get completely replaced. Hence there is no need to retrieve and validate the secret key. Again, 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 secret key needs to get retrieved and validated. In this case, just getReadKey(boolean) needs to get called.
4. The contents of an already existing protected resource need to get read and then only partially updated with new contents. This implies that the secret key needs to get retrieved and validated. Because the contents are only partially updated, changing the secret key is not possible. Again, just getReadKey(boolean) needs to get called.
5. The contents of an already existing protected resource need to get read and then entirely replaced with new contents. This implies that the secret key needs to get retrieved and validated before it may optionally get replaced (at the provider's discretion) with a different secret key. In this case, first getReadKey(boolean) and then getWriteKey() need to get called.

As you can see in the last example, it is at the discretion of the key provider implementation whether or not getWriteKey() returns a secret key which compares equal to the secret key returned by getReadKey(boolean) or returns a completely different secret key. Typically, a provider implementation enables the user to control this.

Implementations must be safe for multi-threading.

Author:

Christian Schlichtherle

See Also:

KeyManager

Method Summary

Modifier and Type	Method and Description
K	getReadKey(boolean invalid) Returns the secret key for reading a protected resource.
K	getWriteKey() Returns the secret key for writing a protected resource.
void	setKey(K key) Sets the secret key programmatically.

Method Detail

getReadKey

K getReadKey(boolean invalid)
      throws UnknownKeyException

Returns the secret key for reading a protected resource. This implies that the secret key needs to get validated by the client. This method is expected to be called consecutively until either the returned key has been validated by another component which actually performs the decryption or an exception is thrown.

Important: From a KeyProvider perspective, a client is not trustworthy! Hence, the implementation should throttle the pace for the return from a subsequent call to this method if the key is invalid in order to protect against 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.

Parameters:

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

Returns:

the secret key for reading a protected resource. Unless invalid is true, subsequent calls to this method return a secret key which at least compares equal to this secret key, but is not necessarily the same.

Throws:

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

getWriteKey

K getWriteKey()
       throws UnknownKeyException

Returns the secret key for writing a protected resource. This implies that the secret key does not need to get validated by the client.

Returns:

the secret key for writing a protected resource. Subsequent calls to this method return a secret key which at least compares equal to this secret key, but is not necessarily the same.

Throws:

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

setKey

void setKey(@CheckForNull
            K key)

Sets the secret key programmatically. This can get used after a call to getReadKey(boolean) in order to update some properties of the secret key after it has been validated by the client.

Implementations should make a protective copy of the given key in order to protect against subsequent modifications by the client.

Parameters:

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