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.

@FunctionalInterface public interface StoreKeyProvider
Supplies the key material the encrypted stores are sealed under, in place of the default derived from machine properties. A host that can reach a real secret — an operating-system keystore entry, a hardware-backed key, a passphrase the user typed — installs one of these so the files at rest are protected by that secret rather than by values any local process can read.

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

    Fields
    Modifier and Type
    Field
    Description
    static final int
    The fewest bytes of key material accepted.
  • Method Summary

    Modifier and Type
    Method
    Description
    byte[]
    Returns the key material.
  • Field Details

    • MIN_LENGTH

      static final int MIN_LENGTH
      The fewest bytes of key material accepted.
      Since:
      0.12.0
      See Also:
  • Method Details

    • keyMaterial

      byte[] keyMaterial() throws Exception
      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_LENGTH bytes of secret key material
      Throws:
      Exception - if the material cannot be obtained; the store then reports itself unavailable
      Since:
      0.12.0