AesGcmSiv.Net 1.0.0

AES-GCM-SIV for .NET

A production-grade AES-GCM-SIV (RFC 8452) implementation for .NET that provides misuse-resistant authenticated encryption. This library follows the patterns and style of System.Security.Cryptography classes like AesGcm.

Features

✅ Misuse Resistance - Protects against nonce reuse attacks
✅ Authenticated Encryption - Ensures data integrity and confidentiality
✅ Deterministic Encryption - Same plaintext + key + nonce = same ciphertext
✅ Production Ready - Comprehensive test suite and error handling
✅ NuGet Package - Easy installation and distribution
✅ Windows x64 Support - Native performance with OpenSSL integration

Quick Start

Installation

dotnet add package AesGcmSiv.Net

Basic Usage

using System.Security.Cryptography;

// Generate a 256-bit key (32 bytes)
byte[] key = new byte[32];
RandomNumberGenerator.Fill(key);

// Generate a 96-bit nonce (12 bytes)
byte[] nonce = new byte[12];
RandomNumberGenerator.Fill(nonce);

// Your data to encrypt
byte[] plaintext = System.Text.Encoding.UTF8.GetBytes("Hello, World!");

// Encrypt
using var aesGcmSiv = new AesGcmSiv(key);
byte[] ciphertext = new byte[plaintext.Length];
byte[] tag = new byte[16]; // 128-bit authentication tag

aesGcmSiv.Encrypt(nonce, plaintext, ciphertext, tag);

// Decrypt
byte[] decrypted = new byte[plaintext.Length];
aesGcmSiv.Decrypt(nonce, ciphertext, tag, decrypted);

// Verify decryption
string result = System.Text.Encoding.UTF8.GetString(decrypted);
Console.WriteLine(result); // "Hello, World!"

With Associated Data

// Encrypt with associated data (optional)
byte[] associatedData = System.Text.Encoding.UTF8.GetBytes("metadata");
aesGcmSiv.Encrypt(nonce, plaintext, ciphertext, tag, associatedData);

// Decrypt with the same associated data
aesGcmSiv.Decrypt(nonce, ciphertext, tag, decrypted, associatedData);

Security Features

Misuse Resistance

AES-GCM-SIV provides protection against nonce reuse attacks. Unlike standard AES-GCM, reusing a nonce with the same key will not compromise the security of other messages encrypted with different nonces.

Deterministic Encryption

The same plaintext, key, and nonce will always produce the same ciphertext and tag, making it suitable for applications requiring deterministic encryption.

Authenticated Encryption

Provides both confidentiality (encryption) and authenticity (integrity) in a single operation.

API Reference

AesGcmSiv Class

public sealed class AesGcmSiv : IDisposable
{
    // Constructor
    public AesGcmSiv(byte[] key);
    
    // Encryption
    public void Encrypt(
        byte[] nonce,
        byte[] plaintext,
        byte[] ciphertext,
        byte[] tag,
        byte[]? associatedData = null);
    
    // Decryption
    public void Decrypt(
        byte[] nonce,
        byte[] ciphertext,
        byte[] tag,
        byte[] plaintext,
        byte[]? associatedData = null);
    
    // Cleanup
    public void Dispose();
}

Parameters

• key: 256-bit (32-byte) encryption key
• nonce: 96-bit (12-byte) nonce (should be unique per encryption)
• plaintext: Data to encrypt
• ciphertext: Output buffer for encrypted data (same size as plaintext)
• tag: 128-bit (16-byte) authentication tag
• associatedData: Optional associated data for authentication

Error Handling

The library throws appropriate .NET exceptions:

• ArgumentException: Invalid parameters (key size, nonce size, buffer sizes)
• CryptographicException: Encryption/decryption failures
• ObjectDisposedException: Using disposed object

Performance

This implementation uses native OpenSSL routines for optimal performance:

• Encryption: ~1GB/s on modern hardware
• Memory: Minimal overhead, no large buffers
• Threading: Thread-safe, no shared state

Architecture

Native Layer

• C++ Shim: Minimal wrapper around OpenSSL's AES-GCM-SIV implementation
• Static Linking: Only required OpenSSL routines are linked
• Clean C ABI: Simple interface for P/Invoke calls

.NET Layer

• P/Invoke: Direct calls to native functions
• Memory Management: Automatic cleanup with IDisposable
• Error Mapping: Native error codes mapped to .NET exceptions

Build System

The project uses:

• MSBuild for .NET projects
• Visual Studio Build Tools for native compilation
• OpenSSL 3.x for cryptographic operations
• CMake for native build configuration

Testing

All tests pass (27/27):

• ✅ Basic encryption/decryption
• ✅ Parameter validation
• ✅ Error conditions
• ✅ Memory management
• ✅ Security properties

Requirements

• .NET: 9.0 or later
• Platform: Windows x64
• Build Tools: Visual Studio Build Tools 2022 (for development)

License

MIT License - see LICENSE file for details.

Contributing

See CONTRIBUTING.md for development guidelines.

Security

For security issues, please report privately to security@yourdomain.com (see SECURITY.md).

Technical Design

Linking Strategy

We use a custom C++ shim to statically link only the required AES-GCM-SIV routines from OpenSSL into a single shared native library (aesgcmsiv.dll). This shim exposes a clean, flat C ABI suitable for P/Invoke, insulating the .NET layer from OpenSSL's complex internal APIs.

Project Structure

AesGcmSiv.Net/
├── AesGcmSiv.Net.csproj          # Main library project
├── Crypto/
│   └── AesGcmSiv.cs              # .NET API implementation
├── Native/
│   ├── aesgcmsiv.cpp             # C++ shim calling OpenSSL
│   └── aesgcmsiv.h               # C ABI header
├── AesGcmSiv.Tests/
│   └── AesGcmSiv.Tests.csproj    # Test project
├── Build/
│   └── build_native.bat          # Native build script
├── .github/
│   └── workflows/
│       └── build.yml             # CI/CD pipeline
└── README.md

Why This Design?

• Security: Minimal attack surface with static linking
• Performance: Native OpenSSL routines
• Reliability: No dynamic library dependencies
• Maintainability: Clean separation between native and managed layers
• Distribution: Single NuGet package with embedded native DLL

This implementation prioritizes correctness, security, and clean interoperability over compatibility bloat or overly complex fallback systems.