Enigma.Cryptography 5.0.0

Enigma.Cryptography

A comprehensive .NET cryptography library built on top of BouncyCastle.Cryptography, providing a clean and easy-to-use API for common cryptographic operations.

• Bouncy Castle GitHub repository
• Bouncy Castle Official website

What's new in 5.0 — RSA-OAEP encryption, selectable PBKDF2 PRF, X.509 CRL revocation checking, and net10.0 added to the target frameworks. This is a major release with breaking changes (Argon2 enum parameters, factory-method renames, UTF-8 default in EncodingExtensions, and more). See the release notes for the full migration guide.

Features

• Block Ciphers — AES, DES, 3DES, Blowfish, Twofish, Serpent, Camellia, and more (CBC, ECB, GCM, SIC/CTR modes)
• Stream Ciphers — ChaCha20, ChaCha20-RFC7539, Salsa20
• Public-Key Cryptography — RSA encryption, signing, and PEM key management
• Post-Quantum Cryptography — ML-DSA (CRYSTALS-Dilithium) and ML-KEM (CRYSTALS-Kyber)
• X.509 Certificates — Self-signed generation, CSR creation, certificate issuance, PEM/DER/PFX support, chain validation
• Hashing — MD5, SHA-1, SHA-256, SHA-512, SHA-3
• HMAC — HMAC-SHA1, HMAC-SHA256, HMAC-SHA512 (byte-array and streaming)
• One-Time Passwords — HOTP (RFC 4226), TOTP (RFC 6238), and otpauth:// provisioning URIs
• Key Derivation — PBKDF2 and Argon2
• Padding — PKCS7, ISO 7816-4, ISO 10126, X9.23
• Data Encoding — Base64, hexadecimal, and Base32 (RFC 4648) encoding/decoding

Async, progress reporting & cancellation

Stream-based modules (Block Ciphers, Stream Ciphers, Hashing) are fully async and accept optional IProgress<int> and CancellationToken parameters for progress reporting and cooperative cancellation:

var cts = new CancellationTokenSource();
var progress = new Progress<int>(bytesProcessed =>
    Console.WriteLine($"Processed {bytesProcessed} bytes"));

await service.EncryptAsync(input, output, parameters, progress, cts.Token);

Progress reports per-chunk byte deltas (not cumulative totals), making it straightforward to build progress bars for large-file processing.

Installation

dotnet add package Enigma.Cryptography

Supported target frameworks: netstandard2.0, net8.0, and net10.0. Built on BouncyCastle.Cryptography 2.6.2.

Desktop application (GUI)

The repository also ships Enigma.Cryptography.Desktop, an Avalonia desktop app that exercises the whole library through one page per module — a hands-on way to try every algorithm without writing code. It uses the library directly via a project reference (dogfooding), so it always tracks the in-development API.

Run it from the repository root:

dotnet run --project src/Enigma.Cryptography.Desktop

Pages:

• Block Cipher / Stream Cipher — symmetric encryption/decryption with file-or-text I/O, progress and cancel.
• Hash / HMAC — digests and keyed digests over text or files.
• KDF — PBKDF2 and Argon2 key derivation.
• Data Encoding — Base64, Hex and Base32 encode/decode.
• Random Bytes — cryptographically secure random generation.
• Padding — PKCS7, ISO 7816-4, ISO 10126 and X9.23 pad/unpad.
• Stream Tools — build and inspect length-value / tag-length-value containers.
• OTP — HOTP/TOTP generation and verification plus otpauth:// provisioning URIs.
• Keys / RSA — RSA key management (PEM) and encrypt/decrypt/sign/verify.
• Post-Quantum — ML-DSA signatures and ML-KEM key encapsulation.
• X.509 — self-signed certificates, CSR create/verify, certificate issuance, chain validation, inspection, and PEM/DER/PFX round-trips.

Command-line application (CLI)

The repository also ships Enigma.Cryptography.Cli, a cross-platform command-line tool (assembly/executable name enigma-crypto) that exposes every library module as a scriptable subcommand. Like the desktop app it references the library directly (no shared layer), so it doubles as a direct-usage reference.

Run it from the repository root:

dotnet run --project src/Enigma.Cryptography.Cli -- --help

