Table of Contents

IBlockCipherModeTransform Interface

Definition

Namespace
Bodu.Security.Cryptography
Assembly
Bodu.Security.Cryptography.dll
Package
Bodu.Security.Cryptography 1.3.0
Source
IBlockCipherModeTransform.cs

Defines a stateful block cipher mode transformation that applies a chaining strategy (such as ECB, CBC, CFB, OFB, or CTR) over a block cipher primitive.

public interface IBlockCipherModeTransform : IDisposable
Inherited Members
Extension Methods

Remarks

Implementations wrap an IBlockCipher and own any mode state required between calls, such as the evolving initialization vector, feedback register, or counter. For the chaining and stream-shaped modes, successive calls to Transform(ReadOnlySpan<byte>, Span<byte>, bool) continue the stream from the state left by the previous call (a CTR call that ends in a partial block discards the rest of that block's keystream). EcbModeTransform is stateless, and XtsModeTransform restarts at the first block of its data unit on every call, so one XTS call must cover a whole data unit.

Padding is not handled by this interface. ECB, CBC, CFB, OFB, and XTS accept only whole blocks, so callers align their input to the cipher block size using an IPaddingStrategy before invoking Transform(ReadOnlySpan<byte>, Span<byte>, bool). CtrModeTransform accepts any length, and CtsModeTransform any length of at least one block.

API surface. The library ships several implementations clustered into three groups:

Most callers configure a mode through the BlockMode property of a block-cipher SymmetricAlgorithm wrapper (a CipherModeKind value, which the wrapper dispatches through BlockCipherModeFactory when CreateEncryptor or CreateDecryptor is called) rather than constructing this interface directly. That route covers ECB, CBC, CFB, OFB, and CTR; CtsModeTransform and XtsModeTransform exist only as direct transforms. Direct use is also appropriate when wiring a custom block cipher into the existing mode infrastructure or building a higher-level construction on top.

Implementations are stateful and not thread-safe; share behind explicit synchronization, or allocate one per consumer. Most modes reset cleanly when constructed afresh - there is no in-place reset method on this interface.

Methods

Transform(ReadOnlySpan<byte>, Span<byte>, bool)

Transforms input under the mode's chaining strategy and writes the result to output.

int Transform(ReadOnlySpan<byte> input, Span<byte> output, bool encrypt)

Parameters

input ReadOnlySpan<byte>

The input data to transform.

output Span<byte>

The destination span. Its length must be greater than or equal to the length of input.

encrypt bool

true to encrypt the input; false to decrypt.

Returns

int

The number of bytes written to output.

Remarks

The length rule depends on the mode: ECB, CBC, CFB, OFB, and XTS accept a whole number of blocks, zero included; CtrModeTransform accepts any length; CtsModeTransform accepts any length of at least one block.

Exceptions

ArgumentException

Thrown when output is shorter than input, or, for CtsModeTransform, when input is shorter than one block.

CryptographicException

Thrown when the mode accepts only whole blocks and the length of input is not a multiple of the block size, or when input and output partially overlap.

ObjectDisposedException

Thrown when the transform has been disposed.

Applies to

ProductVersions
.NET8, 10