Recursive AI

AES-EAX encryption and decryption in C#

OneCrypto is a free, open-source cryptography library for .NET from Recursive AI. MIT or Apache-2.0, preview, no native dependencies.

AES-EAX encrypts messages and authenticates an unencrypted header.

Terminal
dotnet add package RecursiveAI.OneCrypto

Requires .NET 10 (net10.0); .NET 9 and earlier aren’t supported.

C#
using System.Security.Cryptography;
using System.Text;
using RecursiveAI.OneCrypto.Primitives;
 
using var eax = new AesEax(
    RandomNumberGenerator.GetBytes(32));
byte[] nonce =
    RandomNumberGenerator.GetBytes(16);
byte[] data = "Hello EAX"u8.ToArray();
byte[] tag = new byte[16];
byte[] header = "record:1"u8.ToArray();
eax.Encrypt(
    nonce, data, data, tag, header);
eax.Decrypt(
    nonce, data, tag, data, header);
Console.WriteLine(
    Encoding.UTF8.GetString(data));
Text
Hello EAX

Unzip the example, then dotnet run.

The full program

C#
using System.Security.Cryptography;
using System.Text;
using RecursiveAI.OneCrypto.Primitives;
 
byte[] key = RandomNumberGenerator.GetBytes(32);
byte[] nonce = RandomNumberGenerator.GetBytes(16);
byte[] plaintext = "Hello EAX"u8.ToArray();
byte[] header = "record:1"u8.ToArray();
byte[] ciphertext = new byte[plaintext.Length];
byte[] tag = new byte[16], recovered = new byte[plaintext.Length];
using var eax = new AesEax(key);
eax.Encrypt(nonce, plaintext, ciphertext, tag, header);
eax.Decrypt(nonce, ciphertext, tag, recovered, header);
Console.WriteLine(Encoding.UTF8.GetString(recovered));
 
ciphertext[0] ^= 1;
try
{
    eax.Decrypt(nonce, ciphertext, tag, recovered, header);
}
catch (AuthenticationTagMismatchException)
{
    Console.WriteLine("Modified ciphertext rejected");
    Console.WriteLine($"Destination cleared: {recovered.All(b => b == 0)}");
}
CryptographicOperations.ZeroMemory(key);
Text
Hello EAX
Modified ciphertext rejected
Destination cleared: True

The full program uses separate ciphertext and plaintext buffers, then flips one ciphertext byte. Authentication failure throws AuthenticationTagMismatchException and clears the destination; EAX produces no plaintext on failure.

The API documentation requires that nonces “must never repeat under one key.” This example generates a fresh key and nonce for its single encryption.

Variations

Use a 12-byte tag with a 16-byte key. This standalone variation fixes the tag size in the constructor and uses that size for both calls.

C#
using System.Security.Cryptography;
using System.Text;
using RecursiveAI.OneCrypto.Primitives;
 
using var eax = new AesEax(RandomNumberGenerator.GetBytes(16), 12);
byte[] nonce = RandomNumberGenerator.GetBytes(16);
byte[] data = "Hello EAX"u8.ToArray();
byte[] tag = new byte[12], header = "record:1"u8.ToArray();
eax.Encrypt(nonce, data, data, tag, header);
eax.Decrypt(nonce, data, tag, data, header);
Console.WriteLine(Encoding.UTF8.GetString(data));
Text
Hello EAX

The short answer

Create AesEax from an AES key, allocate a ciphertext buffer as long as the plaintext and a tag buffer matching the object’s tag size, then call Encrypt. To decrypt, supply the same key, nonce, associated data and tag. Decrypt authenticates before releasing plaintext; a modified message is rejected rather than returned as damaged text.

OneCrypto exposes EAX in RecursiveAI.OneCrypto.Primitives. The implementation uses the platform’s AES and supplies the EAX mode around it. The example needs no files, network connection or stored credentials: it generates a temporary key, demonstrates the round trip and discards it. Keeping encrypted records across process restarts requires keeping the key securely as well.

How to encrypt and decrypt using AES?

Create AesEax with a 16-, 24- or 32-byte key, call Encrypt(nonce, plaintext, ciphertext, tag, header), then call Decrypt(nonce, ciphertext, tag, plaintext, header) with the same nonce, tag and header. Encrypt writes ciphertext and authentication tag to separate destinations. EAX accepts arbitrary message lengths, so you do not add block padding yourself. The ciphertext has the same length as the plaintext.

The AES modes documentation permits keys of 16, 24 or 32 bytes. Those correspond to AES-128, AES-192 and AES-256; the example’s 32-byte key uses the last option. The tag is separate from the key size. OneCrypto permits tags from 8 through 16 bytes and fixes the chosen length when you construct the key object. Allocate exactly that many tag bytes for each call, not a larger buffer for capacity.

Associated data is authenticated but stays unencrypted. The example uses the UTF-8 bytes of record:1 as a header. Decryption must receive those exact bytes again. Changing the header, ciphertext, nonce or tag makes authentication fail. A wrong key also fails authentication. Do not treat a failed destination buffer as a partial message: the API clears it.

What does nonce mean in cryptography?

For EAX, the nonce is a per-message value that must not repeat with the same key. It is not a password or another secret key. The EAX specification describes nonce-based authenticated encryption; OneCrypto’s API explicitly requires nonce uniqueness under each key.

The API accepts any nonce length, including an empty nonce, but that acceptance does not remove the uniqueness requirement. Do not encrypt multiple messages under one key with an empty nonce or a fixed example nonce. In a persistent record format, define how nonces are assigned so a restart or parallel writer cannot repeat them. The demonstration generates only one message per fresh key.

Store or transmit the nonce and tag with the ciphertext, and reproduce the associated header at decryption. These are the inputs the recipient needs besides the secret key. The API does not define an envelope format or concatenate these fields for you, so sender and receiver must agree on field lengths, byte encoding and tag size.

Use a separate AesEax object per concurrent thread: an instance is not safe for concurrent use. Dispose it when finished. Input and output may be identical spans, as in the snippet at the top, or nonoverlapping buffers, as in the full program. Partial overlap is rejected with ArgumentException; it is not an in-place shortcut.

All onecrypto recipes