Commands accept input from an --in file, inline --text/--value arguments, or standard input, and write results as raw bytes (--out) or encoded text on stdout; diagnostics and progress go to standard error, and processes return scriptable exit codes (0 success, 1 cryptographic failure, 2 usage/I/O error, 130 cancelled). Command groups: block, stream, hash, hmac, kdf, encode/decode, pad/unpad, container, rand, hotp/totp/otp, rsa, mldsa/mlkem, and cert.

# Hash stdin, generate an RSA key pair, and run a full X.509 PKI flow
echo -n abc | dotnet run --project src/Enigma.Cryptography.Cli -- hash --algo sha256
dotnet run --project src/Enigma.Cryptography.Cli -- cert self-signed --subject "CN=Example CA, O=Acme" --out ca.pem --key-out ca.key

See src/Enigma.Cryptography.Cli/README.md for the full command reference — per-command option and exit-code tables, examples, and self-contained publish commands.

Block ciphers

Supported algorithms

Classes

• BlockCipherService — Service for encryption/decryption with block ciphers
• BlockCipherServiceFactory — IBlockCipherService factory
• BlockCipherEngineFactory — IBlockCipher factory
• BlockCipherPaddingFactory — IBlockCipherPadding factory
• BlockCipherParametersFactory — ICipherParameters factory

Usage

Create a block cipher service with an algorithm string:

var service = new BlockCipherService("AES/CBC/PKCS7Padding");
// or without padding:
var service = new BlockCipherService("AES/CBC/NoPadding");

Create a block cipher service with factories:

var engineFactory = new BlockCipherEngineFactory();
var paddingFactory = new BlockCipherPaddingFactory();

// With padding
var service = new BlockCipherServiceFactory().CreateCbcService(engineFactory.CreateAesEngine, paddingFactory.CreatePkcs7Padding);

// Without padding
var service = new BlockCipherServiceFactory().CreateCbcService(engineFactory.CreateAesEngine);

AES-256 GCM example

var service = new BlockCipherService("AES/GCM");

var key = RandomUtils.GenerateRandomBytes(32);
var nonce = RandomUtils.GenerateRandomBytes(12);
var parameters = new BlockCipherParametersFactory().CreateGcmParameters(key, nonce, "associated data".GetUtf8Bytes());

var data = "This is a secret message !".GetUtf8Bytes();

// Encrypt
using var inputEnc = new MemoryStream(data);
using var outputEnc = new MemoryStream();
await service.EncryptAsync(inputEnc, outputEnc, parameters);

var encrypted = outputEnc.ToArray();

// Decrypt
using var inputDec = new MemoryStream(encrypted);
using var outputDec = new MemoryStream();
await service.DecryptAsync(inputDec, outputDec, parameters);

var decrypted = outputDec.ToArray();

AES-256 CBC example

var service = new BlockCipherService("AES/CBC/PKCS7Padding");

var key = RandomUtils.GenerateRandomBytes(32);
var iv = RandomUtils.GenerateRandomBytes(16);
var parameters = new BlockCipherParametersFactory().CreateCbcParameters(key, iv);

var data = "This is a secret message !".GetUtf8Bytes();

// Encrypt
using var inputEnc = new MemoryStream(data);
using var outputEnc = new MemoryStream();
await service.EncryptAsync(inputEnc, outputEnc, parameters);

var encrypted = outputEnc.ToArray();

// Decrypt
using var inputDec = new MemoryStream(encrypted);
using var outputDec = new MemoryStream();
await service.DecryptAsync(inputDec, outputDec, parameters);

var decrypted = outputDec.ToArray();

Stream ciphers

Supported algorithms

Classes

• StreamCipherService — Service for encryption/decryption with stream ciphers
• StreamCipherServiceFactory — IStreamCipherService factory

ChaCha20-RFC7539 example

var service = new StreamCipherServiceFactory().CreateChaCha7539Service();

var key = RandomUtils.GenerateRandomBytes(32);
var nonce = RandomUtils.GenerateRandomBytes(12);

var data = "This is a secret message !".GetUtf8Bytes();

// Encrypt
using var inputEnc = new MemoryStream(data);
using var outputEnc = new MemoryStream();
await service.EncryptAsync(inputEnc, outputEnc, key, nonce);

