CryptoUtility.System 0.29.0

🔐 CryptoUtility

Cryptography, Simplified & Unified.
A developer-first cryptography abstraction library for .NET. Secure your data with state-of-the-art ciphers using a single, unified interface.

❓ Why CryptoUtility?

CryptoUtility makes it quick, simple, and easy to work with cryptography.

We provide commonly requested utilities like Base64 support, easy key generation, unified interfaces that make it easy to swap implementations, or abstract dependencies, and provide backwards compatible implementations for common cryptographic operations.

CryptoUtility enables access to an entire ecosystem; no longer requiring you to learn different crypto APIs for different libraries. In our library, using an authenticated cipher is just as simple and easy as a stateless cipher. You no longer have to manage IDisposable objects and risk memory leaks as our wrappers deal with them.

This keeps your focus where it belongs: writing your application.

⚡ State-of-the-Art Security, Simple APIs

With CryptoUtility, executing high-security authenticated encryption (AEAD) like AES-256-GCM or ChaCha20-Poly1305 is just as straightforward as running a stateless cipher. All complex logic—such as secure nonce generation, authentication tag handling, and associated data verification—is managed automatically.

🧩 Unified Interfaces

We define clean, unified interfaces like ISymmetricCipher, IAsymmetricCipher, IKeyEncapsulationMechanism, IKeyAgreement, IDigitalSignature, IPasswordHasher, IHashProvider, IMacProvider, IKeyExpansionKdf, and IPasswordKdf.

This is incredibly powerful for building modular application systems (such as a SaveManager or a networking layer). Your high-level managers can depend directly on ISymmetricCipher without being bound to a concrete implementation. You can swap your entire encryption algorithm from AES to ChaCha20 with a single line of code, without rewriting your business logic.

📦 Automatic Encrypted and Decrypted Payload Formatting

For symmetric ciphers and hybrid encryption, CryptoUtility automatically packages the encrypted payload, random nonce, and authentication tag into a raw binary format under the hood (zero-overhead, no external serialization dependencies).

You receive a single, ready-to-transmit encrypted byte array or Base64 string. During decryption, the encrypted data is parsed and decrypted automatically.

♻️ Cached Instances

To completely avoid allocations, we provide a <Algo>.Shared cached instance.

This allows you to leverage instance-based APIs continuously without the overhead of instantiating new objects for every cryptographic operation.

🧣 Static Wrapper API

All of our instance APIs are also wrapped with a static API, allowing direct usage of your desired algoithm for brevity, and convenience.

🗺️ One API, Every Implementation

Instead of learning a dozen distinct libraries, paradigms, and syntax patterns for different cryptographic requirements, you only need to learn CryptoUtility. As the project grows, it will continue to expand into a rich ecosystem of supported algorithms and third-party wrappers, giving you a singular, unified gateway to the entire modern cryptographic landscape.

✨ Features

• Unified API Design: Identical syntax patterns for encryption, decryption, signatures, key agreement, hashing, and encapsulation.
• Built-in Utilities: Out-of-the-box helper methods for seamless Base64 string operations, easy key generation using Cipher.GenerateKey(), and backwards compatible cryptographic operations.
• Symmetric Encryption (AEAD): Modern standards including AES-256-GCM, ChaCha20-Poly1305, and more.
• Hybrid Encryption: Encrypt large payloads easily using RSA public keys combined with the speed of AES-256-GCM under the hood.
• Asymmetric & Signatures: Full support for RSA, and elliptic curve digital signatures (ECDSA).
• Post-Quantum Cryptography (PQC): Modern quantum-resistant algorithms for key encapsulation (ML-KEM, BIKE, HQC) and signatures (ML-DSA, SLH-DSA, FALCON).
• Key Agreement & KEM: Establish secure session keys over open channels using ECDH or post-quantum KEMs.
• Hashing, Checksums & Password Storage: SHA-2/3, Blake2/3, SM3, variable-length SHAKE, fast integrity check checksums (CRC-32/64, xxHash32/64/128), and standard PHC password storage hashing (Argon2, Scrypt, Bcrypt, PBKDF2).
• MAC Providers: Verify against message tampering by generating a Message Authentication Code (MAC) (including Blake Keyed MACs, HmacSM3, KMAC, GMAC, and Poly1305) and verifying it against the incoming message.

