Alexandre Lision | 7fd5d3d | 2013-12-04 13:06:40 -0500 | [diff] [blame] | 1 | /* |
| 2 | * Fast, portable, and easy-to-use Twofish implementation, |
| 3 | * Version 0.3. |
| 4 | * Copyright (c) 2002 by Niels Ferguson. |
| 5 | * |
| 6 | * See the twofish.c file for the details of the how and why of this code. |
| 7 | * |
| 8 | * The author hereby grants a perpetual license to everybody to |
| 9 | * use this code for any purpose as long as the copyright message is included |
| 10 | * in the source code of this or any derived work. |
| 11 | */ |
| 12 | |
| 13 | |
| 14 | /* |
| 15 | * PLATFORM FIXES |
| 16 | * ============== |
| 17 | * |
| 18 | * The following definitions have to be fixed for each particular platform |
| 19 | * you work on. If you have a multi-platform program, you no doubt have |
| 20 | * portable definitions that you can substitute here without changing |
| 21 | * the rest of the code. |
| 22 | * |
| 23 | * The defaults provided here should work on most PC compilers. |
| 24 | */ |
| 25 | |
| 26 | #ifndef TWOFISH_H |
| 27 | #define TWOFISH_H |
| 28 | |
| 29 | #ifdef __cplusplus |
| 30 | extern "C" |
| 31 | { |
| 32 | #endif |
| 33 | |
| 34 | /** |
| 35 | * @file twofish.h |
| 36 | * @brief Function that provide basic Twofish crypto support |
| 37 | * |
| 38 | * @ingroup GNU_ZRTP |
| 39 | * @{ |
| 40 | */ |
| 41 | |
| 42 | /** |
| 43 | * A Twofish_Byte must be an unsigned 8-bit integer. |
| 44 | * |
| 45 | * It must also be the elementary data size of your C platform, |
| 46 | * i.e. sizeof( Twofish_Byte ) == 1. |
| 47 | */ |
| 48 | typedef unsigned char Twofish_Byte; |
| 49 | |
| 50 | /** |
| 51 | * A Twofish_UInt32 must be an unsigned integer of at least 32 bits. |
| 52 | * |
| 53 | * This type is used only internally in the implementation, so ideally it |
| 54 | * would not appear in the header file, but it is used inside the |
| 55 | * Twofish_key structure which means it has to be included here. |
| 56 | */ |
| 57 | typedef unsigned int Twofish_UInt32; |
| 58 | |
| 59 | |
| 60 | /* |
| 61 | * END OF PLATFORM FIXES |
| 62 | * ===================== |
| 63 | * |
| 64 | * You should not have to touch the rest of this file, but the code |
| 65 | * in twofish.c has a few things you need to fix too. |
| 66 | */ |
| 67 | |
| 68 | /** |
| 69 | * Return codes |
| 70 | */ |
| 71 | #define SUCCESS 1 |
| 72 | #define ERR_UINT32 -2 |
| 73 | #define ERR_BYTE -3 |
| 74 | #define ERR_GET32 -4 |
| 75 | #define ERR_PUT32 -5 |
| 76 | #define ERR_ROLR -6 |
| 77 | #define ERR_BSWAP -7 |
| 78 | #define ERR_SELECTB -8 |
| 79 | #define ERR_TEST_ENC -9 |
| 80 | #define ERR_TEST_DEC -10 |
| 81 | #define ERR_SEQ_ENC -11 |
| 82 | #define ERR_SEQ_DEC -12 |
| 83 | #define ERR_ODD_KEY -13 |
| 84 | #define ERR_INIT -14 |
| 85 | #define ERR_KEY_LEN -15 |
| 86 | #define ERR_ILL_ARG -16 |
| 87 | |
| 88 | |
| 89 | /** |
| 90 | * Structure that contains a prepared Twofish key. |
| 91 | * |
| 92 | * A cipher key is used in two stages. In the first stage it is converted |
| 93 | * form the original form to an internal representation. |
| 94 | * This internal form is then used to encrypt and decrypt data. |
| 95 | * This structure contains the internal form. It is rather large: 4256 bytes |
| 96 | * on a platform with 32-bit unsigned values. |
| 97 | * |
| 98 | * Treat this as an opague structure, and don't try to manipulate the |
| 99 | * elements in it. I wish I could hide the inside of the structure, |
| 100 | * but C doesn't allow that. |
| 101 | */ |
| 102 | typedef |
| 103 | struct |
| 104 | { |
| 105 | Twofish_UInt32 s[4][256]; /* pre-computed S-boxes */ |
| 106 | Twofish_UInt32 K[40]; /* Round key words */ |
| 107 | } |
| 108 | Twofish_key; |
| 109 | |
| 110 | |
| 111 | /** |
| 112 | * Initialise and test the Twofish implementation. |
| 113 | * |
| 114 | * This function MUST be called before any other function in the |
| 115 | * Twofish implementation is called. |
| 116 | * It only needs to be called once. |
| 117 | * |
| 118 | * Apart from initialising the implementation it performs a self test. |
| 119 | * If the Twofish_fatal function is not called, the code passed the test. |
| 120 | * (See the twofish.c file for details on the Twofish_fatal function.) |
| 121 | * |
| 122 | * @returns a negative number if an error happend, +1 otherwise |
| 123 | */ |
| 124 | extern int Twofish_initialise(); |
| 125 | |
| 126 | |
| 127 | /** |
| 128 | * Convert a cipher key to the internal form used for |
| 129 | * encryption and decryption. |
| 130 | * |
| 131 | * The cipher key is an array of bytes; the Twofish_Byte type is |
| 132 | * defined above to a type suitable on your platform. |
| 133 | * |
| 134 | * Any key must be converted to an internal form in the Twofisk_key structure |
| 135 | * before it can be used. |
| 136 | * The encryption and decryption functions only work with the internal form. |
| 137 | * The conversion to internal form need only be done once for each key value. |
| 138 | * |
| 139 | * Be sure to wipe all key storage, including the Twofish_key structure, |
| 140 | * once you are done with the key data. |
| 141 | * A simple memset( TwofishKey, 0, sizeof( TwofishKey ) ) will do just fine. |
| 142 | * |
| 143 | * Unlike most implementations, this one allows any key size from 0 bytes |
| 144 | * to 32 bytes. According to the Twofish specifications, |
| 145 | * irregular key sizes are handled by padding the key with zeroes at the end |
| 146 | * until the key size is 16, 24, or 32 bytes, whichever |
| 147 | * comes first. Note that each key of irregular size is equivalent to exactly |
| 148 | * one key of 16, 24, or 32 bytes. |
| 149 | * |
| 150 | * WARNING: Short keys have low entropy, and result in low security. |
| 151 | * Anything less than 8 bytes is utterly insecure. For good security |
| 152 | * use at least 16 bytes. I prefer to use 32-byte keys to prevent |
| 153 | * any collision attacks on the key. |
| 154 | * |
| 155 | * The key length argument key_len must be in the proper range. |
| 156 | * If key_len is not in the range 0,...,32 this routine attempts to generate |
| 157 | * a fatal error (depending on the code environment), |
| 158 | * and at best (or worst) returns without having done anything. |
| 159 | * |
| 160 | * @param key Array of key bytes |
| 161 | * @param key_len Number of key bytes, must be in the range 0,1,...,32. |
| 162 | * @param xkey Pointer to an Twofish_key structure that will be filled |
| 163 | * with the internal form of the cipher key. |
| 164 | * @returns a negative number if an error happend, +1 otherwise |
| 165 | */ |
| 166 | extern int Twofish_prepare_key( |
| 167 | Twofish_Byte key[], |
| 168 | int key_len, |
| 169 | Twofish_key * xkey |
| 170 | ); |
| 171 | |
| 172 | |
| 173 | /** |
| 174 | * Encrypt a single block of data. |
| 175 | * |
| 176 | * This function encrypts a single block of 16 bytes of data. |
| 177 | * If you want to encrypt a larger or variable-length message, |
| 178 | * you will have to use a cipher mode, such as CBC or CTR. |
| 179 | * These are outside the scope of this implementation. |
| 180 | * |
| 181 | * The xkey structure is not modified by this routine, and can be |
| 182 | * used for further encryption and decryption operations. |
| 183 | * |
| 184 | * @param xkey pointer to Twofish_key, internal form of the key |
| 185 | * produces by Twofish_prepare_key() |
| 186 | * @param p Plaintext to be encrypted |
| 187 | * @param c Place to store the ciphertext |
| 188 | */ |
| 189 | extern void Twofish_encrypt( |
| 190 | Twofish_key * xkey, |
| 191 | Twofish_Byte p[16], |
| 192 | Twofish_Byte c[16] |
| 193 | ); |
| 194 | |
| 195 | |
| 196 | /** |
| 197 | * Decrypt a single block of data. |
| 198 | * |
| 199 | * This function decrypts a single block of 16 bytes of data. |
| 200 | * If you want to decrypt a larger or variable-length message, |
| 201 | * you will have to use a cipher mode, such as CBC or CTR. |
| 202 | * These are outside the scope of this implementation. |
| 203 | * |
| 204 | * The xkey structure is not modified by this routine, and can be |
| 205 | * used for further encryption and decryption operations. |
| 206 | * |
| 207 | * @param xkey pointer to Twofish_key, internal form of the key |
| 208 | * produces by Twofish_prepare_key() |
| 209 | * @param c Ciphertext to be decrypted |
| 210 | * @param p Place to store the plaintext |
| 211 | */ |
| 212 | extern void Twofish_decrypt( |
| 213 | Twofish_key * xkey, |
| 214 | Twofish_Byte c[16], |
| 215 | Twofish_Byte p[16] |
| 216 | ); |
| 217 | |
| 218 | |
| 219 | /** |
| 220 | * Encrypt data in CFB mode. |
| 221 | * |
| 222 | * This function encrypts data in CFB mode. |
| 223 | * |
| 224 | * The key structure is not modified by this routine, and can be |
| 225 | * used for further encryption and decryption operations. |
| 226 | * |
| 227 | * @param keyCtx pointer to Twofish_key, internal form of the key |
| 228 | * produced by Twofish_prepare_key() |
| 229 | * @param in Plaintext to be encrypted |
| 230 | * @param out Place to store the ciphertext |
| 231 | * @param len number of bytes to encrypt. |
| 232 | * @param ivec initialization vector for this CFB mode encryption. |
| 233 | * @param num pointer to integer that holds number of available crypto bytes. |
| 234 | */ |
| 235 | void Twofish_cfb128_encrypt(Twofish_key* keyCtx, Twofish_Byte* in, |
| 236 | Twofish_Byte* out, size_t len, |
| 237 | Twofish_Byte* ivec, int *num); |
| 238 | |
| 239 | /** |
| 240 | * Decrypt data in CFB mode. |
| 241 | * |
| 242 | * This function decrypts data in CFB. |
| 243 | * |
| 244 | * The key structure is not modified by this routine, and can be |
| 245 | * used for further encryption and decryption operations. |
| 246 | * |
| 247 | * @param keyCtx pointer to Twofish_key, internal form of the key |
| 248 | * produced by Twofish_prepare_key() |
| 249 | * @param in Ciphertext to be decrypted |
| 250 | * @param out Place to store the plaintext |
| 251 | * @param len number of bytes to decrypt. |
| 252 | * @param ivec initialization vector for this CFB mode encryption. |
| 253 | * @param num pointer to integer that holds number of available crypto bytes. |
| 254 | */ |
| 255 | void Twofish_cfb128_decrypt(Twofish_key* keyCtx, Twofish_Byte* in, |
| 256 | Twofish_Byte* out, size_t len, |
| 257 | Twofish_Byte* ivec, int *num); |
| 258 | /** |
| 259 | * @} |
| 260 | */ |
| 261 | #ifdef __cplusplus |
| 262 | } |
| 263 | #endif |
| 264 | |
| 265 | #endif |