var encrypted = outputEnc.ToArray();

// Decrypt
using var inputDec = new MemoryStream(encrypted);
using var outputDec = new MemoryStream();
await service.DecryptAsync(inputDec, outputDec, key, nonce);

var decrypted = outputDec.ToArray();

Public-key cryptography

Classes

• PublicKeyService — Service for public-key encryption/decryption and signing/verifying
• PublicKeyServiceFactory — IPublicKeyService factory

RSA example

var service = new PublicKeyServiceFactory().CreateRsaService();

// Generate a 4096-bit key pair
var keyPair = service.GenerateKeyPair(4096);

var data = "This is a secret message".GetUtf8Bytes();

// Encrypt/decrypt with PKCS#1 v1.5 (the service created above)
var enc = service.Encrypt(data, keyPair.Public);
var dec = service.Decrypt(enc, keyPair.Private);

// For new applications, prefer OAEP (SHA-256 by default) over PKCS#1 v1.5:
var oaep = new PublicKeyServiceFactory().CreateRsaOaepService(); // or CreateRsaOaepService(RsaOaepHash.Sha512)
var encOaep = oaep.Encrypt(data, keyPair.Public);
var decOaep = oaep.Decrypt(encOaep, keyPair.Private);

// Sign/verify
var signature = service.Sign(data, keyPair.Private);
var verified = service.Verify(data, signature, keyPair.Public);

// Save public key in PEM format
using var publicOutput = new MemoryStream();
PemUtils.SaveKey(keyPair.Public, publicOutput);

// Save and encrypt private key in PEM format
using var privateOutput = new MemoryStream();
PemUtils.SavePrivateKey(keyPair.Private, privateOutput, "yourpassword", algorithm: "AES-256-CBC");

// Load public key from PEM
using var publicInput = new MemoryStream(publicOutput.ToArray());
var publicKey = PemUtils.LoadKey(publicInput);

// Load and decrypt private key from PEM
using var privateInput = new MemoryStream(privateOutput.ToArray());
var privateKey = PemUtils.LoadPrivateKey(privateInput, "yourpassword");

Post-Quantum Cryptography (PQC)

Classes

• MLDsaService — Module-Lattice-Based digital signature algorithm (ML-DSA / CRYSTALS-Dilithium)
• MLDsaServiceFactory — IMLDsaService factory
• MLKemService — Module-Lattice-Based key-encapsulation mechanism (ML-KEM / CRYSTALS-Kyber)
• MLKemServiceFactory — IMLKemService factory

ML-DSA example

var service = new MLDsaServiceFactory().CreateDsa65Service(); // deterministic: false (default)

var keyPair = service.GenerateKeyPair();

var data = "Data to sign".GetUtf8Bytes();

// Sign/verify
var signature = service.Sign(data, keyPair.Private);
var verified = service.Verify(data, signature, keyPair.Public);

// Save public key in PEM format
using var publicOutput = new MemoryStream();
PemUtils.SaveKey(keyPair.Public, publicOutput);

// Save and encrypt private key in PEM format
using var privateOutput = new MemoryStream();
PemUtils.SavePrivateKey(keyPair.Private, privateOutput, "yourpassword", algorithm: "AES-256-CBC");

// Load public key from PEM
using var publicInput = new MemoryStream(publicOutput.ToArray());
var publicKey = PemUtils.LoadKey(publicInput);

// Load and decrypt private key from PEM
using var privateInput = new MemoryStream(privateOutput.ToArray());
var privateKey = PemUtils.LoadPrivateKey(privateInput, "yourpassword");

ML-KEM example

var service = new MLKemServiceFactory().CreateKem1024Service();

var keyPair = service.GenerateKeyPair();

// Encapsulate a shared secret
var (encapsulation, secret) = service.Encapsulate(keyPair.Public);

// Decapsulate the shared secret
var secretDec = service.Decapsulate(encapsulation, keyPair.Private);

// Save public key in PEM format
using var publicOutput = new MemoryStream();
PemUtils.SaveKey(keyPair.Public, publicOutput);

// Save and encrypt private key in PEM format
using var privateOutput = new MemoryStream();
PemUtils.SavePrivateKey(keyPair.Private, privateOutput, "yourpassword", algorithm: "AES-256-CBC");

