Class SecureArray<T>

Manage an array that holds sensitive information.

Inheritance

object

SecureArray

SecureArray<T>

Implements

IDisposable

Inherited Members

SecureArray.ReportMaxLockableOnLockFail

SecureArray.DefaultCall

SecureArray.ProtectionType

SecureArray.Call

SecureArray.BuiltInTypeElementSize<T>(T[])

SecureArray.BuiltInTypeElementSize<T>(Span<T>)

SecureArray.Zero<T>(T[], SecureArrayCall)

SecureArray.Zero<T>(Span<T>, SecureArrayCall)

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Namespace: Isopoh.Cryptography.SecureArray

Assembly: Isopoh.Cryptography.SecureArray.dll

Syntax

public sealed class SecureArray<T> : SecureArray, IDisposable

Type Parameters

Name	Description
T	The type of the array. Limited to built in types.

Remarks

You can think of the SecureArray sort of like you would think of SecureString except that SecureString (usually) does crypto to protect its sensitive data and has windows of vulnerability when it decrypts the string for use. SecureArray protects its data by locking the data into RAM to keep it from swapping to disk and also zeroing the buffer when disposed. So, unlike SecureString, any process with access to your process's memory will be able to read the data in your SecureArray, but you do not have to worry about your data persisting anywhere or multiple copies of your data floating around RAM due to C#'s memory management.

Because it locks the memory into RAM (and at a non-movable-by-the-garbage-collector location), you need to use it as infrequently as possible and for as short a time as possible. RAM secured this way puts stress on the computer as a whole by denying physical RAM for other processes and puts stress on your particular executable by denying freedom to the garbage collector to reduce fragmentation as needed for best performance.

Always dispose of your SecureArrays.

Browsers and WebAssembly cannot lock memory against swapping. In those environments, BestEffort falls back to a pinned buffer that is zeroed on disposal. Use IsMemoryLockSupported and ProtectionType to inspect the available and actual protection.

Constructors

SecureArray(int)

Initializes a new instance of the SecureArray<T> class.

Declaration

public SecureArray(int size)

Parameters

Type	Name	Description
int	size	The number of elements in the secure array.

Remarks

Uses SecureArrayType.ZeroedPinnedAndNoSwap and SecureArray.DefaultCall.

SecureArray(int, SecureArrayCall)

Initializes a new instance of the SecureArray<T> class.

Declaration

public SecureArray(int size, SecureArrayCall call)

Parameters

Type	Name	Description
int	size	The number of elements in the secure array.
SecureArrayCall	call	The methods that get called to secure the array. A null value defaults to SecureArray.DefaultCall.

Remarks

Uses SecureArrayType.ZeroedPinnedAndNoSwap.

SecureArray(int, SecureArrayType)

Initializes a new instance of the SecureArray<T> class.

Declaration

public SecureArray(int size, SecureArrayType type)

Parameters

Type	Name	Description
int	size	The number of elements in the secure array.
SecureArrayType	type	The type of secure array to initialize.

Remarks

Uses SecureArray.DefaultCall.

SecureArray(int, SecureArrayType, SecureArrayCall?)

Initializes a new instance of the SecureArray<T> class.

Declaration

public SecureArray(int size, SecureArrayType type, SecureArrayCall? call)

Parameters

Type	Name	Description
int	size	The number of elements in the secure array.
SecureArrayType	type	The type of secure array to initialize.
SecureArrayCall	call	The methods that get called to secure the array. A null value defaults to SecureArray.DefaultCall.

Properties

Buffer

Gets the secure array.

Declaration

public T[] Buffer { get; }

Property Value

Type	Description
T[]

this[int]

Gets or sets elements in the secure array.

Declaration

public T this[int i] { get; set; }

Parameters

Type	Name	Description
int	i	The index of the element.

Property Value

Type	Description
T	The element.

Methods

Best(int, SecureArrayCall?)

Returns the "best" secure array it can. Tries first for ZeroedPinnedAndNoSwap and, if that fails, returns a ZeroedAndPinned secure array.

Declaration

public static SecureArray<T> Best(int size, SecureArrayCall? secureArrayCall)

Parameters

Type	Name	Description
int	size	The number of elements in the returned SecureArray<T>.
SecureArrayCall	secureArrayCall	The methods that get called to secure the array. A null value defaults to SecureArray.DefaultCall.

Returns

Type	Description
SecureArray<T>	A new SecureArray<T>.

Remarks

Whether a no-swap SecureArray<T> can be returned is up to the operating system. You can query ProtectionType to find the type of SecureArray<T> returned.

Create(int, SecureArrayCall?, LockMemoryPolicy)

Returns the "best" secure array it can. Tries first for ZeroedPinnedAndNoSwap and, if that fails, returns a ZeroedAndPinned secure array.

Declaration

public static SecureArray<T> Create(int size, SecureArrayCall? secureArrayCall, LockMemoryPolicy lockMemory = LockMemoryPolicy.BestEffort)

Parameters

Type	Name	Description
int	size	The number of elements in the returned SecureArray<T>.
SecureArrayCall	secureArrayCall	The methods that get called to secure the array. A null value defaults to SecureArray.DefaultCall.
LockMemoryPolicy	lockMemory	Used to set locking strategy for buffers used in creating the hash. The memory will always be zeroed prior to destruction. The memory is also always pinned so the CLR can't move it and leave extraneous copies floating around in RAM.

Returns

Type	Description
SecureArray<T>	A new SecureArray<T>.

Remarks

Whether a no-swap SecureArray<T> can be returned is up to the operating system. You can query ProtectionType to find the type of SecureArray<T> returned.

Dispose()

Zero buffer and release resources.

Declaration

public void Dispose()

Implements

IDisposable