Threefish Class
Definition
- Namespace
- Bodu.Security.Cryptography
- Assembly
- Bodu.Security.Cryptography.dll
- Package
- Bodu.Security.Cryptography 1.2.0
- Source
- Threefish.cs
Serves as the abstract base class for managed implementations of the Threefish tweakable symmetric block cipher family (Threefish-256, Threefish-512, and Threefish-1024).
public abstract class Threefish : TweakableSymmetricAlgorithm, IDisposable- Inheritance
-
Threefish
- Implements
- Derived
- Inherited Members
- Extension Methods
Examples
// Use the recommended general-purpose variant - Threefish-512 over a CTR mode.
using TweakableSymmetricAlgorithm alg = new Threefish512();
alg.GenerateKey();
alg.GenerateIV();
alg.GenerateTweak();
alg.BlockMode = CipherModeKind.CTR;
using ICryptoTransform encryptor = alg.CreateEncryptor(alg.Key, alg.IV, alg.Tweak);
using var cipherText = new MemoryStream();
using (var cs = new CryptoStream(cipherText, encryptor, CryptoStreamMode.Write))
cs.Write(plaintext, 0, plaintext.Length);Remarks
Threefish is a tweakable block cipher designed by Bruce Schneier, Niels Ferguson, Stefan Lucks, Doug Whiting, Mihir Bellare, Tadayoshi Kohno, Jon Callas, and Jesse Walker as the core primitive of the Skein hash function, submitted to the NIST SHA-3 competition (2008). Each variant operates on a block whose size in bits matches its key size (256, 512, or 1024 bits) together with a 128-bit tweak. Derived classes must implement CreateCipher(byte[], byte[]) to instantiate the appropriate concrete engine.
The BlockMode property replaces the standard Mode property, enabling the use of additional or non-standard block cipher modes such as CTR and OFB.
Concrete variants.
- Threefish256 - 256-bit block, 256-bit key, 128-bit tweak.
- Threefish512 - 512-bit block, 512-bit key, 128-bit tweak (the recommended general-purpose default).
- Threefish1024 - 1024-bit block, 1024-bit key, 128-bit tweak.
Threefish is the cipher under the UBI mode of Skein - the same key-and-tweak primitive that drives Skein's hash compression. For a non-tweakable, hardware-accelerated default prefer Aes. For try-pattern transform creation that surfaces bad key/IV/tweak combinations as a false return, see TweakableSymmetricAlgorithmExtensions.
important
This class is not intended to be instantiated directly. Use Threefish256, Threefish512, or Threefish1024 instead.
Constructors
Threefish(int, int)
Initializes a new instance of the Threefish class with the specified block and tweak sizes.
protected Threefish(int blockSizeBits, int tweakSizeBits)Parameters
blockSizeBitsintThe block size in bits. Must match the Threefish variant block size (256, 512, or 1024).
tweakSizeBitsintThe tweak size in bits. 128 bits for all Threefish variants.
Remarks
Sizes are stored in bits via BlockSizeValue, KeySizeValue, and TweakSizeValue, matching the BCL convention. Conversion to bytes occurs only at the byte-array processing boundary (e.g. GenerateKey(), GenerateIV(), GenerateTweak()).
Properties
BlockMode
Gets or sets the block cipher mode of operation used when creating encryptors and decryptors.
public CipherModeKind BlockMode { get; set; }Property Value
- CipherModeKind
One of the CipherModeKind values. The default is CBC.
Remarks
This property replaces the inherited Mode property when used with BlockCipherModeFactory and the extended set of modes it supports, including CTR and OFB.
Methods
CreateCipher(byte[], byte[])
Instantiates the concrete Threefish block cipher with the specified key and tweak.
protected abstract ThreefishBlockCipher CreateCipher(byte[] key, byte[] tweak)Parameters
Returns
- ThreefishBlockCipher
A configured IBlockCipher instance for encryption or decryption.
Exceptions
- ArgumentNullException
Thrown when
keyis null.- CryptographicException
Thrown when the underlying cryptographic algorithm fails.
CreateDecryptor(byte[], byte[]?, byte[])
Creates a symmetric decryptor using the specified key, initialization vector (IV), and tweak value.
public override ICryptoTransform CreateDecryptor(byte[] rgbKey, byte[]? rgbIV, byte[] tweak)Parameters
rgbKeybyte[]The secret key to use for decryption.
rgbIVbyte[]The initialization vector to use for the decryption operation.
tweakbyte[]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, ortweakis null.- CryptographicException
Thrown if any input does not conform to the expected size, format, or algorithm-specific constraints.
CreateEncryptor(byte[], byte[]?, byte[])
Creates a symmetric encryptor using the specified key, initialization vector (IV), and tweak value.
public override ICryptoTransform CreateEncryptor(byte[] rgbKey, byte[]? rgbIV, byte[] tweak)Parameters
rgbKeybyte[]The secret key to use for encryption.
rgbIVbyte[]The initialization vector to use for the encryption operation.
tweakbyte[]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, ortweakis 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
disposingbooltrue to release both managed and unmanaged resources; false to release only unmanaged resources.
Remarks
Marks the instance as disposed, zeroes any retained key and IV buffers, and delegates the tweak buffer cleanup to the base implementation.
GenerateIV()
When overridden in a derived class, generates a random initialization vector (IV) to use for the algorithm.
public override void GenerateIV()GenerateKey()
When overridden in a derived class, generates a random key (Key) to use for the algorithm.
public override void GenerateKey()GenerateTweak()
Generates a new tweak value for the algorithm based on the current TweakSize.
public override 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.
Applies to
| Product | Versions |
|---|---|
| .NET | 8, 10 |