🚀 Getting Started

All primary APIs return direct values and bubble up exceptions natively if an error occurs.

1️⃣ Symmetric Encryption (AES-256-GCM)

🔤 Base64 String Workflow

using CryptoUtility.System;

// 1. Generate a secure, random key as a Base64 string
string base64Key = Aes256Gcm.GenerateKeyBase64();

// 2. Encrypt plaintext directly into a self-contained Base64 string
string plaintext = "Confidential customer details...";
string encrypted = Aes256Gcm.EncryptBase64(base64Key, plaintext);

// 3. Decrypt with a single call directly to value
string decryptedText = Aes256Gcm.DecryptBase64(base64Key, encrypted);
Console.WriteLine($"Decrypted: {decryptedText}"); // Confidential customer details...

📦 Byte Array Workflow

using CryptoUtility.System;

// 1. Generate key and plaintext bytes
byte[] key = Aes256Gcm.GenerateKey();
byte[] plaintext = "Hello World"u8.ToArray();

// 2. Encrypt and Decrypt directly
byte[] encrypted = Aes256Gcm.Encrypt(key, plaintext);
byte[] decrypted = Aes256Gcm.Decrypt(key, encrypted);

2️⃣ Asymmetric Encryption/Decryption

🔤 Static-based Workflow (RSA-4096)

using CryptoUtility.System;

// 1. Generate an RSA KeyPair
var (publicKey, privateKey) = Rsa4096.GenerateKeyPair();

// 2. Encrypt plaintext with the public key
byte[] plaintext = "Secret message"u8.ToArray();
byte[] encrypted = Rsa4096.Encrypt(publicKey, plaintext);

// 3. Decrypt ciphertext with the private key
byte[] decrypted = Rsa4096.Decrypt(privateKey, encrypted);

🧩 Interface-based Workflow (IAsymmetricCipher)

using CryptoUtility;
using CryptoUtility.System;

// 1. Resolve implementation instance (e.g. RSA-2048)
IAsymmetricCipher asymmetric = Rsa2048.Shared;

// 2. Generate a key pair
var (publicKey, privateKey) = asymmetric.GenerateKeyPair();

// 3. Encrypt data with the public key
byte[] plaintext = "Confidential data payload"u8.ToArray();
byte[] encrypted = asymmetric.Encrypt(publicKey, plaintext);

// 4. Decrypt data with the private key
byte[] decrypted = asymmetric.Decrypt(privateKey, encrypted);

3️⃣ Hybrid Asymmetric Encryption (Classical & Post-Quantum)

🔤 Classical Hybrid Encryption (RSA-4096 + AES)

using CryptoUtility.System;

// Generate public/private keypair
var (publicKey, privateKey) = Rsa4096.GenerateKeyPairBase64();

// Encrypt payload using the PUBLIC key
string largePayload = "Highly confidential PDF database dump...";
string encrypted = Rsa4096.HybridEncryptBase64(Aes256Gcm.Shared, publicKey, largePayload);

// Decrypt payload using the PRIVATE key
string decrypted = Rsa4096.HybridDecryptBase64(Aes256Gcm.Shared, privateKey, encrypted);

🛡️ Hybrid Post-Quantum Asymmetric Encryption (ML-KEM-768 + RSA-2048 + AES-256-GCM)

Because classical asymmetric algorithms like RSA-2048 are vulnerable to Shor's algorithm, a hybrid post-quantum approach combines a classical asymmetric cipher with a post-quantum KEM. This ensures that the system remains secure even if one of the underlying mathematical problems is solved.

using CryptoUtility;
using CryptoUtility.BouncyCastle;

