SafeKeyProvider (TrueZIP Driver ZIP.RAES (TZP) 7.3-rc-1 API)

java.lang.Object
- de.schlichtherle.truezip.key.SafeKeyProvider<K>

Type Parameters:
K - The type of the keys.

All Implemented Interfaces:

KeyProvider<K>

Direct Known Subclasses:

PromptingKeyProvider
```
@ThreadSafe
@DefaultAnnotation(value=edu.umd.cs.findbugs.annotations.NonNull.class)
public abstract class SafeKeyProvider<K extends SafeKey<K>>
extends Object
implements KeyProvider<K>
```
Provides the base functionality required to implement a "safe" key provider. Each instance of this class maintains a single instance of the interface SafeKey). A clone of this key is returned on each call to getWriteKey() and getReadKey(boolean).

Author:

Christian Schlichtherle

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

private static class SafeKeyProvider.ThreadLocalLong

Nested Classes
Modifier and Type	Class and Description
`private static class`	`SafeKeyProvider.ThreadLocalLong`

Field Summary

Fields
Modifier and Type	Field and Description
`private ThreadLocal<Long>`	`invalidated`
`private K`	`key`
`static int`	`MIN_KEY_RETRY_DELAY` The minimum delay between subsequent attempts to verify a key in milliseconds.

Constructor Summary

Constructors
Modifier Constructor and Description

protected SafeKeyProvider()
Constructs a new safe key provider.

Constructors
Modifier	Constructor and Description
`protected`	`SafeKeyProvider()` Constructs a new safe key provider.

Method Summary

Methods
Modifier and Type	Method and Description
`private void`	`enforceSuspensionPenalty()`
`protected K`	`getKey()`
`private K`	`getNonNullKey()`
`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.
`protected abstract void`	`retrieveReadKey(boolean invalid)` Retrieves the secret key for the decryption of a protected resource.
`protected abstract void`	`retrieveWriteKey()` Retrieves the secret key for the encryption of a protected resource.
`void`	`setKey(K newKey)` Sets the secret key programmatically.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - MIN_KEY_RETRY_DELAY
```
public static final int MIN_KEY_RETRY_DELAY
```
    The minimum delay between subsequent attempts to verify a key in milliseconds. More specifically, this is the minimum delay between two calls to getReadKey(boolean) by the same thread.
    
    See Also:
    Constant Field Values
  - key
```
@CheckForNull
private volatile K extends SafeKey<K> key
```
  - invalidated
```
private final ThreadLocal<Long> invalidated
```
- Constructor Detail
  - SafeKeyProvider
```
protected SafeKeyProvider()
```
    Constructs a new safe key provider.
- Method Detail
  - getWriteKey
```
public final 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.
    The implementation in SafeKeyProvider forwards the call to retrieveWriteKey().
    
    Specified by:
    
    getWriteKey in interface KeyProvider<K extends SafeKey<K>>
    
    Returns:
    the secret key.
    
    Throws:
    
    UnknownKeyException - If retrieveWriteKey throws this exception or the secret key is still null.
  - retrieveWriteKey
```
protected abstract void retrieveWriteKey()
                                  throws UnknownKeyException
```
    Retrieves the secret key for the encryption of a protected resource.
    Subsequent calls to this method may return the same object.
    
    Throws:
    
    UnknownKeyException - If the secret key is unknown. At the subclasses discretion, this may mean that prompting for the key has been disabled or cancelled by the user.
    See Also:
    getWriteKey()
  - getReadKey
```
public final 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.
    The implementation in SafeKeyProvider forwards the call to retrieveReadKey(boolean) and enforces a three seconds suspension penalty if invalid is true before returning. Because this method is final, this qualifies the implementation in this class as a "safe" KeyProvider implementation, even when subclassed.
    
    Specified by:
    
    getReadKey in interface KeyProvider<K extends SafeKey<K>>
    
    Parameters:
    invalid - true iff a previous call to this method resulted in an invalid key.
    
    Returns:
    the secret key.
    
    Throws:
    
    UnknownKeyException - If retrieveReadKey throws this exception or the secret key is still null.
  - retrieveReadKey
```
protected abstract void retrieveReadKey(boolean invalid)
                                 throws UnknownKeyException
```
    Retrieves the secret key for the decryption of a protected resource.
    Subsequent calls to this method may return the same object.
    
    Throws:
    
    UnknownKeyException - If the secret key is unknown. At the subclasses discretion, this may mean that prompting for the key has been disabled or cancelled by the user.
    See Also:
    getReadKey(boolean)
  - getNonNullKey
```
private K getNonNullKey()
                                    throws UnknownKeyException
```
    Throws:
    
    UnknownKeyException
  - getKey
```
@CheckForNull
protected K getKey()
```
  - setKey
```
public void setKey(@CheckForNull
          K newKey)
```
    Description copied from interface: KeyProvider
    
    Sets the secret key programmatically.
    
    Specified by:
    
    setKey in interface KeyProvider<K extends SafeKey<K>>
    
    Parameters:
    newKey - 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.
  - enforceSuspensionPenalty
```
private void enforceSuspensionPenalty()
```

Class SafeKeyProvider<K extends SafeKey<K>>

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

MIN_KEY_RETRY_DELAY

key

invalidated

Constructor Detail

SafeKeyProvider

Method Detail

getWriteKey

retrieveWriteKey

getReadKey

retrieveReadKey

getNonNullKey

getKey

setKey

enforceSuspensionPenalty