Class DeviceParameterSeal

java.lang.Object
com.iizix.device.DeviceParameterSeal
public final class DeviceParameterSeal extends Object
The seal of a sensitive device parameter, as the server stores it on the device (CC-PWA-APPBOUND-DEVICE-PARAMS; PWA requirement 6, row AP-D-4 of the v5 PWA audit).

The stored value is the purpose, the application ID, the device UUID and the value, sealed through ISensitiveParameterHandler.encodeParameter(String) exactly as the server seals an e-mail verification link or the secret of a second factor: AES-256-GCM under the installation's key, the GCM tag as the keyed MAC. The device holds an opaque value and no key. The purpose keeps a value the server sealed for anything else from being read as a device parameter; the application ID keeps a value one application saved from being read by another application of the same server, were it copied in the device's storage under the other application's name; the device UUID keeps a value from being read on another device, as before.

The form before this class (servers of v4 and earlier) sealed uuid '\n' value, with no purpose and no application ID. Such a value opens as DeviceParameterSeal.Outcome.LEGACY when it names this device: the reader treats the parameter as not found, so that the application asks the user for it again, and removes it from the device.

The separator. The four fields are joined by a line feed. An application ID holds letters, digits, '.' and '_' only (IServer.validateAppID) and a device UUID is one line, so neither holds the separator; seal(ISensitiveParameterHandler, String, String, String) refuses one that does, and open(ISensitiveParameterHandler, String, String, String) takes the application ID and the UUID as the two fields after the purpose and the value as everything after the third separator. A value may therefore hold anything, line feeds included, and nothing in it can move a field boundary.

Author:
Christopher Mindus

  • Field Details

  • Method Details

    • seal

      public static String seal(ISensitiveParameterHandler keys, String appID, String uuid, String value) throws GeneralSecurityException
      Seals the value of a sensitive device parameter for an application on a device.
      Parameters:
      keys - The server's sealing keys.
      appID - The application ID.
      uuid - The device UUID.
      value - The value, anything.
      Returns:
      The sealed value to store on the device.
      Throws:
      GeneralSecurityException - If the value cannot be sealed.
      NullPointerException - If a parameter is null.
      IllegalArgumentException - If the application ID or the device UUID is empty or holds a line feed.

    • open

      public static DeviceParameterSeal.Opened open(ISensitiveParameterHandler keys, String appID, String uuid, String sealed)
      Opens a sealed value read from a device for an application on that device.

      The value is opened with the server's keys, which fails for a value sealed by another server, for one altered anywhere and for anything that is not a sealed value at all; the content must then carry the purpose, the application ID given and the UUID given. Nothing is thrown: the outcome says what the value is, and the caller decides what to log and what the application is told.

      Parameters:
      keys - The server's sealing keys.
      appID - The application ID of the session reading the value.
      uuid - The device UUID of the session reading the value.
      sealed - The sealed value as stored on the device.
      Returns:
      The opened value, never null.
      Throws:
      NullPointerException - If keys, appID or uuid is null.