// 1. Recipient generates both RSA-2048 and ML-KEM-768 key pairs
IAsymmetricCipher rsa = Rsa2048.Shared;
IKeyEncapsulationMechanism kem = MlKem768.Shared;

var (rsaPub, rsaPriv) = rsa.GenerateKeyPair();
var (kemPub, kemPriv) = kem.GenerateKeyPair();

// 2. Sender side: Encrypt a message to recipient
byte[] plaintext = "Highly secure hybrid PQ-classical message."u8.ToArray();
byte[] hybridInfo = "PQ-Asymmetric-RSA-2048-Hybrid"u8.ToArray();

// Perform hybrid encryption
byte[] encrypted = kem.HybridEncrypt(
    rsa,
    Aes256Gcm.Shared,
    Hkdf.Shared,
    kemPub,
    rsaPub,
    plaintext,
    hybridInfo
);

// 3. Recipient side: Decrypt the message
byte[] decrypted = kem.HybridDecrypt(
    rsa,
    Aes256Gcm.Shared,
    Hkdf.Shared,
    kemPriv,
    rsaPriv,
    encrypted,
    hybridInfo
);

4️⃣ Digital Signatures (ECDSA & ML-DSA)

🔤 Static-based Workflow (ECDSA)

using CryptoUtility.System;

// 1. Generate an ECDSA KeyPair
var (publicKey, privateKey) = Ecdsa.GenerateKeyPair();

// 2. Sign message bytes with the private key
byte[] message = "Message to sign"u8.ToArray();
byte[] signature = Ecdsa.Sign(message, privateKey);

// 3. Verify signature with the public key
bool isValid = Ecdsa.Verify(message, signature, publicKey);

🧩 Interface-based Workflow (IDigitalSignature - ML-DSA)

using CryptoUtility;
using CryptoUtility.BouncyCastle;

// 1. Get the digital signature instance (e.g. ML-DSA-44 or Falcon-512)
IDigitalSignature dsa = MlDsa44.Shared;

// 2. Generate a key pair
var (publicKey, privateKey) = dsa.GenerateKeyPair();

// 3. Sign the message
byte[] message = "Verify this message authenticity"u8.ToArray();
byte[] signature = dsa.Sign(message, privateKey);

// 4. Verify the signature
bool isValid = dsa.Verify(message, signature, publicKey);

5️⃣ Key Agreement (ECDH)

using CryptoUtility.System;

// 1. Establish KeyPairs for Alice and Bob
var (alicePub, alicePriv) = Ecdh.GenerateKeyPair();
var (bobPub, bobPriv) = Ecdh.GenerateKeyPair();

// 2. Alice and Bob derive the SAME shared secret
byte[] aliceSecret = Ecdh.DeriveSharedSecret(alicePriv, bobPub);
byte[] bobSecret = Ecdh.DeriveSharedSecret(bobPriv, alicePub);

// 3. Configure KDF parameters for session security
byte[] kdfSalt = "session-salt"u8.ToArray();
byte[] kdfInfo = "session-context-info"u8.ToArray();

// 4. Encrypt and Decrypt using derived secrets
byte[] encrypted = Ecdh.Encrypt(Aes256Gcm.Shared, Hkdf.Shared, aliceSecret, "Hi Bob!"u8.ToArray(), kdfSalt, kdfInfo);
byte[] decrypted = Ecdh.Decrypt(Aes256Gcm.Shared, Hkdf.Shared, bobSecret, encrypted, kdfSalt, kdfInfo);

6️⃣ Hashing & Checksums

using CryptoUtility.System;

byte[] data = "Hash this string"u8.ToArray();

// Compute SHA-256 hash
byte[] hash = Sha256.Hash(data);

// Compute Base64 representation directly
string base64Hash = Sha256.HashBase64("Hash this string");

7️⃣ Message Authentication Code (HMAC-SHA256)

using CryptoUtility.System;

// 1. Generate a random MAC key
string macKey = HmacSha256.GenerateKeyBase64();

