Class StateSealer

java.lang.Object
com.revetsec.StateSealer

@ThreadSafe public final class StateSealer extends Object
Seals short strings into opaque, URL- and cookie-safe values that only a holder of the same keys can open, and only for the same context before they expire.

Revetsec uses sealed values to carry pending sign-in state through the browser, and applications can seal their own data with seal(String, String, Duration) and unsealResult(String, String). A sealed value is encrypted and authenticated with AES-256-GCM under a key derived with HKDF-SHA256 from the sealing key and a fresh random salt, so every value gets its own encryption key, and it is written in unpadded base64url. It carries, in the clear, the ID of the key that sealed it; everything else is encrypted, authenticated or both. Values sealed here are application data: Revetsec seals its own pending state under other type labels, bound into both the key derivation and the authenticated data, so a value of one kind does not open as the other.

Context. Every value is bound to a context string, such as the name of the cookie that carries it or the identity provider it concerns, and opens only for the same context. A context is 1 to 256 characters of well-formed UTF-16 (no unpaired surrogate). It is not secret and is not stored in the value.

Lifetime. seal takes a lifetime from 1 second to 400 days. The value's expiry, which it carries encrypted, is the current time from the builder's Clock rounded up to a whole second, plus the lifetime rounded down to whole seconds. So a value opens for at least the lifetime's whole seconds and at most one second more, and it stops opening at the first instant at or after its expiry.

Failures. Arguments are checked first: a null throws NullPointerException, and an invalid context, plaintext or lifetime, or a plaintext too long to seal, throws IllegalArgumentException. Every failure to open a value returns the same opaque StateUnsealResult.Rejected outcome, whether the value was tampered with, truncated, malformed, too long, sealed for another context, sealed under a key this sealer does not hold, or expired. Opening never tries more than one key: the key ID in the value selects exactly one.

Keys and rotation. The built sealer seals with its active key and opens values sealed under its active key or any of its verification keys (at most 16). To rotate:

  1. add the new key as a verification key on every instance, so each can open values the new key seals;
  2. promote it: make it the active key and the old key a verification key;
  3. once every expiring value sealed under the old key has expired and every permanent protocol record has been migrated, retire the old key.
Permanent protocol records, including TOTP credentials, do not age out with cookies. Their authenticated resealing, outstanding writers and retained backups need an explicit key-retirement inventory. Rotate at once if a key may have been disclosed: whoever holds a key can seal values that every sealer holding it accepts. Use one key per application.

Size. A sealed value is ceil(4 * (54 + k + p) / 3) characters long for a key ID of k characters and a plaintext of p UTF-8 bytes; a 700-byte plaintext under key ID 2026-09 seals to 1,015 characters. The seal operation refuses, and unsealResult rejects before decoding, any value longer than StateSealer.Builder.maximumSealedLength(Integer): 3,800 characters by default, which leaves room for a cookie's name and attributes within the 4,096 bytes per cookie that RFC 6265 section 6.1 asks browsers to support.

Instances are immutable and safe for concurrent use.

Since:
1.0.0
Author:
Mark Allen
  • Method Details

    • withActiveKey

      Starts building a sealer that seals with activeKey.
      Parameters:
      activeKey - the key that seals new values; it also opens them
      Returns:
      a new builder
      Throws:
      NullPointerException - if activeKey is null
      Since:
      1.0.0
    • seal

      public @NonNull String seal(@NonNull String plaintext, @NonNull String context, @NonNull Duration lifetime)
      Seals plaintext for context, to open until lifetime from now.

      Every call returns a different value, even for the same arguments, because each draws a fresh random salt and IV.

      Parameters:
      plaintext - the text to seal, well-formed UTF-16; it may be empty
      context - the context to bind: 1 to 256 characters of well-formed UTF-16
      lifetime - how long the value opens, from 1 second to 400 days; only whole seconds count
      Returns:
      the sealed value, in unpadded base64url
      Throws:
      NullPointerException - if an argument is null
      IllegalArgumentException - if the context or lifetime is out of range, the plaintext or context contains an unpaired surrogate, or the sealed value would be longer than StateSealer.Builder.maximumSealedLength(Integer)
      IllegalStateException - if the platform's cryptographic provider refuses to seal or cannot supply random bytes
      Since:
      1.0.0
    • unsealResult

      @CheckReturnValue public @NonNull StateUnsealResult unsealResult(@NonNull String sealed, @NonNull String context)
      Opens application state once and returns its authenticated plaintext or one undifferentiated rejection. Expiry, wrong context, unknown keys, malformed input and authentication failure expose no differing detail.
      Parameters:
      sealed - untrusted sealed state
      context - trusted application context
      Returns:
      the opening outcome
      Throws:
      NullPointerException - if either argument is null
      IllegalArgumentException - if the context is invalid
      Since:
      1.0.0
    • toString

      Returns a description of this sealer's configuration, which names its key IDs but never renders a key.
      Overrides:
      toString in class Object
      Returns:
      a description of this sealer without its secrets
      Since:
      1.0.0