SecureString class
A secure container for sensitive strings that overwrites content on dispose.
Since Dart strings are immutable, the string is stored as UTF-8 encoded bytes in a Uint8List which can be overwritten with zeros.
Security note: The Dart VM's garbage collector may copy or relocate byte arrays in memory. While dispose zero-fills the current buffer, previous GC copies cannot be wiped from Dart. On Android/iOS the native platform channel provides stronger guarantees. On other platforms (Web, desktop) the wipe is best-effort only.
To minimise leakage, prefer useOnce over repeated value access, because every call to value creates a new immutable Dart String that cannot be wiped.
Important: You MUST call dispose when done, or use useOnce for one-time-use secrets.
final secret = SecureString('my-api-key');
print(secret.value); // 'my-api-key'
secret.dispose();
// secret.value now throws StateError
- Implemented types
Constructors
- SecureString(String value, {Duration? maxAge})
-
Creates a SecureString containing the given
value.
Properties
- createdAt → DateTime
-
When this secure string was created.
final
- hashCode → int
-
The hash code for this object.
no setterinherited
- id → String
-
The internal identifier for platform channel operations.
no setter
- isDisposed → bool
-
Whether this container has been disposed.
no setter
- length → int
-
The length of the original string.
no setter
- maxAge → Duration?
-
Optional maximum age before auto-disposal.
final
- runtimeType → Type
-
A representation of the runtime type of the object.
no setterinherited
- value → String
-
Returns the stored string value.
no setter
Methods
-
dispose(
) → void -
Disposes this container, overwriting internal bytes with zeros.
override
-
matches(
String other) → bool -
Compares
otherto the stored value using constant-time comparison. -
noSuchMethod(
Invocation invocation) → dynamic -
Invoked when a nonexistent method or property is accessed.
inherited
-
toString(
) → String -
A string representation of this object.
inherited
-
useOnce<
T> (T action(String value)) → T -
Executes
actionwith the value, then immediately disposes.
Operators
-
operator ==(
Object other) → bool -
The equality operator.
inherited