IBlockCipher Interface

Definition

Namespace

Bodu.Security.Cryptography

Assembly

Bodu.Security.Cryptography.dll

Package

Bodu.Security.Cryptography 1.2.0

Source

IBlockCipher.cs

Defines a symmetric block cipher that encrypts and decrypts data one fixed-size block at a time.

public interface IBlockCipher : IDisposable

Inherited Members

IDisposable.Dispose()

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>)

Remarks

Implementations represent primitives such as AES or Threefish and operate on buffers whose length equals BlockSize. This interface intentionally exposes only the raw block primitive; chaining modes, padding, and IV management are the responsibility of higher-level components such as IBlockCipherModeTransform and IPaddingStrategy.

Implementations must release all sensitive key material when Dispose() is called and should be safe to invoke repeatedly for the lifetime of the instance.

How this fits with the rest of the library. IBlockCipher is the lowest-level primitive in the cipher stack. Three layers sit on top of it:

• An IBlockCipherModeTransform wraps a cipher with a chaining strategy (CBC, CTR, …) - built via Create(CipherModeKind, IBlockCipher, byte[]?).
• An IPaddingStrategy aligns input to the cipher block size - built via Create(PaddingMode).
• BlockCipherTransform bundles a cipher, mode, and padding into a single ICryptoTransform - the integration point used by every SymmetricAlgorithm in this library.

Most callers never instantiate IBlockCipher directly - they use a SymmetricAlgorithm (Aes, Twofish, Camellia, Threefish, Serpent, Skipjack, Blowfish), set Key/IV/Mode/Padding, and let the library compose the layers. Direct use of this interface is appropriate when implementing a new mode, plugging a non-SymmetricAlgorithm cipher engine into the existing mode infrastructure, or building higher-level constructions on top.

Properties

BlockSize

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

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.

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.

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

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

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.

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

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

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.

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

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

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.

Applies to

Product	Versions
.NET	8, 10

See Also

IBlockCipherModeTransform

IAeadBlockCipherModeTransform

BlockCipherTransform