// 2. Compute the MAC tag
string message = "Authenticate me";
string macTag = HmacSha256.ComputeMacBase64(macKey, message);

// 3. Verify the MAC tag
bool isValid = HmacSha256.VerifyBase64(macKey, message, macTag);

8️⃣ Key Derivation Functions (KDF)

🔑 Key Expansion (HKDF)

using CryptoUtility.System;

byte[] inputKeyMaterial = "master-key-material"u8.ToArray();
byte[] salt = "hkdf-salt-example"u8.ToArray();
byte[] info = "application-context-example"u8.ToArray();

// Expand key to 32 bytes using secure defaults
byte[] expandedKey = Hkdf.DeriveKey(inputKeyMaterial, outputLength: 32, salt, info);

🔒 Password-Based Key Derivation (PBKDF2)

using CryptoUtility.System;

string password = "UserPassword123!";
byte[] salt = "user-specific-salt"u8.ToArray();

// Derive a 32-byte key using secure defaults
byte[] derivedKey = Pbkdf2.DeriveKey(password, salt, outputLength: 32);

9️⃣ Post-Quantum Key Encapsulation (ML-KEM)

🧩 Key Encapsulation Mechanism (IKeyEncapsulationMechanism)

using CryptoUtility;
using CryptoUtility.BouncyCastle;

// 1. Get the KEM instance (e.g. ML-KEM-768)
IKeyEncapsulationMechanism kem = MlKem768.Shared;

// 2. Generate a key pair for the recipient
var (publicKey, secretKey) = kem.GenerateKeyPair();

// 3. Sender encapsulates a shared secret using the recipient's public key
var (senderSecret, ciphertext) = kem.Encapsulate(publicKey);

// 4. Recipient decapsulates the ciphertext using their private key to recover the shared secret
byte[] recipientSecret = kem.Decapsulate(secretKey, ciphertext);

// Both senderSecret and recipientSecret are identical 256-bit symmetric keys

🔐 Post-Quantum Symmetric Encryption (KEM + AES-256-GCM)

AES-256-GCM is symmetric encryption, which is quantum-safe. To perform post-quantum symmetric encryption/decryption, we first use a post-quantum KEM (like ML-KEM-768) to establish a 256-bit shared key, and then use that key to encrypt the payload with AES-256-GCM:

using CryptoUtility;
using CryptoUtility.BouncyCastle;
using CryptoUtility.System;

// 1. Recipient generates a post-quantum ML-KEM key pair
IKeyEncapsulationMechanism kem = MlKem768.Shared;
var (publicKey, secretKey) = kem.GenerateKeyPair();

byte[] salt = "KEM-Salt"u8.ToArray();
byte[] info = "KEM-Info"u8.ToArray();
byte[] plaintext = "Post-quantum secure message payload"u8.ToArray();

// 2. Sender encrypts the message using recipient's public key
byte[] encrypted = kem.Encrypt(
    Aes256Gcm.Shared,
    Hkdf.Shared,
    publicKey,
    plaintext,
    salt,
    info
);

// 3. Recipient decrypts the message using their private key
byte[] decrypted = kem.Decrypt(
    Aes256Gcm.Shared,
    Hkdf.Shared,
    secretKey,
    encrypted,
    salt,
    info
);

if (Aes256Gcm.TryEncrypt(key, plaintext, out byte[] encrypted)) {
    // Encryption succeeded
}

🧪 Sample

View the sample to see all the features in use, you can also run the pre-compiled sample binary to see the execution results.

📚 Cryptography API Reference

Symmetric Encryption (AEAD — Recommended)

Symmetric Encryption (Non-AEAD)

Asymmetric & Hybrid Encryption

Post-Quantum Key Encapsulation Mechanisms (KEM)

Digital Signatures

Key Agreement

Key Derivation Functions

Password Hashing & Key Derivation (PHC Storage)

Hashing & Checksums

Cryptographic Hashes

