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 zeroes bytes: the buffer handed in is consumed, so the plaintext does not stay behind in it.
factory
TomProtectedValue.of(String secret)
Protects secret. The String handed 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 String accessor — every call site is a place the secret is deliberately read, and the String cannot be wiped afterwards: prefer withRevealed where bytes do.
revealInto(Uint8List target, [int offset = 0]) → void
Writes the plaintext into target at offset; the caller wipes target when 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 use with the plaintext's bytes and zeroes them when it returns or throws. use is 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

Constants

mask → const String
The text every masked rendering of a secret shows.