K
- The type of the secret keys.@ThreadSafe public interface KeyProvider<K>
KeyManager
.
Clients typically use the secret key for the encryption and authentication of protected resources. However, neither the protected resources nor their encryption or authentication operations are modelled by this interface. Instead, clients are assumed to use it for the following purposes:
getWriteKey()
returns the secret key for writing a
protected resource.
This implies that the secret key does not need to get validated by the
client.
getReadKey(boolean)
returns the secret key for reading a
protected resource.
This implies that the secret key needs to get validated by the client.
setKey(K)
sets the secret key programmatically.
This can get used after a call to getReadKey(boolean)
in order to update
some properties of the secret key after it has been validated by the
client.
equal
, but is not necessarily the same.
Following are some typical use cases:
getWriteKey()
needs to get called.
getWriteKey()
needs to get called.
getReadKey(boolean)
needs to get called.
getReadKey(boolean)
needs to get called.
getReadKey(boolean)
and then getWriteKey()
need to get called.
getWriteKey()
returns a secret
key which compares equal
to the secret key returned by
getReadKey(boolean)
or returns a completely different secret key.
Typically, a provider implementation enables the user to control this.
Implementations must be safe for multi-threading.
KeyManager
Modifier and Type | Method and Description |
---|---|
K |
getReadKey(boolean invalid)
Returns the secret key for reading a protected resource.
|
K |
getWriteKey()
Returns the secret key for writing a protected resource.
|
void |
setKey(K key)
Sets the secret key programmatically.
|
K getReadKey(boolean invalid) throws UnknownKeyException
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.
invalid
- true
iff a previous call to this method returned
an invalid key.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.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.K getWriteKey() throws UnknownKeyException
equal
to this secret key,
but is not necessarily the same.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.void setKey(@CheckForNull K key)
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.
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.Copyright © 2005–2018 Schlichtherle IT Services. All rights reserved.