Enigma.Cryptography.DataEncryption 1.1.0

Enigma.Cryptography.DataEncryption

A .NET library built on top of Enigma.Cryptography that provides stream-based encryption and decryption services.

All services share the same Stream-in / Stream-out API with optional IProgress<int> and CancellationToken support. Every encrypted blob starts with a binary header that embeds all parameters needed for decryption (cipher, KDF settings, nonce, etc.), so no out-of-band metadata is required.

Target frameworks

netstandard2.0, net10.0

Available services

Ciphers

All services support the following symmetric ciphers operating in GCM mode:

Pbkdf2DataEncryptionService

Password-based encryption using PBKDF2-HMAC-SHA256.

Encryption process

1. Generate a random 16-byte salt and a random 12-byte nonce.
2. Derive a 32-byte key with PBKDF2 from the password, salt, and iteration count.
3. Write the header to the output stream.
4. Encrypt the input stream into the output stream using the selected cipher in GCM mode.
5. Clear the key from memory.

Decryption process

1. Read the header from the input stream.
2. Derive the 32-byte key with PBKDF2 using the password, salt, and iteration count read from the header.
3. Decrypt the input stream into the output stream.

Usage

var service = new Pbkdf2DataEncryptionService();

// Encrypt
await service.EncryptAsync(inputStream, outputStream, Cipher.Aes256Gcm, "password", iterations: 100_000);

// Decrypt
await service.DecryptAsync(inputStream, outputStream, "password");

Binary format

Argon2DataEncryptionService

Password-based encryption using Argon2id.

Encryption process

1. Generate a random 16-byte salt and a random 12-byte nonce.
2. Derive a 32-byte key with Argon2id from the password, salt, and cost parameters.
3. Write the header to the output stream.
4. Encrypt the input stream into the output stream using the selected cipher in GCM mode.
5. Clear the key from memory.

Decryption process

1. Read the header from the input stream.
2. Derive the 32-byte key with Argon2id using the password and cost parameters read from the header.
3. Decrypt the input stream into the output stream.

Usage

var service = new Argon2DataEncryptionService();

// Encrypt
await service.EncryptAsync(inputStream, outputStream, Cipher.Aes256Gcm, passwordBytes);

// Decrypt
await service.DecryptAsync(inputStream, outputStream, passwordBytes);

Binary format

RsaDataEncryptionService

Hybrid encryption using an RSA public/private key pair to protect a random symmetric key.

Encryption process

1. Generate a random 32-byte symmetric key and a random 12-byte nonce.
2. Compute a 16-byte key fingerprint: first 16 bytes of SHA-256 over the public key's SubjectPublicKeyInfo DER encoding.
3. Encrypt the symmetric key with the RSA public key.
4. Write the header to the output stream.
5. Encrypt the input stream into the output stream using the selected cipher in GCM mode.
6. Clear the symmetric key from memory.

Decryption process

1. Read the header from the input stream.
2. Validate that the supplied private key matches the fingerprint stored in the header. Throws InvalidOperationException if they do not match.
3. Decrypt the encrypted symmetric key with the RSA private key.
4. Decrypt the input stream into the output stream.
5. Clear the symmetric key from memory.

Usage

var rsa = new PublicKeyServiceFactory().CreateRsaService();
var keyPair = rsa.GenerateKeyPair(4096);

var service = new RsaDataEncryptionService();

// Encrypt
await service.EncryptAsync(inputStream, outputStream, Cipher.Aes256Gcm, keyPair.Public);

// Decrypt — throws InvalidOperationException if the wrong private key is supplied
await service.DecryptAsync(inputStream, outputStream, keyPair.Private);

Binary format

MLKemDataEncryptionService

Post-quantum hybrid encryption using ML-KEM-1024 (NIST FIPS 203) for key encapsulation, combined with a symmetric block cipher for data encryption.

Encryption process

1. Generate a random 12-byte nonce.
2. Compute a 16-byte key fingerprint: first 16 bytes of SHA-256 over the public key's encoded bytes.
3. Encapsulate a shared secret from the ML-KEM-1024 public key, producing an encapsulation and a 32-byte secret.
4. Write the header to the output stream.
5. Encrypt the input stream into the output stream using the selected cipher in GCM mode with the shared secret as the key.
6. Clear the secret from memory.

Decryption process

1. Read the header from the input stream.
2. Validate that the supplied private key matches the fingerprint stored in the header. Throws InvalidOperationException if they do not match.
3. Decapsulate the shared secret from the encapsulation using the ML-KEM-1024 private key.
4. Decrypt the input stream into the output stream.
5. Clear the secret from memory.

Usage

var mlKem = new MLKemServiceFactory().CreateKem1024();
var keyPair = mlKem.GenerateKeyPair();

var service = new MLKemDataEncryptionService();

// Encrypt
await service.EncryptAsync(inputStream, outputStream, Cipher.Aes256Gcm, keyPair.Public);

// Decrypt — throws InvalidOperationException if the wrong private key is supplied
await service.DecryptAsync(inputStream, outputStream, keyPair.Private);

Binary format