CbcModeTransform Class
Definition
- Namespace
- Bodu.Security.Cryptography
- Assembly
- Bodu.Security.Cryptography.dll
- Package
- Bodu.Security.Cryptography 1.3.0
- Source
- CbcModeTransform.cs
Applies the Cipher Block Chaining (CBC) mode transformation to an underlying IBlockCipher.
public sealed class CbcModeTransform : IBlockCipherModeTransform, IDisposable
- Inheritance
-
CbcModeTransform
- Implements
- Inherited Members
- Extension Methods
Examples
using System.Security.Cryptography;
using Bodu.Security.Cryptography;
// Most callers set BlockMode = CipherModeKind.CBC on a SymmetricAlgorithm wrapper instead of using this directly.
using IBlockCipher cipher = new AesBlockCipher(key);
byte[] iv = RandomNumberGenerator.GetBytes(cipher.BlockSize / 8); // unique per message
IBlockCipherModeTransform cbc = new CbcModeTransform(cipher, iv);
byte[] ciphertext = new byte[paddedPlaintext.Length];
int written = cbc.Transform(paddedPlaintext, ciphertext, encrypt: true);
Remarks
Encryption computes Cᵢ = E(Pᵢ ⊕ Cᵢ₋₁) with C₋₁ = IV, and decryption inverts this as
Pᵢ = D(Cᵢ) ⊕ Cᵢ₋₁. See panel 2 of the diagram above: the dashed feedback line feeds each ciphertext
block forward into the XOR that precedes the next encryption, and the IV supplies that feedback for the very first
block.
The initialization vector must equal the cipher block size in length and should be unpredictable for each message; repeating an IV under the same key weakens confidentiality. The instance retains the most recent ciphertext block as the chaining value, so successive calls to Transform(ReadOnlySpan<byte>, Span<byte>, bool) continue the stream.
When to use CBC. The traditional confidentiality-only mode - the right pick when interoperating
with legacy protocols (TLS up to 1.2, JCE defaults, many file formats) or when an authenticated mode is impractical.
CBC requires plaintext to be a multiple of the block size, so it is almost always paired with
Pkcs7Padding. For new designs prefer GcmModeTransform or
EaxModeTransform, both of which authenticate as well as encrypt; CBC plus a separate MAC is fragile
and easy to misuse. Decryption with strippable padding is vulnerable to padding-oracle attacks. The pad-byte
validation is constant-time (each padding strategy's Unpad - see Pkcs7Padding - walks the full
final block with branchless masks), but that alone is not a complete defense - the depadded length still varies with
the pad count and an invalid block throws. Callers must authenticate the ciphertext (a MAC verified with
FixedTimeEquals(ReadOnlySpan<byte>, ReadOnlySpan<byte>),
or an AEAD mode) before depadding, so a padding failure is never observable to an attacker.
CBC encryption is sequential: each block chains on the previous ciphertext block. Decryption is not, because every chaining value is already in the ciphertext, so runs of blocks are decrypted with one multi-block DecryptBlocks(ReadOnlySpan<byte>, Span<byte>) call. Random access into the ciphertext is not supported.
Constructors
CbcModeTransform(IBlockCipher, byte[])
Initializes a new instance of the CbcModeTransform class with the specified cipher and initialization vector.
public CbcModeTransform(IBlockCipher cipher, byte[] iv)
Parameters
cipherIBlockCipherThe block cipher over which CBC is applied.
ivbyte[]The initialization vector used as the chaining value for the first block. A defensive copy is taken.
Exceptions
- ArgumentNullException
Thrown if
cipherorivis null.- ArgumentException
Thrown if the length of
ivdoes not equal the block size ofcipher.
Methods
Dispose()
Releases the resources used by this instance and zeroes the running chaining vector so that key-equivalent IV state does not linger in memory after disposal. The underlying IBlockCipher is not disposed by this type - ownership remains with the caller.
public void Dispose()
Remarks
Idempotent.
Transform(ReadOnlySpan<byte>, Span<byte>, bool)
Transforms input under the mode's chaining strategy and writes the result to
output.
public 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 |