Method Detail

• getKeyForReading

  public K getKeyForReading(boolean invalid)
                                             throws UnknownKeyException

  Description copied from interface: KeyProvider
  Returns the key for reading a protected resource. This implies that the 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.

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

  Parameters:

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

  Returns:

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

  Throws:

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

• getKeyForWriting

  public K getKeyForWriting()
                                             throws UnknownKeyException

  Description copied from interface: KeyProvider
  Returns the key for (over)writing a protected resource. This implies that the key does not need to get validated by any client.

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

  Returns:

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

  Throws:

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

• resetCancelledKey

  public void resetCancelledKey()

  Resets the state of this key provider if and only if prompting for the key has been cancelled.

• resetUnconditionally

  public void resetUnconditionally()

  Resets the state of this key provider unconditionally.

• setKey

  public void setKey(@CheckForNull
            K key)

  Sets the key for reading and (over)writing a protected resource. This may get used after a call to KeyProvider.getKeyForReading(boolean) in order to update some properties of the 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.

  The implementation in the class PromptingKeyProvider clones the given nullable key before setting it.

  Parameters:

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