Interface StoreKeyProvider
- Functional Interface:
- This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.
Entirely optional. Without a provider the stores behave exactly as they always have. With one, a file opens under the host's key or not at all: a store that does not open under it is reported unreadable and left untouched, whatever key did seal it.
Files written before the provider was installed are the one exception, and only when the host
asks: AltsRuntime.Builder#migrateFromMachineKey(boolean) lets a store that opens under the
machine-derived default load once and be rewritten under the host's key, along with every kept copy
of it, so that nothing sealed under the old key is left in the directory. Turn it on for the launch
that adopts the provider and off afterwards. It is off by default because the machine-derived key can
be reconstructed by anyone who can read the machine's properties: accepting it indefinitely would let
whoever can write the store directory plant a file, or put back a copy from before the migration, and
have it load as though the host had sealed it.
Resolution fails closed. A provider that throws, or returns null or fewer than
MIN_LENGTH bytes, leaves the store unreadable and unwritable; the library never falls back to
the machine-derived key for a write, because that would silently store credentials under the weaker
key at the moment the host believed otherwise. A load that fails this way also holds every later
write back, even once the provider answers, until the store has been loaded successfully — the file
on disk is intact, and writing what is in memory would replace it. Call the store's load()
again when the secret becomes available, or its discardUnreadable() if it never will (the key
was rotated or lost), which copies the file aside and starts a new store.
The provider belongs to the runtime it is given to. Each of that runtime's stores asks it, and no other runtime's store ever does. A later runtime built without it, on the same directory, cannot open the files and does not write over them either: a file that did not open is never overwritten.
- Since:
- 0.12.0
-
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final intThe fewest bytes of key material accepted. -
Method Summary
-
Field Details
-
MIN_LENGTH
static final int MIN_LENGTHThe fewest bytes of key material accepted.- Since:
- 0.12.0
- See Also:
-
-
Method Details
-
keyMaterial
Returns the key material. It must be the same bytes on every call for as long as the stored files are meant to stay readable; each store asks when it first needs the key and keeps the answer in memory for as long as it is open. The material is stretched and bound to each store before use, so one secret serves both stores.- Returns:
- at least
MIN_LENGTHbytes of secret key material - Throws:
Exception- if the material cannot be obtained; the store then reports itself unavailable- Since:
- 0.12.0
-