// Load public key from PEM
using var publicInput = new MemoryStream(publicOutput.ToArray());
var publicKey = PemUtils.LoadKey(publicInput);

// Load and decrypt private key from PEM
using var privateInput = new MemoryStream(privateOutput.ToArray());
var privateKey = PemUtils.LoadPrivateKey(privateInput, "yourpassword");

X.509 Certificates

Classes

• X509CertificateService — Service for certificate generation, CSR creation, certificate issuance, and chain validation
• X509CertificateServiceFactory — IX509CertificateService factory
• X509Utils — Static utilities for loading, saving, and inspecting certificates (PEM, DER, PFX)
• CertificateInfo — Read-only certificate information (subject, issuer, validity, extensions, etc.)

Self-signed certificate example

var certService = new X509CertificateServiceFactory().CreateX509CertificateService();
var rsaService = new PublicKeyServiceFactory().CreateRsaService();

// Generate RSA key pair and self-signed certificate
var keyPair = rsaService.GenerateKeyPair(2048);
var cert = certService.GenerateSelfSignedCertificate(
    keyPair,
    new X509Name("CN=example.com,O=MyOrg"),
    DateTime.UtcNow.AddDays(-1),
    DateTime.UtcNow.AddYears(1),
    keyUsage: KeyUsage.DigitalSignature | KeyUsage.KeyEncipherment,
    basicConstraintsCa: false,
    subjectAlternativeNames: new GeneralNames(new GeneralName(GeneralName.DnsName, "example.com")));

// Save certificate to PEM
using var pemOutput = new MemoryStream();
X509Utils.SaveCertificateToPem(cert, pemOutput);

// Load certificate from PEM
using var pemInput = new MemoryStream(pemOutput.ToArray());
var loaded = X509Utils.LoadCertificateFromPem(pemInput);

// Save/load certificate in DER format
var derBytes = X509Utils.SaveCertificate(cert);
var fromDer = X509Utils.LoadCertificate(derBytes);

// Export to PFX (certificate + private key)
var pfxData = X509Utils.ExportToPfx("mycert", cert, keyPair.Private, "password");

// Import from PFX
var (pfxCert, pfxKey) = X509Utils.LoadFromPfx(pfxData, "password");

// Inspect certificate
var info = X509Utils.GetCertificateInfo(cert);
Console.WriteLine($"Subject: {info.Subject}");
Console.WriteLine($"Valid: {info.NotBefore} - {info.NotAfter}");
Console.WriteLine($"Is CA: {info.IsCa}");

CSR and certificate issuance example

var certService = new X509CertificateServiceFactory().CreateX509CertificateService();
var rsaService = new PublicKeyServiceFactory().CreateRsaService();

// Create a CA
var caKeyPair = rsaService.GenerateKeyPair(2048);
var caCert = certService.GenerateSelfSignedCertificate(
    caKeyPair,
    new X509Name("CN=My CA"),
    DateTime.UtcNow.AddDays(-1),
    DateTime.UtcNow.AddYears(10),
    keyUsage: KeyUsage.KeyCertSign | KeyUsage.CrlSign,
    basicConstraintsCa: true);

// Generate a CSR for a leaf certificate
var leafKeyPair = rsaService.GenerateKeyPair(2048);
var csr = certService.GenerateCsr(leafKeyPair, new X509Name("CN=leaf.example.com"));

// Issue the certificate from the CSR
var leafCert = certService.IssueCertificate(
    csr, caKeyPair, new X509Name("CN=My CA"),
    DateTime.UtcNow.AddDays(-1),
    DateTime.UtcNow.AddYears(1),
    keyUsage: KeyUsage.DigitalSignature | KeyUsage.KeyEncipherment,
    basicConstraintsCa: false);

// Validate the chain (signature, trust anchor, path, and validity period).
// Revocation is NOT checked by default; pass CRLs to enable it:
//   certService.ValidateChain(leafCert, new[] { caCert }, crls);
var isValid = certService.ValidateChain(leafCert, new[] { caCert });

Hashing

Supported algorithms

Classes

• HashService — Hash service
• HashServiceFactory — IHashService factory

