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

• invalidated

  private final ThreadLocal<Long> invalidated

Constructor Detail

• SafeKeyProvider

  protected SafeKeyProvider()

Method Detail

• getWriteKey

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

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

  Specified by:

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

  Returns:

  the key object.

  Throws:

  UnknownKeyException - If getWriteKeyImpl throws this exception or the returned key is null.

• getWriteKeyImpl

  @CheckForNull
  protected abstract K getWriteKeyImpl()
                                                   throws UnknownKeyException

  Returns the key for (over)writing the contents of a new or existing protected resource.

  Subsequent calls to this method may return the same object.

  Returns:

  The key for (over)writing the contents of a new or existing protected resource.

  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.

  See Also:

  getWriteKey()

• getReadKey

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

  The implementation in SafeKeyProvider forwards the call to getReadKeyImpl(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 "friendly" 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 key object.

  Throws:

  UnknownKeyException - If getReadKeyImpl throws this exception or the returned key is null.

• getReadKeyImpl

  @CheckForNull
  protected abstract K getReadKeyImpl(boolean invalid)
                                                  throws UnknownKeyException

  Returns the key for reading the contents of an existing protected resource.

  Subsequent calls to this method may return the same object.

  Returns:

  The key for reading the contents of an existing protected resource.

  Throws:

  UnknownKeyException - If the required 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:

  KeyProvider.getWriteKey()

• clone

  @Nullable
  protected static <K extends SafeKey<K>> K clone(@CheckForNull
                                        K key)

  Returns a clone of the given key.

  Returns:

  A clone of the given key.

• reset

  protected static <K extends SafeKey<K>> void reset(@CheckForNull
                                  K key)

  Resets the given key.

  Parameters:

  key - the key to reset.

• enforceSuspensionPenalty

  private void enforceSuspensionPenalty()