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() with pinned: true for allocations. This prevents .NET copying the memory around, allowing proper erasure.

3. Use ZeroMemory() to wipe arrays in a way 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 LockMemory() to try and avoid data swapping to disk.

5. Use guarded heap allocations, which take care of the above plus limit access to the memory at an operating system level. This protects against buffer overflows/underflows and other processes accessing the data.

6. Use a library like memguard (a Go library, but a C# equivalent is in the works) 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.

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

Of these, bullets 1, 2, and 3 are most important.

If going the extra mile, bullet 5 should be used instead of bullets 2, 3, and 4.

Usage

ZeroMemory

Overwrites a byte array with zeros.

SecureMemory.ZeroMemory(Span<byte> buffer)

buffer MUST be pinned for this method to work properly.

Exceptions

ArgumentOutOfRangeException

buffer has a length of 0.

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

ArgumentOutOfRangeException

buffer has a length of 0.

LockMemory

Locks a byte array to try and avoid the contents being swapped to disk.

SecureMemory.LockMemory(ReadOnlySpan<byte> buffer)

buffer MUST be pinned for this method to work properly.

It is RECOMMENDED to use guarded heap allocations instead, which perform memory locking/unlocking for you.

Exceptions

ArgumentOutOfRangeException

buffer has a length that's not a multiple of PageSize.

OutOfMemoryException

Unable to lock memory.

UnlockAndZeroMemory

Overwrites a locked byte array with zeros before unlocking the memory.

SecureMemory.UnlockAndZeroMemory(Span<byte> buffer)

buffer MUST be pinned for this method to work properly.

It is RECOMMENDED to use guarded heap allocations instead, which perform memory locking/unlocking for you.

Exceptions

ArgumentOutOfRangeException

buffer has a length that's not a multiple of PageSize.

InvalidOperationException

Unable to unlock memory.

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.

Exceptions

ArgumentOutOfRangeException

size is less than 1 or greater than MaxSize.

OutOfMemoryException

Unable to allocate memory.

InvalidOperationException

Unable to make memory inaccessible.

InvalidOperationException

Unable to make memory read-only.

InvalidOperationException

Unable to make memory readable and writable.

ObjectDisposedException

The object has been disposed.

Constants

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

// SecureMemory class
public static readonly int PageSize = Environment.SystemPageSize;

// GuardedHeapAllocation class
public static readonly int MaxSize = PageSize - 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 users of your application do the following:

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

• Harden their machine against malware.

• 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.