Provides the ability to manage the lifetime of memory by pinning buffers to prevent duplicate copies in ram and securely zeroing sensitive data when no longer needed.
namespace NCode.CryptoMemory;
/// <summary>
/// Provides a resource pool that enables reusing instances of byte arrays that are
/// pinned during their lifetime and securely zeroed when returned.
/// </summary>
public static class CryptoPool
{
/// <summary>
/// Retrieves a buffer that is at least the requested length.
/// </summary>
/// <param name="minBufferSize">The minimum length of the buffer needed.</param>
/// <returns>
/// An <see cref="IMemoryOwner{T}"/> that manages the lifetime of the lease.
/// </returns>
public static IMemoryOwner<byte> Rent(
int minBufferSize);
/// <summary>
/// Retrieves a buffer that is at least the requested length.
/// </summary>
/// <param name="minBufferSize">The minimum length of the buffer needed.</param>
/// <param name="isSensitive">Indicates whether the buffer should be pinned during it's lifetime
/// and securely zeroed when returned. When <c>false></c>, this implementation delegates to
/// <c>MemoryPool<byte>.Shared.Rent</c>.</param>
/// <returns>
/// An <see cref="IMemoryOwner{T}"/> that manages the lifetime of the lease.
/// </returns>
public static IMemoryOwner<byte> Rent(
int minBufferSize,
bool isSensitive);
/// <summary>
/// Retrieves a buffer that is at least the requested length.
/// </summary>
/// <param name="minBufferSize">The minimum length of the buffer needed.</param>
/// <param name="buffer">When this method returns, contains the buffer with the exact
/// requested size.</param>
/// <returns>
/// An <see cref="IMemoryOwner{T}"/> that manages the lifetime of the lease.
/// </returns>
public static IMemoryOwner<byte> Rent(
int minBufferSize,
out Span<byte> buffer);
/// <summary>
/// Retrieves a buffer that is at least the requested length.
/// </summary>
/// <param name="minBufferSize">The minimum length of the buffer needed.</param>
/// <param name="isSensitive">Indicates whether the buffer should be pinned during it's lifetime
/// and securely zeroed when returned. When <c>false></c>, this implementation delegates to
/// <c>MemoryPool<byte>.Shared.Rent</c>.</param>
/// <param name="buffer">When this method returns, contains the buffer with the exact
/// requested size.</param>
/// <returns>
/// An <see cref="IMemoryOwner{T}"/> that manages the lifetime of the lease.
/// </returns>
public static IMemoryOwner<byte> Rent(
int minBufferSize,
bool isSensitive,
out Span<byte> buffer);
/// <summary>
/// Retrieves a buffer that is at least the requested length.
/// </summary>
/// <param name="minBufferSize">The minimum length of the buffer needed.</param>
/// <param name="buffer">When this method returns, contains the buffer with the exact
/// requested size.</param>
/// <returns>
/// An <see cref="IMemoryOwner{T}"/> that manages the lifetime of the lease.
/// </returns>
public static IMemoryOwner<byte> Rent(
int minBufferSize,
out Memory<byte> buffer);
/// <summary>
/// Retrieves a buffer that is at least the requested length.
/// </summary>
/// <param name="minBufferSize">The minimum length of the buffer needed.</param>
/// <param name="isSensitive">Indicates whether the buffer should be pinned during it's lifetime
/// and securely zeroed when returned. When <c>false></c>, this implementation delegates to
/// <c>MemoryPool<byte>.Shared.Rent</c>.</param>
/// <param name="buffer">When this method returns, contains the buffer with the exact
/// requested size.</param>
/// <returns>
/// An <see cref="IMemoryOwner{T}"/> that manages the lifetime of the lease.
/// </returns>
public static IMemoryOwner<byte> Rent(
int minBufferSize,
bool isSensitive,
out Memory<byte> buffer);
}
namespace NCode.CryptoMemory;
/// <summary>
/// Provides an implementation of <see cref="MemoryManager{T}"/> that allocates a byte buffer from
/// the heap and securely zeroes the allocated memory when the managed is disposed.
/// </summary>
public class HeapMemoryManager : MemoryManager<byte>
{
/// <summary>
/// Initializes a new instance of the <see cref="HeapMemoryManager"/> class.
/// </summary>
/// <param name="length">The length in bytes of the allocated memory.</param>
/// <param name="zeroOnDispose">Specifies whether the allocated memory should be zeroed when
/// the manager is disposed.</param>
public HeapMemoryManager(int length, bool zeroOnDispose = true);
/// <summary>
/// Gets the memory block handled by this <see cref="MemoryManager{T}"/>.
/// </summary>
public Memory<byte> Memory { get; }
/// <summary>
/// Returns a memory span that wraps the underlying memory buffer.
/// </summary>
public Span<byte> GetSpan();
/// <summary>
/// Returns a handle to the memory that has been pinned and whose address can be taken.
/// </summary>
/// <param name="elementIndex">The offset to the element in the memory buffer at which the
/// returned <see cref="MemoryHandle"/> points.</param>
public MemoryHandle Pin(int elementIndex = 0);
/// <summary>
/// Unpins pinned memory so that the garbage collector is free to move it.
/// </summary>
/// <remarks>
/// Since this <see cref="MemoryManager{T}"/> uses memory from the heap which is already
/// pinned, this implemtation does nothing.
/// </remarks>
public void Unpin();
}
- v1.0.0 - Initial release
- v1.0.1 - Updating readme