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 if the parameter invalid is true.

  See Also:

  Constant Field Values

Constructor Detail

• SafeKeyProvider

  protected SafeKeyProvider()

  Constructs a new safe key provider.

Method Detail

• getKey

  @CheckForNull
  protected K getKey()

• getReadKey

  public final 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.

  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 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 retrieveReadKey throws this exception or the secret key is still null.

• getWriteKey

  public final 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.

  The implementation in SafeKeyProvider forwards the call to retrieveWriteKey().

  Specified by:

  getWriteKey in interface KeyProvider<K extends SafeKey<K>>

  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 retrieveWriteKey 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)

• 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()

• setKey

  public void setKey(@CheckForNull
            K newKey)

  Description copied from interface: KeyProvider
  Sets the secret key programmatically. This can get used after a call to KeyProvider.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.

  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.