Table of Contents

BlockCipherTransform Class

Definition

Namespace
Bodu.Security.Cryptography
Assembly
Bodu.Security.Cryptography.dll
Package
Bodu.Security.Cryptography 1.2.0
Source
BlockCipherTransform.cs

Provides a base implementation of ICryptoTransform for block cipher algorithms that combine an IBlockCipher engine with an IBlockCipherModeTransform and an IPaddingStrategy.

public class BlockCipherTransform : ICryptoTransform, IDisposable
Inheritance
BlockCipherTransform
Implements
Inherited Members
Extension Methods

Examples

// Most consumers never touch BlockCipherTransform directly - it is surfaced as the
// ICryptoTransform returned by every Bodu SymmetricAlgorithm. Typical usage:
using SymmetricAlgorithm alg = new Twofish();
alg.GenerateKey();
alg.GenerateIV();
alg.Mode    = CipherMode.CBC;
alg.Padding = PaddingMode.PKCS7;

// CreateEncryptor returns a BlockCipherTransform under the hood - a one-shot
// ICryptoTransform that pairs the block cipher with the configured mode and padding.
using ICryptoTransform encryptor = alg.CreateEncryptor();
using var output = new MemoryStream();
using (var cs = new CryptoStream(output, encryptor, CryptoStreamMode.Write))
    cs.Write(plaintext, 0, plaintext.Length);
byte[] ciphertext = output.ToArray();

// Reuse requires a fresh transform - BlockCipherTransform.CanReuseTransform is false.

Remarks

Block-aligned streaming data is processed via TransformBlock(byte[], int, int, byte[], int), and the final potentially partial block - including padding application or removal - is handled by TransformFinalBlock(byte[], int, int).

When decrypting with a strippable padding mode, such as PKCS7, the last complete block of ciphertext is deferred until TransformFinalBlock(byte[], int, int) is called. This allows padding to be validated and removed only at the end of the stream.

A BlockCipherTransform instance represents a single cryptographic transform operation. Once TransformFinalBlock(byte[], int, int) has completed, the instance is finalized and cannot be used for another operation. Consequently, CanReuseTransform returns false. Callers that need to encrypt or decrypt additional data must create a new transform instance.

Finalization is distinct from disposal. After TransformFinalBlock(byte[], int, int) completes, subsequent transform calls throw InvalidOperationException. After Dispose() is called, subsequent transform calls throw ObjectDisposedException.

The transform is intentionally not reusable because the underlying block cipher mode transform may contain mutable chaining, feedback, or counter state. Clearing deferred padding input after finalization is not sufficient to restore the mode transform to its initial IV or counter state.

How this fits with the rest of the library. BlockCipherTransform is the glue layer that turns a low-level IBlockCipher into the ICryptoTransform contract that CryptoStream, SymmetricAlgorithm.CreateEncryptor(), and the rest of the BCL crypto pipeline expect. Every SymmetricAlgorithm in this library (Blowfish, Camellia, Skipjack, Twofish, Serpent, Threefish, …) returns an instance of this class from its CreateEncryptor / CreateDecryptor overrides, pairing the family's cipher engine with the configured mode and padding.

Most callers never touch this type directly - they use Mode and Padding to configure encryption and let the existing transform infrastructure handle the wiring.

Constructors

BlockCipherTransform(IBlockCipher, CipherModeKind, PaddingModeKind, byte[]?, bool)

Initializes a new instance of the BlockCipherTransform class using the specified cipher engine, mode, extended padding scheme, initialization vector, and transform direction.

protected BlockCipherTransform(IBlockCipher cipher, CipherModeKind cipherMode, PaddingModeKind paddingMode, byte[]? iv, bool encrypt)

Parameters

cipher IBlockCipher

The configured IBlockCipher engine to use. Must not be null.

cipherMode CipherModeKind

The block cipher mode of operation.

paddingMode PaddingModeKind

The extended padding scheme to apply to the final block. Accepts values beyond the framework PaddingMode enum, including ISO7816_4.

iv byte[]

The initialization vector for the cipher mode. Must match the cipher block size.

