CryptoUtility.NaCl 0.14.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?

Standard cryptography APIs are notoriously complex, boilerplate-heavy, and easy to misconfigure. Because of this, developers often default to older, less secure options like AES-CBC simply because modern authenticated ciphers like AES-GCM are harder to set up.

CryptoUtility bridges this gap by offering:

⚡ 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, IHashProvider, IKeyAgreement, 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 Cryptographic Envelopes

For symmetric ciphers and hybrid encryption, CryptoUtility automatically packages the encrypted payload, random nonce, and authentication tag into a serialized cryptographic envelope under the hood using MemoryPack (an ultra-fast binary serializer). You receive a single, ready-to-transmit byte array or Base64 string. During decryption, the envelope is parsed automatically.

♻️ Cached Instance

To avoid allocations, we provide a <Algo>.Shared cached instance that can always be used so you don't have to instantiate new objects to work with the instance APIs.

🧣 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.

✨ Features

• Unified API Design: Identical syntax patterns for encryption, decryption, signatures, key agreement, and hashing.
• Built-in Utilities: Out-of-the-box helper methods for seamless Base64 string operations and easy key generation using Cipher.GenerateKey().
• Symmetric Encryption (AEAD): Modern standards including AES-256-GCM, AES-192-GCM, AES-128-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-2048, RSA-4096, and elliptic curve digital signatures (ECDSA).
• Key Agreement (ECDH): Establish secure session keys over open channels with Elliptic Curve Diffie-Hellman.
• Hashing & Checksums: SHA-2/3, fast non-cryptographic hashes (xxHash32/64/128), and integrity checksums (CRC-32, CRC-64).

🚀 Getting Started

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

🔤 Base64 String Workflow

using CryptoUtility;

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

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

if (encSuccess)
{
    // 3. Decrypt with a single call
    var (decSuccess, decryptedText) = Aes256Gcm.DecryptBase64(base64Key, envelope);
    Console.WriteLine($"Decrypted: {decryptedText}"); // Confidential customer details...
}

📦 Byte Array Workflow

using CryptoUtility;

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

// 2. Encrypt and Decrypt
var (encSuccess, ciphertext) = Aes256Gcm.Encrypt(key, plaintext);
var (decSuccess, decrypted) = Aes256Gcm.Decrypt(key, ciphertext);

2️⃣ Hybrid Asymmetric Encryption (RSA-4096 + AES)

using CryptoUtility;

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

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

// Decrypt payload using the PRIVATE key
var (decSuccess, decryptedPayload) = Rsa4096.HybridDecryptBase64(Aes256Gcm.Shared, privateKey, envelope);

3️⃣ Key Agreement & Hybrid ECDH

using CryptoUtility;

// 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
var (_, aliceSecret) = Ecdh.DeriveSharedSecret(alicePriv, bobPub);
var (_, 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
var (_, ciphertext) = Ecdh.Encrypt(Aes256Gcm.Shared, Hkdf.Shared, aliceSecret, "Hi Bob!", kdfSalt, kdfInfo);
var (_, decrypted) = Ecdh.Decrypt(Aes256Gcm.Shared, Hkdf.Shared, bobSecret, ciphertext, kdfSalt, kdfInfo);

📚 Cryptography API Reference

Symmetric Encryption (AEAD — Recommended)

Symmetric Encryption (Non-AEAD)

Asymmetric Encryption

Digital Signatures

Key Agreement

Key Derivation Functions

Password Based Key Derivation Functions

Hashing & Checksums

Cryptographic Hashes

Non-Cryptographic Hashes / Checksums

📝 API Notes

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

📄 License

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