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

Type Parameters:
K - The type of the secret keys.

All Known Implementing Classes:

PromptingKeyProvider, SafeKeyProvider
```
@DefaultAnnotation(value=edu.umd.cs.findbugs.annotations.NonNull.class)
public interface KeyProvider<K>
```
Manages the life cycle of a generic secret key for the encryption and decryption of protected resources. A key provider is usually (but not necessarily) associated to one or more protected resources by a KeyManager. Note that neither the protected resources nor their encryption/decryption operations are modelled by this interface.
Clients are assumed to use this interface for the following purposes:
1. The method getWriteKey() retrieves the secret key for encrypting a protected resource. This implies that the secret key does not need to get authenticated.
2. The method getReadKey(boolean) retrieves the secret key for decrypting a protected resource. This implies that the secret key needs to get authenticated by the component which actually performs the decryption.
3. The method setKey(K) sets the secret key. This can be used after a call to getReadKey(boolean) in order to update some properties of the secret key after it has been authenticated by the component which actually performs the decryption.
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 be created. In this case, 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 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 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 secret key needs to be retrieved and authenticated. 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 be read and then entirely replaced with new contents. This implies that the secret key needs to be retrieved and authenticated 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. Ideally, a brave provider implementation would allow the user to control this.
Implementations must be safe for multi-threading.
Author:

Christian Schlichtherle

See Also:
KeyManager

Method Summary

Methods
Modifier and Type	Method and Description
`K`	`getReadKey(boolean invalid)` Retrieves the secret key for the decryption of a protected resource.
`K`	`getWriteKey()` Retrieves the secret key for the encryption of a protected resource.
`void`	`setKey(K key)` Sets the secret key programmatically.

- Method Detail
  - getWriteKey
```
K getWriteKey()
              throws UnknownKeyException
```
    Retrieves the secret key for the encryption of a protected resource.
    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 secret key.
    
    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.
  - getReadKey
```
K getReadKey(boolean invalid)
             throws UnknownKeyException
```
    Retrieves the secret key for the decryption of a protected resource. This method is expected to be called consecutively until either the returned key has been authenticated by another component which actually performs the decryption 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 obey 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 secret key.
    
    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.
    
    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.

Interface KeyProvider<K>

Method Summary

Method Detail

getWriteKey

getReadKey

setKey