encrypt bool

true to configure for encryption; false for decryption.

Exceptions

ArgumentNullException

cipher is null.

BlockCipherTransform(IBlockCipher, CipherModeKind, PaddingMode, byte[]?, bool)

Initializes a new instance of the BlockCipherTransform class using the specified cipher engine, mode, padding scheme, initialization vector, and transform direction.

protected BlockCipherTransform(IBlockCipher cipher, CipherModeKind cipherMode, PaddingMode paddingMode, byte[]? iv, bool encrypt)

Parameters

cipher IBlockCipher

The configured IBlockCipher engine to use. Must not be null.

cipherMode CipherModeKind

The block cipher mode of operation.

paddingMode PaddingMode

The padding scheme to apply to the final block.

iv byte[]

The initialization vector for the cipher mode. Must match the cipher block size.

encrypt bool

true to configure for encryption; false for decryption.

Exceptions

ArgumentNullException

cipher is null.

Properties

CanReuseTransform

Gets a value indicating whether the current transform can be reused.

public bool CanReuseTransform { get; }

Property Value

bool

true if the current transform can be reused; otherwise, false.

CanTransformMultipleBlocks

Gets a value indicating whether multiple blocks can be transformed.

public bool CanTransformMultipleBlocks { get; }

Property Value

bool

true if multiple blocks can be transformed; otherwise, false.

InputBlockSize

Gets the input block size.

public int InputBlockSize { get; }

Property Value

int

The size of the input data blocks in bytes.

Remarks

The BCL ICryptoTransform contract requires this value in bytes; the underlying BlockSize is in bits, so we divide by 8.

OutputBlockSize

Gets the output block size.

public int OutputBlockSize { get; }

Property Value

int

The size of the output data blocks in bytes.

Remarks

The BCL ICryptoTransform contract requires this value in bytes; the underlying BlockSize is in bits, so we divide by 8.

Methods

Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

public void Dispose()

ThrowIfFinalized()

Throws if this transform has already completed its final block operation.

protected void ThrowIfFinalized()

Exceptions

InvalidOperationException

This transform has already been finalized and cannot be reused.

TransformBlock(byte[], int, int, byte[], int)

Transforms a block-aligned region of the input byte array and writes the result to the output buffer.

public int TransformBlock(byte[] inputBuffer, int inputOffset, int inputCount, byte[] outputBuffer, int outputOffset)

Parameters

inputBuffer byte[]

The input data buffer. Must not be null.

inputOffset int

The byte offset within inputBuffer at which to begin reading.

inputCount int

The number of bytes to process. Must be a multiple of InputBlockSize.

outputBuffer byte[]

The buffer to write the transformed data into. Must not be null.

outputOffset int

The byte offset within outputBuffer at which to begin writing.

Returns

int

The number of bytes written to outputBuffer.

Exceptions

ObjectDisposedException

This instance has been disposed.

InvalidOperationException

This transform has already been finalized and cannot be reused.

ArgumentNullException

inputBuffer or outputBuffer is null.

ArgumentException

The input or output buffer span is invalid or insufficient in length for the requested operation.

TransformFinalBlock(byte[], int, int)

Transforms the final block of data, applying or removing padding as appropriate, and returns the result.

public byte[] TransformFinalBlock(byte[] inputBuffer, int inputOffset, int inputCount)

Parameters

inputBuffer byte[]

The final input data buffer. Must not be null.

inputOffset int

The byte offset within inputBuffer at which to begin reading.

inputCount int

The number of bytes to process from inputBuffer.

Returns

byte[]

A new byte array containing the transformed and padded, or depadded, final block.

Exceptions

ObjectDisposedException

This instance has been disposed.

InvalidOperationException

This transform has already been finalized and cannot be reused.

ArgumentNullException

inputBuffer is null.

ArgumentException

The input buffer span is invalid for the requested operation.

CryptographicException

The padding is invalid or cannot be removed during decryption.

Applies to

ProductVersions
.NET8, 10

See Also

IBlockCipher
IBlockCipherModeTransform
IPaddingStrategy