Non-Cryptographic Hashes & Checksums

Message Authentication Code (MAC)

📦 Raw Binary Formats & Password Storage Formats

CryptoUtility provides consistent raw byte structures across all packages for seamless integration:

1. Symmetric Encryption Layouts

AEAD Ciphers (AES-GCM, ARIA-GCM, Camellia-GCM, ChaCha20-Poly1305)

+-------------------+-----------------------------+-----------------------+
|   Nonce (N bytes) |   Ciphertext (C bytes)      |  Auth Tag (T bytes)   |
+-------------------+-----------------------------+-----------------------+

Non-AEAD Ciphers (ChaCha20, Salsa20, XOR Obfuscation)

+-------------------+-----------------------------+
|   Nonce (N bytes) |   Ciphertext (C bytes)      |
+-------------------+-----------------------------+

2. Hybrid Asymmetric Encryption Layout

+---------------------------------+------------------------+------------------------+
| AsymEncrypted Length (4 bytes)  | AsymEncrypted Payload  | SymEncrypted Payload   |
+---------------------------------+------------------------+------------------------+

3. Hybrid Post-Quantum Asymmetric Encryption Layout

Used by HybridPostQuantumCipherEnvelope to package both classical and post-quantum payloads:

+----------------------+------------------------+-------------------+------------------------+----------------------+
| KEM Length (4 bytes) | Asym Length (4 bytes)  | KEM Ciphertext    | AsymEncrypted Payload  | SymEncrypted Payload |
+----------------------+------------------------+-------------------+------------------------+----------------------+

4. Nonce-Based MAC Tag Layout (GMAC, Poly1305)

+-------------------+-----------------------------+
|   Nonce (N bytes) |   Auth Tag (T bytes)        |
+-------------------+-----------------------------+

5. Password Hashing PHC Formats

CryptoUtility formats hashed passwords into standard PHC strings for database storage:

• Argon2 (d/i/id): $argon2id$v=19$m=<memory>,t=<iterations>,p=<parallelism>$<salt-base64>$<hash-base64>
• Scrypt: $scrypt$ln=<N>,r=<r>,p=<p>$<salt-base64>$<hash-base64>
• Bcrypt: Standard Modular Crypt Format (e.g. $2b$<cost>$<salt><hash>)
• PBKDF2: $pbkdf2-sha256$i=<iterations>$<salt-base64>$<hash-base64>

📝 API Notes

The core CryptoUtility package contains only the contracts, serialization models, and utilities. The individual extension packages contain implementations built upon the core contracts.

Official .NET implementations are recommended, as they are usually hardware accelerated, and have the best support, but they typically have less platform support, which is important if your on an older version of .NET; such as Unity developers, in those cases consider BouncyCastle or a purpose specific library that offers the implementation you need.

Over time the goal of this library is to support and unify all the popular cryptographic concepts and implementations.

🗺️ Disambiguation

To maintain API brevity, this library has opted for all algorithm classes to use the same name, and are intended to be disambiguated through namespaces, and namespace aliases.

🛡️ Security Best Practices

• No Static Nonces: CryptoUtility generates a unique, cryptographically secure random nonce for every single symmetric encryption.
• Authentication-First: We default to AEAD (Authenticated Encryption with Associated Data) ciphers to prevent bit-flipping and padding oracle attacks.
• Memory Sanitation: Sensitive derived keys are zeroed out of system memory immediately after use.
• Standard Implementations: We do not roll custom cryptographic algorithms. We wrap standard, industry-vetted implementations, except where one is not available.

📦 Installation

Add the NuGet package to your project:

dotnet add package CryptoUtility

📜 Full package list:

• CryptoUtility
• CryptoUtility.System
• CryptoUtility.System.Extras
• CryptoUtility.BouncyCastle
• CryptoUtility.HkdfStandard
• CryptoUtility.NaCl
• CryptoUtility.Extras

📄 License

This project is licensed under the MIT License. See LICENSE.md for details.