Twofish

Twofish

Documentation

#include <cryptopp/twofish.h>

Twofish is a 128-bit (16 bytes) block cipher designed by Bruce Schneier. The cipher uses a 128-bit, 192-bit or 256-bit key. See Schneier's The Twofish Encryption Algorithm for details.

Note: if your project is using encryption alone to secure your data, encryption alone is usually not enough. Please take a moment to read Authenticated Encryption and consider using an algorithm or mode like CCM, GCM, EAX or ChaCha20Poly1305.

Sample Programs

There are three sample programs. The first shows Twofish key and block sizes. The second and third use filters in a pipeline. Pipelining is a high level abstraction and it handles buffering input, buffering output and padding for you.

If you are benchmarking then you may want to visit Benchmarks | Sample Program . It shows you how to use StreamTransformation::ProcessString method to process blocks at a time. Calling a cipher's ProcessString or ProcessBlock eventually call a cipher's ProcessAndXorBlock or AdvancedProcessBlocks, and they are the lowest level API you can use.

The first snippet dumps the minimum, maximum, and default key lengths used by Twofish.

cout << "key length: " << Twofish::DEFAULT_KEYLENGTH << endl;
cout << "key length (min): " << Twofish::MIN_KEYLENGTH << endl;
cout << "key length (max): " << Twofish::MAX_KEYLENGTH << endl;
cout << "block size: " << Twofish::BLOCKSIZE << endl;

Output from the above snippet produces the following. Notice the default key size is 128 bits or 16 bytes.

key length: 16
key length (min): 0
key length (max): 32
block size: 16

The following program demonstrates CBC encryption using Twofish. The key is declared on the stack using a SecByteBlock to ensure the sensitive material is zeroized. Similar could be used for both plain text and recovered text.

AutoSeededRandomPool prng;

SecByteBlock key(Twofish::DEFAULT_KEYLENGTH);
prng.GenerateBlock(key, key.size());

byte iv[Twofish::BLOCKSIZE];
prng.GenerateBlock(iv, sizeof(iv));

string plain = "CBC Mode Test";
string cipher, encoded, recovered;

/*********************************\
\*********************************/

try
{
    cout << "plain text: " << plain << endl;

    CBC_Mode< Twofish >::Encryption e;
    e.SetKeyWithIV(key, key.size(), iv);

    // The StreamTransformationFilter adds padding
    //  as required. ECB and CBC Mode must be padded
    //  to the block size of the cipher.
    StringSource ss1(plain, true, 
        new StreamTransformationFilter(e,
            new StringSink(cipher)
        ) // StreamTransformationFilter
    ); // StringSource
}
catch(const CryptoPP::Exception& e)
{
    cerr << e.what() << endl;
    exit(1);
}

/*********************************\
\*********************************/

// Pretty print
StringSource ss2(cipher, true,
    new HexEncoder(
        new StringSink(encoded)
    ) // HexEncoder
); // StringSource

cout << "cipher text: " << encoded << endl;

/*********************************\
\*********************************/

try
{
    CBC_Mode< Twofish >::Decryption d;
    d.SetKeyWithIV(key, key.size(), iv);

    // The StreamTransformationFilter removes
    //  padding as required.
    StringSource ss3(cipher, true, 
        new StreamTransformationFilter(d,
            new StringSink(recovered)
        ) // StreamTransformationFilter
    ); // StringSource

    cout << "recovered text: " << recovered << endl;
}
catch(const CryptoPP::Exception& e)
{
    cerr << e.what() << endl;
    exit(1);
}

A typical output is shown below. Note that each run will produce different results because the key and initialization vector are randomly generated.

$ ./Driver.exe
key: 6B990E620635B4C36A1B737487CEAD8D
iv: 05C9428085EE3F34D7ECE73C5628F605
plain text: CBC Mode Test
cipher text: BCD4B28F01B0CB68424FEFED3D9483BA
recovered text: CBC Mode Test

By switching to EAX mode, authenticity assurances can placed on the cipher text for nearly no programming costs. Below the StreamTransformationFilter was replaced by AuthenticatedEncryptionFilter and AuthenticatedDecryptionFilter.

EAX< Twofish >::Encryption e;
e.SetKeyWithIV(key, key.size(), iv);

StringSource ss1(plain, true, 
    new AuthenticatedEncryptionFilter(e,
        new StringSink(cipher)
    ) // StreamTransformationFilter
); // StringSource

...

EAX< Twofish >::Decryption d;
d.SetKeyWithIV(key, key.size(), iv);

StringSource ss2(cipher, true, 
    new AuthenticatedDecryptionFilter(d,
        new StringSink(recovered)
    ) // StreamTransformationFilter
); // StringSource

Typical output is as follows. Notice the additional cipher text bytes due to the MAC bytes. See EAX Mode for details.

$ ./Driver.exe
key: 71A1136E5767B4B5D9EB88494F03A1C4
iv: AE8B062CF0C0CED9FF64A40B9FAAB9C1
plain text: EAX Mode Test
cipher text: F9227CCB97F61D825898F3437EFE1B55DC4EB111EC01E23964721A63AC
recovered text: EAX Mode Test

To manually insert bytes into the filter, perform multiple Puts. Though Get is used below, a StringSink could easily be attached and save the administrivia.

const size_t SIZE = 16 * 4;
string plain(SIZE, 0x00);

for(size_t i = 0; i < plain.size(); i++)
    plain[i] = 'A' + (i%26);
...

CBC_Mode < Twofish >::Encryption encryption(key, sizeof(key), iv);
StreamTransformationFilter encryptor(encryption, NULL);

for(size_t j = 0; j < plain.size(); j++)
    encryptor.Put((byte)plain[j]);

encryptor.MessageEnd();
size_t ready = encryptor.MaxRetrievable();

string cipher(ready, 0x00);
encryptor.Get((byte*) &cipher[0], cipher.size());

Downloads

Twofish-EAX-Filter.zip - encryption and decryption using Twofish in EAX mode with filters (confidentiality and authenticity)

Twofish-CBC-Filter.zip - encryption and decryption using Twofish in CBC mode with filters (confidentiality only)

Twofish-CTR-Filter.zip - encryption and decryption using Twofish in CTR mode with filters (confidentiality only)

Twofish-ECB-Filter.zip - encryption and decryption using Twofish in ECB mode with filters (confidentiality only)