TweakableSymmetricAlgorithmExtensions Class

Definition

Namespace

Bodu.Security.Cryptography.Extensions

Assembly

Bodu.Security.Cryptography.dll

Package

Bodu.Security.Cryptography 1.2.0

Source

TweakableSymmetricAlgorithmExtensions.TryCreateDecryptor.cs

Extends TweakableSymmetricAlgorithm with try-pattern transform creation that surfaces invalid key, IV, or tweak material as a false return rather than a thrown CryptographicException.

public static class TweakableSymmetricAlgorithmExtensions

Inheritance

object

TweakableSymmetricAlgorithmExtensions

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

Tweakable block ciphers - Threefish in this library, and tweakable variants used as building blocks for AEAD constructions - accept a third keying input alongside the key and IV: the tweak. The tweak is a per-message value that varies the cipher's behavior without renegotiating a key, making it a natural fit for disk encryption, authenticated modes, and protocols that bind ciphertext to a position or message identifier. Constructing an encryptor or decryptor for one of these algorithms requires all three values to be valid in concert; the BCL-style approach is to throw on the first invalid value, which is awkward when the values are user-supplied.

The API surface is intentionally narrow and parallels TryCreateEncryptor(SymmetricAlgorithm, byte[], byte[], out ICryptoTransform?) :

• TryCreateEncryptor Wraps CreateEncryptor() and the explicit (key, iv, tweak) overload, returning false on any cryptographic validation failure.
• TryCreateDecryptor The matching pair for CreateDecryptor().

All four overloads validate algorithm eagerly and throw ArgumentNullException when it is null; only cryptographic failures from the underlying transform are converted to a false return. The returned ICryptoTransform is owned by the caller and must be disposed.

using System.Security.Cryptography;
using Bodu.Security.Cryptography;
using Bodu.Security.Cryptography.Extensions;

using TweakableSymmetricAlgorithm tf = new Threefish256();

// 1. Validate user-supplied key/IV/tweak without catching CryptographicException.
if (!tf.TryCreateEncryptor(suppliedKey, suppliedIv, suppliedTweak, out ICryptoTransform? encryptor))
    return BadRequest("invalid key, iv, or tweak");
using (encryptor) { /* … encrypt with the validated transform … */ }

// 2. Round-trip pairing - same try-pattern shape for the decryptor.
if (tf.TryCreateDecryptor(suppliedKey, suppliedIv, suppliedTweak, out ICryptoTransform? decryptor))
{
    using (decryptor) { /* … decrypt … */ }
}

Methods

TryCreateDecryptor(TweakableSymmetricAlgorithm, byte[], byte[], byte[], out ICryptoTransform?)

Attempts to create a decryptor using the specified key, initialization vector, and tweak.

public static bool TryCreateDecryptor(this TweakableSymmetricAlgorithm algorithm, byte[] key, byte[] iv, byte[] tweak, out ICryptoTransform? transform)

Parameters

algorithm TweakableSymmetricAlgorithm

The tweakable symmetric algorithm to use for decryption. Must not be null.

key byte[]

The decryption key.

iv byte[]

The initialization vector.

tweak byte[]

The tweak value to apply during decryption.

transform ICryptoTransform

When this method returns, contains the created ICryptoTransform if the operation succeeded; otherwise, null.

Returns

bool

true if the decryptor was successfully created; otherwise, false.

Remarks

This method wraps CreateDecryptor(byte[], byte[]?, byte[]) in a try/catch block, returning false if the operation fails due to an invalid key, IV, or tweak. Use this overload when all keying material must be supplied explicitly.

Exceptions

ArgumentNullException

Thrown if algorithm is null.

TryCreateDecryptor(TweakableSymmetricAlgorithm, out ICryptoTransform?)

Attempts to create a decryptor using the current Key, IV, and Tweak values of the algorithm.

public static bool TryCreateDecryptor(this TweakableSymmetricAlgorithm algorithm, out ICryptoTransform? transform)

Parameters

algorithm TweakableSymmetricAlgorithm

The tweakable symmetric algorithm to use for decryption. Must not be null.

transform ICryptoTransform

When this method returns, contains the created ICryptoTransform if the operation succeeded; otherwise, null.

Returns

bool

true if the decryptor was successfully created; otherwise, false.

Remarks

This method wraps CreateDecryptor() in a try/catch block, returning false if the operation fails due to an invalid or uninitialized key, IV, or tweak.

Use this overload when the algorithm has already been fully configured. To supply keying material explicitly, use TryCreateDecryptor(TweakableSymmetricAlgorithm, byte[], byte[], byte[], out ICryptoTransform?) .

Exceptions

ArgumentNullException

Thrown if algorithm is null.

TryCreateEncryptor(TweakableSymmetricAlgorithm, byte[], byte[], byte[], out ICryptoTransform?)

Attempts to create an encryptor using the specified key, initialization vector, and tweak.

public static bool TryCreateEncryptor(this TweakableSymmetricAlgorithm algorithm, byte[] key, byte[] iv, byte[] tweak, out ICryptoTransform? transform)

Parameters

algorithm TweakableSymmetricAlgorithm

The tweakable symmetric algorithm to use for encryption. Must not be null.

key byte[]

The encryption key.

iv byte[]

The initialization vector.

tweak byte[]

The tweak value to apply during encryption.

transform ICryptoTransform

When this method returns, contains the created ICryptoTransform if the operation succeeded; otherwise, null.

Returns

bool

true if the encryptor was successfully created; otherwise, false.

Remarks

This method wraps CreateEncryptor(byte[], byte[]?, byte[]) in a try/catch block, returning false if the operation fails due to an invalid key, IV, or tweak. Use this overload when all keying material must be supplied explicitly.

Exceptions

ArgumentNullException

Thrown if algorithm is null.

TryCreateEncryptor(TweakableSymmetricAlgorithm, out ICryptoTransform?)

Attempts to create an encryptor using the current Key, IV, and Tweak values of the algorithm.

public static bool TryCreateEncryptor(this TweakableSymmetricAlgorithm algorithm, out ICryptoTransform? transform)

Parameters

algorithm TweakableSymmetricAlgorithm

The tweakable symmetric algorithm to use for encryption. Must not be null.

transform ICryptoTransform

When this method returns, contains the created ICryptoTransform if the operation succeeded; otherwise, null.

Returns

bool

true if the encryptor was successfully created; otherwise, false.

Remarks

This method wraps CreateEncryptor() in a try/catch block, returning false if the operation fails due to an invalid or uninitialized key, IV, or tweak.

Use this overload when the algorithm has already been fully configured. To supply keying material explicitly, use TryCreateEncryptor(TweakableSymmetricAlgorithm, byte[], byte[], byte[], out ICryptoTransform?) .

Exceptions

ArgumentNullException

Thrown if algorithm is null.

Applies to

Product	Versions
.NET	8, 10