Secure memory

Purpose

If an attacker can retrieve sensitive data, like keys, passwords, and plaintexts, they can effectively bypass the associated cryptography. Therefore, it is recommended to limit the exposure of and protect such sensitive data in memory, reducing the likelihood of it being accessible to attackers.

Here are several steps you should take as a developer:

1. Use byte or char arrays over strings. Strings are immutable, meaning they can't reliably be erased and copies may be made. SecureString is also not worth using.

2. Use stackalloc or GC.AllocateArray<T>() with pinned: true for allocations. This prevents .NET from copying the memory around, allowing proper erasure.

3. Use ZeroMemory() to wipe arrays in a manner that won't be optimised away by the compiler. This should be done as soon as the array is no longer needed and when an exception occurs. For example, you can call this method in a try-finally statement.

4. Use guarded heap allocations, which perform memory locking and limit access to the memory at an operating system level. This protects against data being swapped to disk, buffer overflows/underflows, and other processes accessing the data.

5. Use a library like memguard (a Go library, but a C# equivalent may be made) that encrypts memory whilst using guarded heap allocations. This does all of the above whilst protecting against things like cold boot attacks and speculative execution vulnerabilities.

6. Support using hardware that stores secrets and performs cryptographic operations on your behalf, like YubiKeys.

The first three bullets are the most important.

Usage

ZeroMemory

Overwrites a byte array with zeros.

SecureMemory.ZeroMemory(Span<byte> buffer);

buffer MUST be pinned for this method to work properly.

Exceptions

N/A

ZeroMemory

Overwrites a char array or string with zeros.

SecureMemory.ZeroMemory(ReadOnlySpan<char> buffer);

buffer MUST be pinned for this method to work properly.

Also, calling this function on a string converted to a span may crash the .NET runtime in the future. However, it doesn't currently based on my testing.

Exceptions

N/A

GuardedHeapAllocation

Provides access to guarded heap allocations, which can be used instead of regular allocations for additional security. However, there is a performance penalty, and this functionality SHOULD NOT be used for large amounts of variables/data due to system limits.

// Instead of Span<byte> key = stackalloc byte[32];
using var key = new GuardedHeapAllocation(int size);

// Access the memory
SecureRandom.Fill(key.AsSpan());

// Make the memory inaccessible
key.NoAccess();

// Make the memory read-only
key.ReadOnly();

// Make the memory readable and writable
key.ReadWrite();

// Destroy the secret (done automatically with a using statement)
key.Dispose();

Do NOT assign the AsSpan() return value to a span variable. This is a good way to crash your application. Instead, call AsSpan() every time you want to access the memory.

Similarly, do NOT access the memory after calling NoAccess() or try to write to the memory after calling ReadOnly(). This will immediately crash your application.

Do NOT use this class with multiple threads. If you absolutely have to, you need to use lock statements to avoid exceptions being thrown.

Exceptions

ArgumentOutOfRangeException

size is less than 1 or greater than MaxSize.

InsufficientMemoryException

Insufficient memory for guarded heap allocation.

InvalidOperationException

Error marking memory as inaccessible.

InvalidOperationException

Error marking memory as read-only.

InvalidOperationException

Error marking memory as readable and writable.

InvalidOperationException

Methods cannot be called from multiple threads simultaneously.

ObjectDisposedException

The object has been disposed.

Constants

These are used for validation and/or save you from defining your own constants.

// GuardedHeapAllocation class
public static readonly int MaxSize = Environment.SystemPageSize - 16;

Notes

Guarded heap allocations have the following memory layout, with a few caveats:

• The stored size in the first guard page refers to the canary plus data size rounded up to a multiple of the page size.

• The length of the stored size in the first guard page depends on the platform, as does the page size.

• The canary plus data does not necessarily take up a whole page; there may be padding at the beginning (unused memory) and multiple pages (if the data is large enough).

• The canary is initialized with random bytes, and data is initialized with 0xdb bytes to help catch bugs due to uninitialized data.

• If access protection is not supported on the platform, the last page contains a canary at the beginning, meaning there can be two canaries with the same value surrounding the data. In this scenario, access to guard pages is not restricted.

Guarded heap allocation layout

Guarded heap allocations are not as fast as ordinary allocations and use up a lot more memory. Additionally, there are system limits on how much memory can be locked by a process. Therefore, use them sparingly for small amounts of data and test your application thoroughly.

Memory locking is not guaranteed with guarded heap allocations. For example, it may fail or not be supported on the system, in which case the function continues with no error.

It is RECOMMENDED to use a separate guarded heap allocation for each secret. This is less error-prone whilst offering greater protection and access control.

As well as taking these steps as a developer, you can recommend that users of your application do the following:

• Limit the number of installed/running applications on their machine.

• Harden their machine against malware (e.g., allowlisting, a local firewall, etc).

• Encrypt their OS drive.

• Disable hibernation.

• Disable memory dumps.

• Disable swap files/the swap partition.

Memory locking uses VirtualLock() on Windows and mlock() with madvise() and MADV_DONTDUMP on Unix.

Guarded heap allocations require 3 or 4 extra pages of memory over a typical allocation. Allocations are done with VirtualAlloc() on Windows and mmap() with MAP_NOCORE or posix_memalign() on Unix. VirtualProtect() on Windows and mprotect() on Unix are used for the memory access restrictions.

The protection on Unix is likely superior to on Windows.