TomProtectedValue class final
A secret in memory: reveal gives the plaintext, digest identifies it.
The bytes can still be read by a determined caller; what this changes is
where the read is visible. Every place the plaintext leaves the object
is a call to reveal, withRevealed or revealInto, which a reader can
search for, and every place that would leak it by accident — toString()
in a log line, an interpolated map, jsonEncode, a merge comparison —
gets the mask, the digest or an error instead.
The plaintext is kept XOR-ed with a per-instance random salt, so it is not in memory as one contiguous string between reads. Equality is by digest, so "same secret or not" never needs the plaintext.
reveal hands out a String, which no one can overwrite afterwards;
withRevealed and revealInto hand out bytes the caller controls, and
withRevealed zeroes them once the callback returns. dispose zeroes the
masked bytes and the salt; the value can then no longer be read.
Constructors
- TomProtectedValue.fromBytes(Uint8List bytes)
-
Protects
bytes(any bytes: text as UTF-8, or binary) and zeroesbytes: the buffer handed in is consumed, so the plaintext does not stay behind in it.factory - TomProtectedValue.of(String secret)
-
Protects
secret. TheStringhanded in is the caller's to drop.factory
Properties
- digest → String
-
The SHA-256 hex of the plaintext's bytes (a text's UTF-8).
final
- hashCode → int
-
The hash code for this object.
no setteroverride
- isDisposed → bool
-
Whether dispose has run.
no setter
- isEmpty → bool
-
no setter
- length → int
-
The plaintext's length in bytes (a text's UTF-8) — zero for an empty
secret. It stays after dispose.
no setter
- runtimeType → Type
-
A representation of the runtime type of the object.
no setterinherited
Methods
-
dispose(
) → void - Zeroes the masked bytes and the salt. Reading afterwards throws a StateError; digest, length and equality stay. Disposing twice is fine.
-
noSuchMethod(
Invocation invocation) → dynamic -
Invoked when a nonexistent method or property is accessed.
inherited
-
reveal(
) → String -
The plaintext as text (the bytes read as UTF-8). The one
Stringaccessor — every call site is a place the secret is deliberately read, and theStringcannot be wiped afterwards: prefer withRevealed where bytes do. -
revealInto(
Uint8List target, [int offset = 0]) → void -
Writes the plaintext into
targetatoffset; the caller wipestargetwhen it is done with it. Throws RangeError when it does not fit. -
toString(
) → String -
Never the secret: the mask.
override
-
withRevealed<
T> (T use(Uint8List bytes)) → T -
Calls
usewith the plaintext's bytes and zeroes them when it returns or throws.useis synchronous: the bytes exist only for its duration, and it must not keep them.
Operators
-
operator ==(
Object other) → bool -
By digest: two values protecting the same secret are equal.
override