SecretBytes Class

Definition

Namespace

Bodu.Security.Cryptography

Assembly

Bodu.Security.Cryptography.dll

Package

Bodu.Security.Cryptography 1.2.0

Source

SecretBytes.cs

Provides a disposable holder for sensitive byte material that pins its buffer and zeroes it on disposal.

public sealed class SecretBytes : IDisposable

Inheritance

object

SecretBytes

Implements

IDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

Extension Methods

ComparableExtensions.AtLeast<T>(T, T, IComparer<T>)

ComparableExtensions.AtMost<T>(T, T, IComparer<T>)

ComparableExtensions.IsEqualTo<T>(T, T, IComparer<T>)

ComparableExtensions.Max<T>(T, T, IComparer<T>)

ComparableExtensions.Min<T>(T, T, IComparer<T>)

Examples

// Hold secret key material for the scope of an operation; the pinned buffer is zeroed on dispose.
using SecretBytes key = SecretBytes.Random(32);

// Hand a transient copy to a BCL API that requires a byte[], then erase that copy as well.
byte[] transient = key.ToArray();
try
{
    using var hmac = new HMACSHA256(transient);
    // ... use hmac ...
}
finally
{
    CryptographicOperations.ZeroMemory(transient);
}

Remarks

SecretBytes is a hygiene measure for key material, passwords, and other secrets: the bytes are copied into a buffer allocated on the pinned object heap (so the garbage collector cannot relocate it and leave stale copies behind), the buffer is zeroed by Clear() and Dispose() using ZeroMemory(Span<byte>), and ToString() never reveals the content.

Managed .NET cannot guarantee perfect secrecy: the source data existed in unprotected memory before it was copied in, the runtime or a debugger may copy memory for diagnostics, and the operating system may page memory to disk. Treat this type as defensive hygiene that narrows the exposure window - not as a secure enclave.

This type is not thread-safe; callers coordinate concurrent access and disposal.

Properties

Length

Gets the number of bytes of secret material.

public int Length { get; }

Property Value

int

The buffer length in bytes. Remains readable after disposal, because the length of a secret is not itself secret.

Methods

AsSpan()

Returns a read-only view over the secret bytes.

public ReadOnlySpan<byte> AsSpan()

Returns

ReadOnlySpan<byte>

A read-only span over the buffer.

Remarks

The span aliases the live internal buffer: it observes Clear() and must not be used after Dispose().

Exceptions

ObjectDisposedException

The instance has been disposed.

Clear()

Zeroes the secret bytes while leaving the instance usable.

public void Clear()

Remarks

After clearing, the instance holds all-zero bytes of the original Length.

Exceptions

ObjectDisposedException

The instance has been disposed.

CopyFrom(ReadOnlySpan<byte>)

Creates a SecretBytes instance containing a copy of the provided bytes.

public static SecretBytes CopyFrom(ReadOnlySpan<byte> source)

Parameters

source ReadOnlySpan<byte>

The bytes to copy. An empty span yields an empty instance.

Returns

SecretBytes

A new SecretBytes holding a defensive copy of source.

Remarks

The caller remains responsible for clearing source if it holds the only other copy of the secret; this method cannot erase the original.

Dispose()

Zeroes the secret bytes and marks the instance as disposed.

public void Dispose()

Remarks

Disposal is idempotent. After disposal, Length and ToString() remain usable; all members that reach the secret content throw ObjectDisposedException.

FixedTimeEquals(SecretBytes)

Compares this secret to another in fixed time.

public bool FixedTimeEquals(SecretBytes other)

Parameters

other SecretBytes

The secret to compare against. Must not be null.

Returns

bool

true if both secrets have the same length and identical bytes; otherwise, false.

Exceptions

ArgumentNullException

other is null.

ObjectDisposedException

This instance or other has been disposed.

FixedTimeEquals(ReadOnlySpan<byte>)

Compares this secret to a raw byte sequence in fixed time.

public bool FixedTimeEquals(ReadOnlySpan<byte> other)

Parameters

other ReadOnlySpan<byte>

The bytes to compare against.

Returns

bool

true if other has the same length and identical bytes; otherwise, false.

Exceptions

ObjectDisposedException

The instance has been disposed.

Random(int)

Creates a SecretBytes instance filled with cryptographically secure random bytes.

public static SecretBytes Random(int length)

Parameters

length int

The number of random bytes to generate.

Returns

SecretBytes

A new SecretBytes holding length random bytes.

Exceptions

ArgumentOutOfRangeException

length ≤ 0.

ToArray()

Copies the secret bytes into a new unprotected array.

public byte[] ToArray()

Returns

byte[]

A new array containing the secret bytes.

Remarks

The returned array is an ordinary managed allocation outside this instance's control; callers should zero it (for example with ZeroMemory(Span<byte>)) as soon as it is no longer needed.

Exceptions

ObjectDisposedException

The instance has been disposed.

ToString()

Returns a description of the instance that never includes the secret content.

public override string ToString()

Returns

string

A string of the form "SecretBytes (Length = N)".

Applies to

Product	Versions
.NET	8, 10