K
- The type of the keys.@ImplementationsShouldExtend(value=AbstractKeyProvider.class) public interface KeyProvider<K>
AbstractKeyProvider
class rather than directly implementing this
interface in order to maintain binary backwards compatibility even if this
interface is changed.
A key provider is usually (but not necessarily) associated to one or more
protected resources by a KeyManager
.
Clients typically use the 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:
getKeyForWriting()
returns the key for writing the
protected resources.
This implies that the key does not need to get validated by any client.
getKeyForReading(boolean)
returns the key for reading the
protected resources.
This implies that the key needs to get validated by some client.
setKey(K)
sets the key programmatically.
This may get used after a call to getKeyForReading(boolean)
in order to
update some properties of the key and implies that the key has been
validated by some client.
equal
, but is not necessarily the same.
Following are some typical use cases:
getKeyForWriting()
needs to get called.
getKeyForWriting()
needs to get called.
getKeyForReading(boolean)
needs to get called.
getKeyForReading(boolean)
needs to get called.
getKeyForReading(boolean)
and then
getKeyForWriting()
need to get called.
getKeyForWriting()
returns a
key which compares equal
to the key returned by
getKeyForReading(boolean)
or returns a completely different 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 |
getKeyForReading(boolean invalid)
Returns the key for reading a protected resource.
|
K |
getKeyForWriting()
Returns the key for (over)writing a protected resource.
|
void |
setKey(K key)
Sets the key for reading and (over)writing a protected resource.
|
K getKeyForReading(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.
Implementations should return a protective copy of the key in order to protect against subsequent modifications by the client.
invalid
- true
iff a previous call to this method returned
an invalid key.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.UnknownKeyException
- if the key is unknown for some
reason, e.g. if prompting for the key has been disabled or
cancelled by the user.K getKeyForWriting() throws UnknownKeyException
Implementations should return a protective copy of the key in order to protect against subsequent modifications by the client.
equal
to this key,
but is not necessarily the same.UnknownKeyException
- if the key is unknown for some
reason, e.g. if prompting for the key has been disabled
or cancelled by the user.void setKey(@CheckForNull K key)
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.
key
- the key.
If this is null
, this key provider is set to a state
as if prompting for the key had been cancelled.Copyright © 2012–2014 Schlichtherle IT Services. All rights reserved.