Usage

var data = "Data to hash".GetUtf8Bytes();

var service = new HashServiceFactory().CreateSha3Service();

using var input = new MemoryStream(data);
var hash = await service.HashAsync(input);

HMAC

Supported algorithms

Classes

• HmacService — HMAC computation service (synchronous byte[] and async streaming)
• HmacServiceFactory — IHmacService factory

Usage

var key = "shared-secret".GetUtf8Bytes();
var service = new HmacServiceFactory().CreateHmacSha256Service(key);

// Byte array
var mac = service.ComputeHmac("message".GetUtf8Bytes());

// Streaming
using var input = new MemoryStream("message".GetUtf8Bytes());
var macFromStream = await service.ComputeHmacAsync(input);

// The key is caller-owned; clear it when no longer needed
Array.Clear(key, 0, key.Length);

One-Time Passwords (HOTP / TOTP)

Counter-based (HOTP, RFC 4226) and time-based (TOTP, RFC 6238) one-time passwords, plus otpauth:// provisioning URIs for enrolling authenticator apps. QR-code image generation is out of scope.

Classes

• HotpService / HotpServiceFactory — HOTP (RFC 4226), counter-based
• TotpService / TotpServiceFactory — TOTP (RFC 6238), time-based
• OtpProvisioning — Static helpers: secret generation, otpauth URI build/parse
• OtpAuthParameters — Parsed otpauth URI parameters
• OtpHashAlgorithm — HMAC algorithm selector (Sha1, Sha256, Sha512)

TOTP example

var hotpFactory = new HotpServiceFactory(new HmacServiceFactory());

// Enroll: generate a secret and build a provisioning URI for the authenticator app
var secret = OtpProvisioning.GenerateSecret();
var uri = OtpProvisioning.BuildUri("Example", "alice@example.com", secret);
// otpauth://totp/Example:alice%40example.com?secret=...&issuer=Example&algorithm=SHA1&digits=6&period=30

// Generate and verify codes
var totp = new TotpServiceFactory(hotpFactory).CreateTotpService(secret);
var code = totp.Generate();
var isValid = totp.Verify(code); // default drift window of ±1 time step

// Reject replays using the matched time step
if (totp.Verify(code, window: 1, out var matchedStep))
{
    // accept only if matchedStep is greater than the last accepted step, then store it
}

// Seconds remaining before the current code rolls over
var remaining = totp.GetRemainingSeconds();

// The secret is caller-owned; clear it when no longer needed
Array.Clear(secret, 0, secret.Length);

HOTP example

var secret = OtpProvisioning.GenerateSecret();
var service = new HotpServiceFactory(new HmacServiceFactory()).CreateHotpService(secret);

var code = service.Generate(counter: 0);
var isValid = service.Verify(code, counter: 0, window: 1);

Key Derivation (KDF)

Classes

• Pbkdf2Service — PBKDF2 key derivation service
• Pbkdf2ServiceFactory — IPbkdf2Service factory
• Argon2Service — Argon2 password-based key derivation service
• Argon2ServiceFactory — IArgon2Service factory

PBKDF2 example

var service = new Pbkdf2Service();

var salt = "5775ada0513d7d7d7316de8d72d1f4d2".FromHexString();

// Derive a 32-byte key from a password and salt
var key = service.GenerateKey(size: 32, password: "yourpassword", salt);

// Select the PRF (HMAC digest); defaults to HMAC-SHA-1 for compatibility,
// HMAC-SHA-256 or stronger is recommended for new use.
var key256 = service.GenerateKey(size: 32, password: "yourpassword", salt, prf: Pbkdf2Prf.HmacSha256);

Argon2 example

var service = new Argon2Service();

var passwordData = "yourpassword".GetUtf8Bytes();
var salt = RandomUtils.GenerateRandomBytes(16);

// Derive a 32-byte key from a password and salt
var key = service.GenerateKey(32, passwordData, salt);

// The caller is responsible for clearing sensitive input when done
Array.Clear(passwordData, 0, passwordData.Length);

Padding

Supported schemes

Classes

• NoPaddingService — No-op padding service
• PaddingService — Padding service
• PaddingServiceFactory — IPaddingService factory

Usage

