Table of Contents

TweakableSymmetricAlgorithm Class

Definition

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

Serves as the abstract base class for tweakable symmetric algorithms, which accept an additional tweak value in addition to the key and initialization vector.

public abstract class TweakableSymmetricAlgorithm : SymmetricAlgorithm, IDisposable
Inheritance
TweakableSymmetricAlgorithm
Implements
Derived
Inherited Members
Extension Methods

Examples

// Construct via a concrete derivative - Threefish is the production tweakable cipher family.
using TweakableSymmetricAlgorithm alg = new Threefish256();
alg.GenerateKey();
alg.GenerateIV();
alg.GenerateTweak();      // unique to TweakableSymmetricAlgorithm - supplies the per-message tweak

// CreateEncryptor / CreateDecryptor accept the additional tweak argument.
using ICryptoTransform encryptor = alg.CreateEncryptor(alg.Key, alg.IV, alg.Tweak);
using ICryptoTransform decryptor = alg.CreateDecryptor(alg.Key, alg.IV, alg.Tweak);

// The companion try-pattern wrappers gate over user-supplied keying material.
if (alg.TryCreateEncryptor(userKey, userIv, userTweak, out ICryptoTransform? safe))
{
    using (safe) { /* encrypt */ }
}

Remarks

This class extends SymmetricAlgorithm with a Tweak property, a LegalTweakSizes enumeration, and tweak-aware CreateEncryptor / CreateDecryptor overloads. It is intended for ciphers such as Threefish that take a tweak input as part of their cryptographic contract.

Derived classes must override CreateEncryptor(byte[], byte[]?, byte[]), CreateDecryptor(byte[], byte[]?, byte[]), and GenerateTweak().

What is a tweak? A tweak is a third keying input alongside key and IV - a per-message (or per-position) value that varies the cipher's behavior without renegotiating the key. Tweaks are what make tweakable block ciphers a natural fit for disk encryption (the sector number is the tweak), authenticated modes built from the cipher (the message position is the tweak), and protocols that need to bind ciphertext to a position or message identifier.

Concrete implementations. The library ships Threefish256, Threefish512, and Threefish1024 as the production tweakable ciphers (Threefish is the cipher under the hood of Skein). The Serpent256/Serpent512/Serpent1024 wide-block variants are also tweakable but non-standard - see their headers for the experimental-only caveat.

Companion try-pattern helpers. The TweakableSymmetricAlgorithmExtensions class adds TryCreateEncryptor and TryCreateDecryptor wrappers that return false when the supplied key/IV/tweak combination is invalid - useful when keying material is user-supplied.

Constructors

TweakableSymmetricAlgorithm() 

protected TweakableSymmetricAlgorithm()

Fields

LegalTweakSizesValue

Specifies the tweak sizes, in bits, that are supported by the algorithm.

[MaybeNull]
protected KeySizes[] LegalTweakSizesValue

Field Value

KeySizes[]

Remarks

Each KeySizes entry expresses its minimum, maximum, and skip values in bits. This backing field defines the range of acceptable tweak sizes for a given algorithm and is used internally by the LegalTweakSizes property.

TweakSizeValue

Stores the currently configured tweak size, in bits, for the algorithm instance.

protected int TweakSizeValue

Field Value

int

Remarks

This backing field represents the effective size of the tweak currently configured via TweakSize or Tweak.

TweakValue

Stores the current tweak value used by the algorithm.

protected byte[]? TweakValue

Field Value

byte[]

Remarks

The value stored here is used internally and may be cleared or regenerated via Dispose(bool), GenerateTweak(), or changes to TweakSize. Defensive copies are used when accessing or assigning through the Tweak property.

Properties

LegalTweakSizes

Gets the tweak sizes, in bits, that are supported by the symmetric algorithm.

public virtual KeySizes[] LegalTweakSizes { get; }

Property Value

KeySizes[]

An array of KeySizes instances indicating the valid minimum, maximum, and step sizes supported for tweak values, all expressed in bits. Divide by 8 to obtain the equivalent byte lengths.

Remarks

This property returns a cloned copy of the internal tweak size definitions to prevent external modification. Override this property in derived types to define custom tweak size support for a specific algorithm.

Tweak

Gets or sets the tweak value for the symmetric algorithm.

public virtual byte[] Tweak { get; set; }

Property Value

byte[]

A byte array representing the tweak to be used. Must conform to one of the valid lengths specified by LegalTweakSizes.

Remarks

If the tweak is not explicitly set, it will be lazily generated via GenerateTweak(). Defensive copies are made during assignment and retrieval to prevent external mutation.

Exceptions

ArgumentNullException

Thrown when the value is null.

CryptographicException

Thrown when the tweak size is invalid or the tweak has not been set and TweakSize is missing or invalid.

TweakSize

Gets or sets the tweak size, in bits, of the cryptographic operation for the tweakable cipher (for example, 128 bits / 16 bytes for the Threefish family).

public virtual int TweakSize { get; set; }

Property Value

int

The tweak size, in bits. Must match one of the values defined in LegalTweakSizes. Divide by 8 to obtain the equivalent byte length used when allocating the Tweak buffer.

Remarks

Changing this value clears the current tweak. A new one can be generated via GenerateTweak().

Exceptions

CryptographicException

Thrown when the value does not match a valid tweak size defined in LegalTweakSizes.

Methods

CreateDecryptor()

