KeyProvider (TrueZIP Driver ZIP.RAES (TZP) 7.1.3 API)

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).
Calling the same method subsequently is guaranteed to return a key which at least compares equal, but is not necessarily the same.
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.
As you can see in the last example, it is at the discretion of the key provider whether or not getWriteKey() returns a key which compares equal to the key returned by getReadKey(boolean) or returns a completely different new key. Ideally, a brave provider implementation would allow the user to control this.
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

Nested Class Summary

Nested Classes
Modifier and Type Interface and Description

static interface KeyProvider.Factory<P extends KeyProvider<?>>
A factory for key providers.

Nested Classes
Modifier and Type	Interface and Description
`static interface`	`KeyProvider.Factory<P extends KeyProvider<?>>` A factory for key providers.

Method Summary

Methods
Modifier and Type	Method and Description
`K`	`getReadKey(boolean invalid)` Returns the key for reading the contents of an existing protected resource.
`K`	`getWriteKey()` Returns the key for (over)writing the contents of a new or existing protected resource.
`void`	`setKey(K key)` Sets the key programmatically.

- Method Detail
  - 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.

Interface KeyProvider<K>

Nested Class Summary

Method Summary

Method Detail

getWriteKey

getReadKey

setKey