Class StateSealer
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:
- add the new key as a verification key on every instance, so each can open values the new key seals;
- promote it: make it the active key and the old key a verification key;
- once every expiring value sealed under the old key has expired and every permanent protocol record has been migrated, retire the old key.
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
-
Nested Class Summary
Nested Classes -
Method Summary
Modifier and TypeMethodDescriptionSealsplaintextforcontext, to open untillifetimefrom now.toString()Returns a description of this sealer's configuration, which names its key IDs but never renders a key.unsealResult(@NonNull String sealed, @NonNull String context) Opens application state once and returns its authenticated plaintext or one undifferentiated rejection.static @NonNull StateSealer.BuilderwithActiveKey(@NonNull SealingKey activeKey) Starts building a sealer that seals withactiveKey.
-
Method Details
-
withActiveKey
Starts building a sealer that seals withactiveKey.- Parameters:
activeKey- the key that seals new values; it also opens them- Returns:
- a new builder
- Throws:
NullPointerException- ifactiveKeyisnull- Since:
- 1.0.0
-
seal
public @NonNull String seal(@NonNull String plaintext, @NonNull String context, @NonNull Duration lifetime) Sealsplaintextforcontext, to open untillifetimefrom 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 emptycontext- the context to bind: 1 to 256 characters of well-formed UTF-16lifetime- 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 isnullIllegalArgumentException- if the context or lifetime is out of range, the plaintext or context contains an unpaired surrogate, or the sealed value would be longer thanStateSealer.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 statecontext- trusted application context- Returns:
- the opening outcome
- Throws:
NullPointerException- if either argument is nullIllegalArgumentException- if the context is invalid- Since:
- 1.0.0
-
toString
-