NCode.CryptoMemory 2.3.0

NCode.CryptoMemory

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. Also provides secure encodings that throw an exception when invalid bytes are encountered.

References

• Pinned Object Heap (POH)
• Character Encoding with Exception Fallback

API

SecureEncoding

namespace NCode.CryptoMemory;

/// <summary>
/// Provides secure encodings that throw an exception when invalid bytes are encountered.
/// </summary>
public static class SecureEncoding
{
    /// <summary>
    /// Gets an ASCII encoding that throws an exception when invalid bytes are encountered.
    /// </summary>
    public static ASCIIEncoding ASCII { get; }

    /// <summary>
    /// Gets a UTF-8 encoding that throws an exception when invalid bytes are encountered.
    /// </summary>
    public static UTF8Encoding UTF8 { get; }
}

CryptoPool

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>
    /// <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&lt;byte&gt;.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="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&lt;byte&gt;.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
    );
}

SecureBufferWriter

namespace NCode.CryptoMemory;

/// <summary>
/// Provides a secure buffer writer that uses <see cref="SecureMemoryPool{T}"/> for memory allocation,
/// ensuring sensitive data is securely managed and cleared when disposed.
/// </summary>
public class SecureBufferWriter<T> : IBufferWriter<T>, IDisposable
{
    /// <summary>
    /// Gets the length of the written data.
    /// </summary>
    public long Length { get; }

    /// <summary>
    /// Gets the written data as a read-only sequence.
    /// </summary>
    public ReadOnlySequence<T> AsReadOnlySequence { get; }

    /// <summary>
    /// Disposes the buffer writer and releases all associated memory.
    /// </summary>
    public void Dispose();

    /// <summary>
    /// Advances the writer by the specified number of elements.
    /// </summary>
    /// <param name="count">The number of elements written.</param>
    public void Advance(int count);

    /// <summary>
    /// Returns a <see cref="Span{T}"/> to write to that is at least the requested size.
    /// </summary>
    /// <param name="sizeHint">The minimum length of the returned span. If 0, a non-empty buffer is returned.</param>
    /// <returns>A span of at least <paramref name="sizeHint"/> in length.</returns>
    public Span<T> GetSpan(int sizeHint = 0);

    /// <summary>
    /// Returns a <see cref="Memory{T}"/> to write to that is at least the requested size.
    /// </summary>
    /// <param name="sizeHint">The minimum length of the returned memory. If 0, a non-empty buffer is returned.</param>
    /// <returns>A memory block of at least <paramref name="sizeHint"/> in length.</returns>
    public Memory<T> GetMemory(int sizeHint = 0);
}

RefSpanLease

namespace NCode.CryptoMemory;

/// <summary>
/// Represents a ref struct that holds a leased <see cref="ReadOnlySpan{T}"/> and manages the lifetime of its underlying owner.
/// When disposed, the owner is also disposed, releasing the leased memory back to its source.
/// </summary>
/// <typeparam name="T">The type of elements in the span.</typeparam>
public readonly ref struct RefSpanLease<T> : IDisposable
{
    /// <summary>
    /// Gets the leased <see cref="ReadOnlySpan{T}"/>.
    /// </summary>
    public ReadOnlySpan<T> Span { get; }

    /// <summary>
    /// Disposes the underlying owner, releasing the leased memory back to its source.
    /// </summary>
    public void Dispose();
}

SequenceExtensions

namespace NCode.CryptoMemory;

/// <summary>
/// Provides extension methods for <see cref="Sequence{T}"/> to enable secure memory operations.
/// </summary>
public static class SequenceExtensions
{
    /// <summary>
    /// Gets a <see cref="RefSpanLease{T}"/> that provides access to the underlying data as a contiguous <see cref="ReadOnlySpan{T}"/>.
    /// If the sequence is a single segment, the span is returned directly without allocation. Otherwise, the data is copied to a rented buffer from the crypto pool.
    /// </summary>
    /// <typeparam name="T">The type of elements in the sequence.</typeparam>
    /// <param name="sequence">The sequence to convert.</param>
    /// <param name="isSensitive">
    /// <see langword="true"/> if the data is sensitive and should be securely cleared when disposed; otherwise, <see langword="false"/>.
    /// </param>
    /// <returns>
    /// A <see cref="RefSpanLease{T}"/> that provides access to the sequence data as a contiguous span.
    /// The caller must dispose the lease to release the underlying resources.
    /// </returns>
    public static RefSpanLease<T> GetSpanLease<T>(this Sequence<T> sequence, bool isSensitive);
}