var data = "Data to pad".GetUtf8Bytes();

var service = new PaddingServiceFactory().CreatePkcs7Service();

// Pad/unpad with a 16-byte block size
var padded = service.Pad(data, blockSize: 16);
var unpadded = service.Unpad(padded, blockSize: 16);

Data encoding

Classes

• Base64Service — Base64 encoding/decoding service
• HexService — Hexadecimal encoding/decoding service
• Base32Service — Base32 (RFC 4648) encoding/decoding service (padded Encode; Decode tolerant of case, whitespace, and missing padding)

Usage

var data = "This is some data".GetUtf8Bytes();

// Hex encoding
var hex = new HexService();
var hexEncoded = hex.Encode(data);
var hexDecoded = hex.Decode(hexEncoded);

// Base64 encoding
var base64 = new Base64Service();
var base64Encoded = base64.Encode(data);
var base64Decoded = base64.Decode(base64Encoded);

// Base32 encoding
var base32 = new Base32Service();
var base32Encoded = base32.Encode(data);
var base32Decoded = base32.Decode(base32Encoded);

With extension methods:

var data = "This is some data".GetUtf8Bytes();

var hexEncoded = data.ToHexString();
var hexDecoded = hexEncoded.FromHexString();

var base64Encoded = data.ToBase64String();
var base64Decoded = base64Encoded.FromBase64String();

var base32Encoded = data.ToBase32String();
var base32Decoded = base32Encoded.FromBase32String();

Stream extensions

StreamExtensions (namespace Enigma.Cryptography.Extensions) adds typed read/write helpers to any Stream, plus length-value (LV) and tag-length-value (TLV) framing for building and parsing binary containers. Integers are written little-endian, every read fully populates its buffer (partial reads are handled), and both synchronous and ...Async variants are provided.

• Typed values — WriteBool/ReadBool, WriteShort/ReadShort and WriteUShort/ReadUShort, WriteInt/ReadInt and WriteUInt/ReadUInt, WriteLong/ReadLong and WriteULong/ReadULong, WriteFloat/ReadFloat, WriteDouble/ReadDouble.
• Raw bytes — WriteBytes(bytes) / ReadBytes(count), plus async WriteByteAsync / ReadByteAsync.
• Length-Value — WriteLengthValue(value) / ReadLengthValue(maxLength = 10 MB): writes a 4-byte length prefix followed by the bytes; the read guards against negative or oversized lengths.
• Tag-Length-Value — WriteTagLengthValue(tag, value) / ReadTagLengthValue(maxLength = 10 MB): a ushort tag followed by a length-value block; the read returns a (ushort tag, byte[] value) tuple.

using var stream = new MemoryStream();

// Write a small container: a typed header value, then two tagged fields
stream.WriteInt(1);                                    // e.g. a format version
stream.WriteTagLengthValue(1, "alice".GetUtf8Bytes());
stream.WriteTagLengthValue(2, RandomUtils.GenerateRandomBytes(16));

// Read it back
stream.Position = 0;
var version = stream.ReadInt();                        // 1
var (tag1, value1) = stream.ReadTagLengthValue();      // (1, "alice")
var (tag2, value2) = stream.ReadTagLengthValue();      // (2, 16 random bytes)

Synchronous Stream.WriteByte(byte) / ReadByte() are not provided as extensions — the System.IO.Stream instance methods of those names take precedence. Use those built-ins, or the async WriteByteAsync / ReadByteAsync.

Utilities

The Enigma.Cryptography.Utils namespace holds stateless helpers used throughout the library:

• RandomUtils — RandomUtils.GenerateRandomBytes(size) returns cryptographically secure random bytes from a thread-local BouncyCastle SecureRandom. Use it for keys, IVs/nonces, and salts (as in the cipher and KDF examples above).
• PemUtils — load/save PEM-encoded keys (see the Public-key and PQC examples).
• X509Utils — load/save/inspect X.509 certificates in PEM, DER, and PFX (see the X.509 examples).

// 32 bytes for an AES-256 key, 12 for a GCM nonce
var key = RandomUtils.GenerateRandomBytes(32);
var nonce = RandomUtils.GenerateRandomBytes(12);

Copyright (c) 2026 Josué Clément