Creates a symmetric decryptor object with the current Key property and initialization vector (IV).

public override ICryptoTransform CreateDecryptor()

Returns

ICryptoTransform

A symmetric decryptor object.

CreateDecryptor(byte[], byte[]?)

When overridden in a derived class, creates a symmetric decryptor object with the specified Key property and initialization vector (IV).

public override ICryptoTransform CreateDecryptor(byte[] rgbKey, byte[]? rgbIV)

Parameters

rgbKey byte[]

The secret key to use for the symmetric algorithm.

rgbIV byte[]

The initialization vector to use for the symmetric algorithm.

Returns

ICryptoTransform

A symmetric decryptor object.

CreateDecryptor(byte[], byte[]?, byte[])

Creates a symmetric decryptor using the specified key, initialization vector (IV), and tweak value.

public abstract ICryptoTransform CreateDecryptor(byte[] rgbKey, byte[]? rgbIV, byte[] tweak)

Parameters

rgbKey byte[]

The secret key to use for decryption.

rgbIV byte[]

The initialization vector to use for the decryption operation.

tweak byte[]

The tweak value that modifies the decryption process.

Returns

ICryptoTransform

An ICryptoTransform instance that can be used to perform the decryption.

Remarks

This method must be implemented by derived types to support decryption with a tweak, as required by tweakable block ciphers such as Threefish.

Exceptions

ArgumentNullException

Thrown if rgbKey, rgbIV, or tweak is null.

CryptographicException

Thrown if any input does not conform to the expected size, format, or algorithm-specific constraints.

CreateEncryptor()

Creates a symmetric encryptor object with the current Key property and initialization vector (IV).

public override ICryptoTransform CreateEncryptor()

Returns

ICryptoTransform

A symmetric encryptor object.

CreateEncryptor(byte[], byte[]?)

When overridden in a derived class, creates a symmetric encryptor object with the specified Key property and initialization vector (IV).

public override ICryptoTransform CreateEncryptor(byte[] rgbKey, byte[]? rgbIV)

Parameters

rgbKey byte[]

The secret key to use for the symmetric algorithm.

rgbIV byte[]

The initialization vector to use for the symmetric algorithm.

Returns

ICryptoTransform

A symmetric encryptor object.

CreateEncryptor(byte[], byte[]?, byte[])

Creates a symmetric encryptor using the specified key, initialization vector (IV), and tweak value.

public abstract ICryptoTransform CreateEncryptor(byte[] rgbKey, byte[]? rgbIV, byte[] tweak)

Parameters

rgbKey byte[]

The secret key to use for encryption.

rgbIV byte[]

The initialization vector to use for the encryption operation.

tweak byte[]

The tweak value that modifies the encryption process.

Returns

ICryptoTransform

An ICryptoTransform instance that can be used to perform the encryption.

Remarks

This method must be implemented by derived types to support encryption with a tweak, as required by tweakable block ciphers such as Threefish.

Exceptions

ArgumentNullException

Thrown if rgbKey, rgbIV, or tweak is null.

CryptographicException

Thrown if any input does not conform to the expected size, format, or algorithm-specific constraints.

Dispose(bool)

Releases the unmanaged resources used by the SymmetricAlgorithm and optionally releases the managed resources.

protected override void Dispose(bool disposing)

Parameters

disposing bool

true to release both managed and unmanaged resources; false to release only unmanaged resources.

GenerateTweak()

Generates a new tweak value for the algorithm based on the current TweakSize.

public abstract void GenerateTweak()

Remarks

This method initializes the tweak with random or algorithm-specific data. The generated size will match the current TweakSize. If no size has been set, an exception will be thrown.

Exceptions

CryptographicException

Thrown if TweakSize is not configured to a valid size.

ThrowIfInvalidTweakSize(byte[])

Throws if the specified tweak is null or its size is not valid.

protected void ThrowIfInvalidTweakSize(byte[] tweak)

Parameters

tweak byte[]

The tweak value to validate.

Exceptions

ArgumentNullException

Thrown when tweak is null.

CryptographicException

Thrown when tweak is not supported by LegalTweakSizes.

ThrowIfInvalidTweakSize(int)

Throws an exception if the specified bit length is not a valid tweak size for this algorithm.

protected void ThrowIfInvalidTweakSize(int bitLength)

Parameters

bitLength int

The length of the tweak in bits.

Remarks

This method should be used internally to validate programmatic assignment to TweakSize or Tweak.

Exceptions

CryptographicException

Thrown if the specified bit length is not among the legal sizes defined by LegalTweakSizes.

ThrowIfTweakNotSet()

Throws if the tweak has not been set or generated.

protected void ThrowIfTweakNotSet()

Remarks

Call this method before using the Tweak property to ensure that the tweak has been initialized.

Exceptions

CryptographicException

Thrown if the internal tweak value is null or empty.

ValidTweakSize(int)

Determines whether the specified tweak size, in bits, is supported by the algorithm.

public bool ValidTweakSize(int length)

Parameters

length int

The tweak size to validate, in bits.

Returns

bool

true if the specified size matches any of the valid configurations in LegalTweakSizes; otherwise, false.

Remarks

This method checks the specified bit length against all entries in LegalTweakSizes. A size is considered valid if it falls within the defined range and aligns with the specified skip size (if any).

Applies to

ProductVersions
.NET8, 10

See Also

Threefish256
Threefish512
Threefish1024
TweakableSymmetricAlgorithmExtensions