IBlockCipherModeTransform Interface
Definition
- Namespace
- Bodu.Security.Cryptography
- Assembly
- Bodu.Security.Cryptography.dll
- Package
- Bodu.Security.Cryptography 1.3.0
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:
- Classic confidentiality-only modes EcbModeTransform, CbcModeTransform, CfbModeTransform, OfbModeTransform, CtrModeTransform, CtsModeTransform.
- Disk-encryption modeXtsModeTransform.
- Authenticated modes (AEAD) Implement the richer IAeadBlockCipherModeTransform contract instead - GcmModeTransform , CcmModeTransform, EaxModeTransform, GcmSivModeTransform, OcbModeTransform, SivModeTransform.
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
inputReadOnlySpan<byte>The input data to transform.
outputSpan<byte>The destination span. Its length must be greater than or equal to the length of
input.encryptbool
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
outputis shorter thaninput, or, for CtsModeTransform, wheninputis shorter than one block.- CryptographicException
Thrown when the mode accepts only whole blocks and the length of
inputis not a multiple of the block size, or wheninputandoutputpartially overlap.- ObjectDisposedException
Thrown when the transform has been disposed.
Applies to
| Product | Versions |
|---|---|
| .NET | 8, 10 |