4 * Fast, portable, and easy-to-use Twofish implementation,
\r
6 * Copyright (c) 2002 by Niels Ferguson.
\r
8 * See the twofish.c file for the details of the how and why of this code.
\r
10 * The author hereby grants a perpetual license to everybody to
\r
11 * use this code for any purpose as long as the copyright message is included
\r
12 * in the source code of this or any derived work.
\r
20 * The following definitions have to be fixed for each particular platform
\r
21 * you work on. If you have a multi-platform program, you no doubt have
\r
22 * portable definitions that you can substitute here without changing
\r
23 * the rest of the code.
\r
25 * The defaults provided here should work on most PC compilers.
\r
30 * A Twofish_Byte must be an unsigned 8-bit integer.
\r
31 * It must also be the elementary data size of your C platform,
\r
32 * i.e. sizeof( Twofish_Byte ) == 1.
\r
34 typedef unsigned char Twofish_Byte;
\r
37 * A Twofish_UInt32 must be an unsigned integer of at least 32 bits.
\r
39 * This type is used only internally in the implementation, so ideally it
\r
40 * would not appear in the header file, but it is used inside the
\r
41 * Twofish_key structure which means it has to be included here.
\r
43 typedef unsigned int Twofish_UInt32;
\r
47 * END OF PLATFORM FIXES
\r
48 * =====================
\r
50 * You should not have to touch the rest of this file, but the code
\r
51 * in twofish.c has a few things you need to fix too.
\r
56 * Structure that contains a prepared Twofish key.
\r
57 * A cipher key is used in two stages. In the first stage it is converted
\r
58 * form the original form to an internal representation.
\r
59 * This internal form is then used to encrypt and decrypt data.
\r
60 * This structure contains the internal form. It is rather large: 4256 bytes
\r
61 * on a platform with 32-bit unsigned values.
\r
63 * Treat this as an opague structure, and don't try to manipulate the
\r
64 * elements in it. I wish I could hide the inside of the structure,
\r
65 * but C doesn't allow that.
\r
70 Twofish_UInt32 s[4][256]; /* pre-computed S-boxes */
\r
71 Twofish_UInt32 K[40]; /* Round key words */
\r
77 * Initialise and test the Twofish implementation.
\r
79 * This function MUST be called before any other function in the
\r
80 * Twofish implementation is called.
\r
81 * It only needs to be called once.
\r
83 * Apart from initialising the implementation it performs a self test.
\r
84 * If the Twofish_fatal function is not called, the code passed the test.
\r
85 * (See the twofish.c file for details on the Twofish_fatal function.)
\r
87 extern void Twofish_initialise();
\r
91 * Convert a cipher key to the internal form used for
\r
92 * encryption and decryption.
\r
94 * The cipher key is an array of bytes; the Twofish_Byte type is
\r
95 * defined above to a type suitable on your platform.
\r
97 * Any key must be converted to an internal form in the Twofisk_key structure
\r
98 * before it can be used.
\r
99 * The encryption and decryption functions only work with the internal form.
\r
100 * The conversion to internal form need only be done once for each key value.
\r
102 * Be sure to wipe all key storage, including the Twofish_key structure,
\r
103 * once you are done with the key data.
\r
104 * A simple memset( TwofishKey, 0, sizeof( TwofishKey ) ) will do just fine.
\r
106 * Unlike most implementations, this one allows any key size from 0 bytes
\r
107 * to 32 bytes. According to the Twofish specifications,
\r
108 * irregular key sizes are handled by padding the key with zeroes at the end
\r
109 * until the key size is 16, 24, or 32 bytes, whichever
\r
110 * comes first. Note that each key of irregular size is equivalent to exactly
\r
111 * one key of 16, 24, or 32 bytes.
\r
113 * WARNING: Short keys have low entropy, and result in low security.
\r
114 * Anything less than 8 bytes is utterly insecure. For good security
\r
115 * use at least 16 bytes. I prefer to use 32-byte keys to prevent
\r
116 * any collision attacks on the key.
\r
118 * The key length argument key_len must be in the proper range.
\r
119 * If key_len is not in the range 0,...,32 this routine attempts to generate
\r
120 * a fatal error (depending on the code environment),
\r
121 * and at best (or worst) returns without having done anything.
\r
124 * key Array of key bytes
\r
125 * key_len Number of key bytes, must be in the range 0,1,...,32.
\r
126 * xkey Pointer to an Twofish_key structure that will be filled
\r
127 * with the internal form of the cipher key.
\r
129 extern void Twofish_prepare_key(
\r
130 Twofish_Byte key[],
\r
132 Twofish_key * xkey
\r
137 * Encrypt a single block of data.
\r
139 * This function encrypts a single block of 16 bytes of data.
\r
140 * If you want to encrypt a larger or variable-length message,
\r
141 * you will have to use a cipher mode, such as CBC or CTR.
\r
142 * These are outside the scope of this implementation.
\r
144 * The xkey structure is not modified by this routine, and can be
\r
145 * used for further encryption and decryption operations.
\r
148 * xkey pointer to Twofish_key, internal form of the key
\r
149 * produces by Twofish_prepare_key()
\r
150 * p Plaintext to be encrypted
\r
151 * c Place to store the ciphertext
\r
153 extern void Twofish_encrypt(
\r
154 Twofish_key * xkey,
\r
155 Twofish_Byte p[16],
\r
161 * Decrypt a single block of data.
\r
163 * This function decrypts a single block of 16 bytes of data.
\r
164 * If you want to decrypt a larger or variable-length message,
\r
165 * you will have to use a cipher mode, such as CBC or CTR.
\r
166 * These are outside the scope of this implementation.
\r
168 * The xkey structure is not modified by this routine, and can be
\r
169 * used for further encryption and decryption operations.
\r
172 * xkey pointer to Twofish_key, internal form of the key
\r
173 * produces by Twofish_prepare_key()
\r
174 * c Ciphertext to be decrypted
\r
175 * p Place to store the plaintext
\r
177 extern void Twofish_decrypt(
\r
178 Twofish_key * xkey,
\r
179 Twofish_Byte c[16],
\r