C# Platform Guide

Overview

MetaMUI.Crypto provides a cryptographic library for .NET applications, supporting .NET 6.0+. Build from source and reference as a local project dependency.

Installation

Build from source:

cd metamui-crypto-csharp
dotnet build

Running Tests

cd metamui-crypto-csharp/MetaMUI.Crypto.Falcon.Tests
dotnet test

Using in Your Project

Reference the project directly in your .csproj:

<ProjectReference Include="../metamui-crypto-csharp/MetaMUI.Crypto.Falcon/MetaMUI.Crypto.Falcon.csproj" />

Or reference the built DLL:

<Reference Include="MetaMUI.Crypto.Falcon">
  <HintPath>../metamui-crypto-csharp/MetaMUI.Crypto.Falcon/bin/Release/net6.0/MetaMUI.Crypto.Falcon.dll</HintPath>
</Reference>

Usage Examples

Basic Hashing with BLAKE3

using MetaMUI.Crypto.Blake3;

// Simple hashing
byte[] data = Encoding.UTF8.GetBytes("Hello, World!");
byte[] hash = Blake3.ComputeHash(data);
Console.WriteLine($"BLAKE3 Hash: {Convert.ToHexString(hash)}");

// Streaming hash
using var hasher = new Blake3Hasher();
hasher.Update(data1);
hasher.Update(data2);
byte[] finalHash = hasher.Finalize();

// Keyed hashing (MAC)
byte[] key = new byte[32];
RandomNumberGenerator.Fill(key);
byte[] mac = Blake3.ComputeKeyedHash(key, data);

Post-Quantum Key Exchange (ML-KEM-768)

using MetaMUI.Crypto.PostQuantum;
using MetaMUI.Crypto.MlKem768;

public class QuantumSafeKeyExchange
{
    public static void DemonstrateKEM()
    {
        // Generate keypair
        var (publicKey, secretKey) = MlKem768.GenerateKeypair();

        // Sender: Encapsulate shared secret
        var (ciphertext, sharedSecretSender) = MlKem768.Encapsulate(publicKey);

        // Receiver: Decapsulate shared secret
        byte[] sharedSecretReceiver = MlKem768.Decapsulate(ciphertext, secretKey);

        // Verify shared secrets match
        bool match = sharedSecretSender.SequenceEqual(sharedSecretReceiver);
        Console.WriteLine($"Shared secrets match: {match}");

        // Use shared secret for symmetric encryption
        using var aes = Aes.Create();
        aes.Key = sharedSecretSender;
    }
}

Authenticated Encryption (ChaCha20-Poly1305)

using MetaMUI.Crypto.ChaCha20Poly1305;

public class SecureMessaging
{
    public static (byte[] ciphertext, byte[] tag) Encrypt(
        byte[] plaintext,
        byte[] key,
        byte[] nonce,
        byte[] associatedData = null)
    {
        using var cipher = new ChaCha20Poly1305(key);

        byte[] ciphertext = new byte[plaintext.Length];
        byte[] tag = new byte[16];

        cipher.Encrypt(nonce, plaintext, ciphertext, tag, associatedData);

        return (ciphertext, tag);
    }

    public static byte[] Decrypt(
        byte[] ciphertext,
        byte[] tag,
        byte[] key,
        byte[] nonce,
        byte[] associatedData = null)
    {
        using var cipher = new ChaCha20Poly1305(key);

        byte[] plaintext = new byte[ciphertext.Length];

        cipher.Decrypt(nonce, ciphertext, tag, plaintext, associatedData);

        return plaintext;
    }
}

Digital Signatures with Dilithium

using MetaMUI.Crypto.PostQuantum;

public class QuantumSafeSignatures
{
    public static void DemonstrateSignatures()
    {
        // Generate signing keypair
        var (publicKey, privateKey) = Dilithium3.GenerateKeypair();

        // Sign a message
        byte[] message = Encoding.UTF8.GetBytes("Important document");
        byte[] signature = Dilithium3.Sign(message, privateKey);

        // Verify signature
        bool valid = Dilithium3.Verify(message, signature, publicKey);
        Console.WriteLine($"Signature valid: {valid}");

        // Secure key disposal
        privateKey.SecureDispose();
    }
}

Password Hashing with Argon2id

using MetaMUI.Crypto.Argon2;

public class PasswordManager
{
    public static string HashPassword(string password)
    {
        // Generate salt
        byte[] salt = new byte[16];
        RandomNumberGenerator.Fill(salt);

        // Hash with Argon2id
        var hasher = new Argon2id
        {
            Salt = salt,
            MemorySize = 65536,  // 64 MB
            Iterations = 4,
            DegreeOfParallelism = 2
        };

        byte[] hash = hasher.ComputeHash(Encoding.UTF8.GetBytes(password));

        // Return encoded string (includes parameters)
        return hasher.GetEncodedString();
    }

    public static bool VerifyPassword(string password, string encodedHash)
    {
        return Argon2id.Verify(encodedHash, password);
    }
}

Async Operations

using MetaMUI.Crypto.Async;

// Async hashing for large files
public async Task<byte[]> HashLargeFileAsync(string filePath)
{
    using var stream = File.OpenRead(filePath);
    return await Blake3.ComputeHashAsync(stream);
}

// Async encryption
public async Task<byte[]> EncryptAsync(byte[] data, byte[] key)
{
    return await Task.Run(() =>
    {
        using var cipher = new ChaCha20Poly1305(key);
        // Perform encryption
        return encryptedData;
    });
}

Secure Memory Management

using MetaMUI.Crypto.Security;

// Secure string handling
using (var secureString = new SecureString())
{
    foreach (char c in password)
        secureString.AppendChar(c);

    // Use secure string
    byte[] key = SecureStringUtils.DeriveKey(secureString);

    // Automatic secure disposal
}

// Secure byte arrays
using (var secureBytes = new SecureByteArray(32))
{
    RandomNumberGenerator.Fill(secureBytes.Buffer);
    // Use secure bytes
    // Automatically zeroed on disposal
}

Dependency Injection

// Startup.cs or Program.cs
builder.Services.AddMetaMUICrypto(options =>
{
    options.EnableHardwareAcceleration = true;
});

// In your service
public class CryptoService
{
    private readonly IHashProvider _hashProvider;
    private readonly IKemProvider _kemProvider;

    public CryptoService(IHashProvider hashProvider, IKemProvider kemProvider)
    {
        _hashProvider = hashProvider;
        _kemProvider = kemProvider;
    }

    public byte[] HashData(byte[] data)
    {
        return _hashProvider.ComputeHash(HashAlgorithm.Blake3, data);
    }
}

Platform Support

Framework Version Support
.NET 8.0 Latest Full
.NET 7.0 Latest Full
.NET 6.0 LTS Full
.NET Standard 2.1 - Full

Error Handling

try
{
    var result = MlKem768.Encapsulate(publicKey);
}
catch (CryptographicException ex)
{
    // Handle crypto-specific errors
    Logger.LogError($"Cryptographic error: {ex.Message}");
}
catch (InvalidKeyException ex)
{
    // Handle key-related errors
    Logger.LogError($"Invalid key: {ex.Message}");
}

Support Resources

C Guide Go Guide