RefFixedBufferWriter

namespace NCode.CryptoMemory;

/// <summary>
/// A high-performance ref struct implementation of <see cref="IBufferWriter{T}"/> that writes to a fixed-size buffer.
/// Unlike growable buffer writers, this implementation cannot resize and will throw if the buffer capacity is exceeded.
/// </summary>
/// <typeparam name="T">The type of elements in the buffer.</typeparam>
public ref struct RefFixedBufferWriter<T> : IBufferWriter<T>
{
    /// <summary>
    /// Gets the total capacity of the underlying buffer.
    /// </summary>
    public int Capacity { get; }

    /// <summary>
    /// Gets the number of elements that have been written to the buffer.
    /// </summary>
    public int WrittenCount { get; }

    /// <summary>
    /// Gets the amount of free space remaining in the buffer.
    /// </summary>
    public int FreeCapacity { get; }

    /// <summary>
    /// Gets a <see cref="ReadOnlySpan{T}"/> of the data that has been written to the buffer.
    /// </summary>
    public ReadOnlySpan<T> WrittenSpan { get; }

    /// <summary>
    /// Clears the written data by resetting the write position to zero.
    /// Does not clear the underlying buffer contents.
    /// </summary>
    public void Clear();

    /// <summary>
    /// Resets the buffer writer by clearing all written data and zeroing out the underlying buffer.
    /// Use this method when the buffer may contain sensitive data that should be securely cleared.
    /// </summary>
    public void Reset();

    /// <summary>
    /// Advances the write position by the specified count.
    /// </summary>
    /// <param name="count">The number of elements that have been written to the buffer.</param>
    public void Advance(int count);

    /// <summary>
    /// Returns a <see cref="Span{T}"/> to write to that is at least the requested size.
    /// </summary>
    /// <param name="sizeHint">The minimum length of the returned span. If 0, a non-empty buffer is returned if space is available.</param>
    /// <returns>A span representing the available space for writing.</returns>
    public Span<T> GetSpan(int sizeHint = 0);

    /// <summary>
    /// This method is not supported. Use <see cref="GetSpan"/> instead.
    /// </summary>
    public Memory<T> GetMemory(int sizeHint = 0);
}

SpanExtensions

namespace NCode.CryptoMemory;

/// <summary>
/// Provides extension methods for <see cref="Span{T}"/> to enable buffer writing operations.
/// </summary>
public static class SpanExtensions
{
    /// <summary>
    /// Creates a <see cref="RefFixedBufferWriter{T}"/> that writes to this span.
    /// </summary>
    /// <typeparam name="T">The type of elements in the span.</typeparam>
    /// <param name="span">The span to write to.</param>
    /// <returns>A <see cref="RefFixedBufferWriter{T}"/> that can be used to write data to the span.</returns>
    public static RefFixedBufferWriter<T> GetFixedBufferWriter<T>(this Span<T> span);
}

Release Notes

• v1.0.0 - Initial release
• v1.0.1 - Updating readme
• v2.0.0 - Net8 upgrade. Refactored to use SecureMemoryPool. Added SecureEncoding. Removed HeapMemoryManager.
• v2.1.0 - Net10 upgrade. Added SecureBufferWriter.
• v2.1.1 - Fixing CI build
• v2.2.0 - Added RefSpanLease and SequenceExtensions for secure span operations on sequences.
• v2.3.0 - Added RefFixedBufferWriter and SpanExtensions for high-performance fixed-size buffer writing.