AesBlockCipher Class

Definition

Namespace

Bodu.Security.Cryptography

Assembly

Bodu.Security.Cryptography.dll

Package

Bodu.Security.Cryptography 1.2.0

Source

AesBlockCipher.cs

Exposes the BCL Aes algorithm as an IBlockCipher, providing the single-block primitive that the authenticated-mode transforms (GcmModeTransform, CcmModeTransform, OcbModeTransform, SivModeTransform, GcmSivModeTransform) require.

public sealed class AesBlockCipher : IBlockCipher, IDisposable

Inheritance

object

AesBlockCipher

Implements

IBlockCipher

IDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Extension Methods

ComparableExtensions.AtLeast<T>(T, T, IComparer<T>)

ComparableExtensions.AtMost<T>(T, T, IComparer<T>)

ComparableExtensions.IsEqualTo<T>(T, T, IComparer<T>)

ComparableExtensions.Max<T>(T, T, IComparer<T>)

ComparableExtensions.Min<T>(T, T, IComparer<T>)

Examples

// Encrypt a single 16-byte block (typically used indirectly via an AEAD mode transform).
byte[] key = RandomNumberGenerator.GetBytes(16);
using var cipher = new AesBlockCipher(key);
Span<byte> block = stackalloc byte[16];
Span<byte> output = stackalloc byte[16];
cipher.Encrypt(block, output);

Remarks

The adapter encrypts and decrypts exactly one 16-byte block per call, in ECB mode with no padding, delegating to the BCL's hardware-accelerated Aes implementation. The ECB encryptor is created on construction and the decryptor on the first decryption, and both are cached, so per-block calls reuse the expanded key schedule rather than rebuilding a cipher context each time, and an instance that only encrypts never builds a decryptor.

AesBlockCipher is not intended for direct encryption of user data. Wrap it in one of the authenticated mode transforms listed above - the mode transform is responsible for chaining, IV / nonce handling, associated-data authentication, and tag generation or verification.

Instances hold sensitive key material and must be disposed after use. Disposal releases the underlying Aes instance and zeros its expanded key schedule.

Constructors

AesBlockCipher(byte[])

Initializes a new instance of the AesBlockCipher class with the specified AES key.

public AesBlockCipher(byte[] key)

Parameters

key byte[]

The AES key. Valid lengths are 16, 24, or 32 bytes (AES-128, AES-192, or AES-256). A defensive copy is taken - the caller may zero the original array immediately after construction.

Exceptions

ArgumentNullException

key is null.

CryptographicException

key length is not 16, 24, or 32 bytes.

Properties

BlockSize

Gets the block size, in bits, of the cipher (for example, 128 bits / 16 bytes for AES).

public int BlockSize { get; }

Property Value

int

The block size, in bits.

Remarks

The block size is expressed in bits to align with the BCL convention used by BlockSize. Byte-array operations (encrypt, decrypt, slice) convert to bytes at the call site as BlockSize / 8.

Methods

Decrypt(ReadOnlySpan<byte>, Span<byte>)

Decrypts a single block of ciphertext into the specified output span.

public void Decrypt(ReadOnlySpan<byte> input, Span<byte> output)

Parameters

input ReadOnlySpan<byte>

A read-only span containing the ciphertext block. Its byte length must equal BlockSize / 8.

output Span<byte>

A writable span that receives the plaintext block. Its byte length must equal BlockSize / 8.

Remarks

In-place decryption (passing the same buffer as both input and output) is supported only when the implementation explicitly permits it; otherwise the spans must not overlap.

Exceptions

ArgumentException

Thrown if the length of input or output does not match BlockSize.

ObjectDisposedException

The instance has been disposed.

ArgumentException

input or output is not exactly BlockSize / 8 bytes.

DecryptBlocks(ReadOnlySpan<byte>, Span<byte>)

Decrypts a run of one or more contiguous blocks, each independently (ECB semantics), writing the plaintext into output.

public void DecryptBlocks(ReadOnlySpan<byte> input, Span<byte> output)

Parameters

input ReadOnlySpan<byte>

The ciphertext blocks. Length must be a positive multiple of BlockSize / 8.

output Span<byte>

The destination for the plaintext. Must be at least input.Length bytes.

Remarks

The default implementation calls Decrypt(ReadOnlySpan<byte>, Span<byte>) once per block; see EncryptBlocks(ReadOnlySpan<byte>, Span<byte>) for when to override.

Exceptions

ObjectDisposedException

The instance has been disposed.

ArgumentException

input is not a whole number of blocks, or output is shorter than input.

Dispose()

Releases the underlying Aes instance, zeroing its expanded key schedule. Subsequent calls to Encrypt(ReadOnlySpan<byte>, Span<byte>) or Decrypt(ReadOnlySpan<byte>, Span<byte>) throw ObjectDisposedException.

public void Dispose()

Encrypt(ReadOnlySpan<byte>, Span<byte>)

Encrypts a single block of plaintext into the specified output span.

public void Encrypt(ReadOnlySpan<byte> input, Span<byte> output)

Parameters

input ReadOnlySpan<byte>

A read-only span containing the plaintext block. Its byte length must equal BlockSize / 8.

output Span<byte>

A writable span that receives the ciphertext block. Its byte length must equal BlockSize / 8.

Remarks

In-place encryption (passing the same buffer as both input and output) is supported only when the implementation explicitly permits it; otherwise the spans must not overlap.

Exceptions

ArgumentException

Thrown if the length of input or output does not match BlockSize.

ObjectDisposedException

The instance has been disposed.

ArgumentException

input or output is not exactly BlockSize / 8 bytes.

EncryptBlocks(ReadOnlySpan<byte>, Span<byte>)

Encrypts a run of one or more contiguous blocks, each independently (ECB semantics), writing the ciphertext into output.

public void EncryptBlocks(ReadOnlySpan<byte> input, Span<byte> output)

Parameters

input ReadOnlySpan<byte>

The plaintext blocks. Length must be a positive multiple of BlockSize / 8.

output Span<byte>

The destination for the ciphertext. Must be at least input.Length bytes.

Remarks

The default implementation calls Encrypt(ReadOnlySpan<byte>, Span<byte>) once per block. Implementations backed by a primitive with per-call setup cost (for example a wrapped BCL cipher context) should override this to amortize that cost across the whole run. Callers that process independent blocks - ECB and the keystream layer of CTR-based modes - should prefer this over a per-block loop.

Exceptions

ObjectDisposedException

The instance has been disposed.

ArgumentException

input is not a whole number of blocks, or output is shorter than input.

Applies to

Product	Versions
.NET	8, 10

See Also

Using AEAD modes (guide with full encrypt / decrypt examples)