5 Author: Pekka Riikonen <priikone@silcnet.org>
7 Copyright (C) 1997 - 2008 Pekka Riikonen
9 This program is free software; you can redistribute it and/or modify
10 it under the terms of the GNU General Public License as published by
11 the Free Software Foundation; version 2 of the License.
13 This program is distributed in the hope that it will be useful,
14 but WITHOUT ANY WARRANTY; without even the implied warranty of
15 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 GNU General Public License for more details.
20 /****h* silccrypt/Cipher Interface
24 * This is the interface for cipher functions. It provides cipher
25 * registering and unregistering routines, encryption and decryption
30 * // Allocate AES-128 cipher in CBC mode
33 * silc_cipher_alloc(SILC_CIPHER_AES_128_CBC, &aes);
35 * // Set key for encryption, key length must in bits
36 * silc_cipher_set_key(aes, key, key_len * 8, TRUE);
39 * silc_cipher_set_iv(aes, iv);
42 * silc_cipher_encrypt(aes, src, dst, len, NULL);
49 /* Forward declarations */
50 typedef struct SilcCipherObjectStruct SilcCipherObject;
52 /****s* silccrypt/SilcCipher
56 * typedef struct SilcCipherStruct *SilcCipher;
60 * This context is the actual cipher context and is allocated
61 * by silc_cipher_alloc and given as argument usually to all
62 * silc_cipher _* functions. It is freed by the silc_cipher_free
66 typedef struct SilcCipherStruct *SilcCipher;
68 /****d* silccrypt/Ciphers
76 * Supported ciphers names. These names can be given as argument
77 * to silc_cipher_alloc.
82 /* AES in CTR mode, in different key lengths */
83 #define SILC_CIPHER_AES_256_CTR "aes-256-ctr"
84 #define SILC_CIPHER_AES_192_CTR "aes-192-ctr"
85 #define SILC_CIPHER_AES_128_CTR "aes-128-ctr"
87 /* AES in CBC mode, in different key lengths */
88 #define SILC_CIPHER_AES_256_CBC "aes-256-cbc"
89 #define SILC_CIPHER_AES_192_CBC "aes-192-cbc"
90 #define SILC_CIPHER_AES_128_CBC "aes-128-cbc"
92 /* AES in CFB mode, in different key lengths */
93 #define SILC_CIPHER_AES_256_CFB "aes-256-cfb"
94 #define SILC_CIPHER_AES_192_CFB "aes-192-cfb"
95 #define SILC_CIPHER_AES_128_CFB "aes-128-cfb"
97 /* AES in ECB mode, in different key lengths */
98 #define SILC_CIPHER_AES_256_ECB "aes-256-ecb"
99 #define SILC_CIPHER_AES_192_ECB "aes-192-ecb"
100 #define SILC_CIPHER_AES_128_ECB "aes-128-ecb"
102 /* Twofish in CTR mode, in different key lengths */
103 #define SILC_CIPHER_TWOFISH_256_CTR "twofish-256-ctr"
104 #define SILC_CIPHER_TWOFISH_192_CTR "twofish-192-ctr"
105 #define SILC_CIPHER_TWOFISH_128_CTR "twofish-128-ctr"
107 /* Twofish in CBC mode, in different key lengths */
108 #define SILC_CIPHER_TWOFISH_256_CBC "twofish-256-cbc"
109 #define SILC_CIPHER_TWOFISH_192_CBC "twofish-192-cbc"
110 #define SILC_CIPHER_TWOFISH_128_CBC "twofish-128-cbc"
112 /* Twofish in CFB mode, in different key lengths */
113 #define SILC_CIPHER_TWOFISH_256_CFB "twofish-256-cfb"
114 #define SILC_CIPHER_TWOFISH_192_CFB "twofish-192-cfb"
115 #define SILC_CIPHER_TWOFISH_128_CFB "twofish-128-cfb"
117 /* Twofish in ECB mode, in different key lengths */
118 #define SILC_CIPHER_TWOFISH_256_ECB "twofish-256-ecb"
119 #define SILC_CIPHER_TWOFISH_192_ECB "twofish-192-ecb"
120 #define SILC_CIPHER_TWOFISH_128_ECB "twofish-128-ecb"
122 /* CAST-128 in CTR, CBC, CFB, ECB modes, 128-bit key length */
123 #define SILC_CIPHER_CAST5_128_CTR "cast5-128-ctr"
124 #define SILC_CIPHER_CAST5_128_CBC "cast5-128-cbc"
125 #define SILC_CIPHER_CAST5_128_CFB "cast5-128-cfb"
126 #define SILC_CIPHER_CAST5_128_ECB "cast5-128-ecb"
128 /* DES in CTR, CBC, CFB, ECB modes, 56-bit key length */
129 #define SILC_CIPHER_DES_56_CTR "des-56-ctr"
130 #define SILC_CIPHER_DES_56_CBC "des-56-cbc"
131 #define SILC_CIPHER_DES_56_CFB "des-56-cfb"
132 #define SILC_CIPHER_DES_56_ECB "des-56-ecb"
134 /* 3DES in CTR, CBC, CFB, ECB modes, 168-bit (192-bit) key length */
135 #define SILC_CIPHER_3DES_168_CTR "3des-168-ctr"
136 #define SILC_CIPHER_3DES_168_CBC "3des-168-cbc"
137 #define SILC_CIPHER_3DES_168_CFB "3des-168-cfb"
138 #define SILC_CIPHER_3DES_168_ECB "3des-168-ecb"
141 #define SILC_CIPHER_NONE "none"
144 /****d* silccrypt/Cipher-Algorithms
152 * Supported cipher algorithm names. These names can be give as argument
153 * to silc_cipher_alloc_full.
157 #define SILC_CIPHER_AES "aes" /* AES */
158 #define SILC_CIPHER_TWOFISH "twofish" /* Twofish */
159 #define SILC_CIPHER_CAST5 "cast5" /* CAST-128 */
160 #define SILC_CIPHER_DES "des" /* DES */
161 #define SILC_CIPHER_3DES "3des" /* Triple-DES */
164 /****d* silccrypt/SilcCipherMode
168 * typedef enum { ... } SilcCipherMode;
172 * Cipher modes. Notes about cipher modes and implementation:
174 * SILC_CIPHER_MODE_CBC
176 * The Cipher-block Chaining mode. The plaintext length must be
177 * multiple by the cipher block size. If it isn't the plaintext must
180 * SILC_CIPHER_MODE_CTR
182 * The Counter mode. The CTR mode does not require the plaintext length
183 * to be multiple by the cipher block size. If the last plaintext block
184 * is shorter the remaining bits of the key stream are used next time
185 * silc_cipher_encrypt is called. If silc_cipher_set_iv is called it
186 * will reset the counter for a new block (discarding any remaining
187 * bits from previous key stream). The CTR mode expects MSB first
188 * ordered counter. Note also, the counter is incremented when
189 * silc_cipher_encrypt is called for the first time, before encrypting.
191 * SILC_CIPHER_MODE_CFB
193 * The Cipher Feedback mode. The CFB mode does not require the plaintext
194 * length to be multiple by the cipher block size. If the last plaintext
195 * block is shorter the remaining bits of the stream are used next time
196 * silc_cipher_encrypt is called. If silc_cipher_set_iv is called it
197 * will reset the feedback for a new block (discarding any remaining
198 * bits from previous stream).
200 * SILC_CIPHER_MODE_OFB
202 * The Output Feedback mode.
204 * SILC_CIPHER_MODE_ECB
206 * The Electronic Codebook mode. This mode does not provide sufficient
207 * security and should not be used alone.
209 * Each mode using and IV (initialization vector) modifies the IV of the
210 * cipher when silc_cipher_encrypt or silc_cipher_decrypt is called. The
211 * IV may be set/reset by calling silc_cipher_set_iv and the current IV
212 * can be retrieved by calling silc_cipher_get_iv.
217 SILC_CIPHER_MODE_ECB = 1, /* ECB mode */
218 SILC_CIPHER_MODE_CBC = 2, /* CBC mode */
219 SILC_CIPHER_MODE_CTR = 3, /* CTR mode */
220 SILC_CIPHER_MODE_CFB = 4, /* CFB mode */
221 SILC_CIPHER_MODE_OFB = 5, /* OFB mode */
225 #define SILC_CIPHER_MAX_IV_SIZE 16 /* Maximum IV size */
227 /* Marks for all ciphers in silc. This can be used in silc_cipher_unregister
228 to unregister all ciphers at once. */
229 #define SILC_ALL_CIPHERS ((SilcCipherObject *)1)
231 #include "silccipher_i.h"
233 /* Static list of ciphers for silc_cipher_register_default(). */
234 extern DLLAPI const SilcCipherObject silc_default_ciphers[];
238 /****f* silccrypt/silc_cipher_register
242 * SilcBool silc_cipher_register(const SilcCipherObject *cipher);
246 * Register a new cipher into SILC. This can be used at the initialization
247 * of an applicatio. Usually this function is not needed. The default
248 * ciphers are automatically registered. This can be used to change the
249 * order of the registered ciphers by re-registering them in desired order,
250 * or add new ciphers.
253 SilcBool silc_cipher_register(const SilcCipherObject *cipher);
255 /****f* silccrypt/silc_cipher_unregister
259 * SilcBool silc_cipher_unregister(SilcCipherObject *cipher);
263 * Unregister a cipher from the SILC.
266 SilcBool silc_cipher_unregister(SilcCipherObject *cipher);
268 /****f* silccrypt/silc_cipher_register_default
272 * SilcBool silc_cipher_register_default(void);
276 * Function that registers all the default ciphers (all builtin ciphers).
277 * Application need not call this directly. By calling silc_crypto_init
278 * this function is called.
281 SilcBool silc_cipher_register_default(void);
283 /****f* silccrypt/silc_cipher_unregister_all
287 * SilcBool silc_cipher_unregister_all(void);
291 * Unregisters all ciphers. Application need not call this directly.
292 * By calling silc_crypto_init this function is called.
295 SilcBool silc_cipher_unregister_all(void);
297 /****f* silccrypt/silc_cipher_alloc
301 * SilcBool silc_cipher_alloc(const char *name,
302 * SilcCipher *new_cipher);
306 * Allocates a new SILC cipher object. Function returns TRUE on succes
307 * and FALSE on error. The allocated cipher is returned in new_cipher
308 * argument. The caller must set the key to the cipher after this
309 * function has returned by calling the silc_cipher_set_key.
311 * See Ciphers for supported ciphers.
314 SilcBool silc_cipher_alloc(const char *name, SilcCipher *new_cipher);
316 /****f* silccrypt/silc_cipher_alloc_full
320 * SilcBool silc_cipher_alloc_full(const char *alg_name,
321 * SilcUInt32 key_len,
322 * SilcCipherMode mode,
323 * SilcCipher *new_cipher);
326 * Same as silc_cipher_alloc but takes the cipher algorithm name,
327 * key length and mode as separate arguments.
329 * See Cipher-Algorithms for supported algorithms.
332 SilcBool silc_cipher_alloc_full(const char *alg_name, SilcUInt32 key_len,
333 SilcCipherMode mode, SilcCipher *new_cipher);
335 /****f* silccrypt/silc_cipher_free
339 * void silc_cipher_free(SilcCipher cipher);
343 * Frees the given cipher.
346 void silc_cipher_free(SilcCipher cipher);
348 /****f* silccrypt/silc_cipher_is_supported
352 * SilcBool silc_cipher_is_supported(const char *name);
356 * Returns TRUE if cipher `name' is supported.
359 SilcBool silc_cipher_is_supported(const char *name);
361 /****f* silccrypt/silc_cipher_get_supported
365 * char *silc_cipher_get_supported(SilcBool only_registered);
369 * Returns comma separated list of supported ciphers. If `only_registered'
370 * is TRUE only ciphers explicitly registered with silc_cipher_register
371 * are returned. If FALSE, then all registered and default builtin
372 * ciphers are returned. However, if there are no registered ciphers
373 * and `only_registered' is TRUE, the builtin ciphers are returned.
376 char *silc_cipher_get_supported(SilcBool only_registered);
378 /****f* silccrypt/silc_cipher_encrypt
382 * SilcBool silc_cipher_encrypt(SilcCipher cipher,
383 * const unsigned char *src,
384 * unsigned char *dst, SilcUInt32 len,
385 * unsigned char *iv);
389 * Encrypts data from `src' into `dst' with the specified cipher and
390 * Initial Vector (IV). If the `iv' is NULL then the cipher's internal
391 * IV is used. The `src' and `dst' maybe same buffer.
394 SilcBool silc_cipher_encrypt(SilcCipher cipher, const unsigned char *src,
395 unsigned char *dst, SilcUInt32 len,
398 /****f* silccrypt/silc_cipher_decrypt
402 * SilcBool silc_cipher_decrypt(SilcCipher cipher,
403 * const unsigned char *src,
404 * unsigned char *dst, SilcUInt32 len,
405 * unsigned char *iv);
409 * Decrypts data from `src' into `dst' with the specified cipher and
410 * Initial Vector (IV). If the `iv' is NULL then the cipher's internal
411 * IV is used. The `src' and `dst' maybe same buffer.
414 SilcBool silc_cipher_decrypt(SilcCipher cipher, const unsigned char *src,
415 unsigned char *dst, SilcUInt32 len,
418 /****f* silccrypt/silc_cipher_set_key
422 * SilcBool silc_cipher_set_key(SilcCipher cipher, const unsigned char *key,
423 * SilcUInt32 bit_keylen, SilcBool encryption);
427 * Sets the key for the cipher. The `keylen' is the key length in
428 * bits. If the `encryption' is TRUE the key is for encryption, if FALSE
429 * the key is for decryption.
432 SilcBool silc_cipher_set_key(SilcCipher cipher, const unsigned char *key,
433 SilcUInt32 bit_keylen, SilcBool encryption);
435 /****f* silccrypt/silc_cipher_set_iv
439 * void silc_cipher_set_iv(SilcCipher cipher, const unsigned char *iv);
443 * Sets the IV (initialization vector) for the cipher. The `iv' must be
444 * the size of the block size of the cipher. If `iv' is NULL this
445 * does not do anything.
447 * If the encryption mode is CTR (Counter mode) this also resets the
448 * the counter for a new block. This is done also if `iv' is NULL.
450 * If the encryption mode is CFB (cipher feedback) this also resets the
451 * the feedback stream for a new block. This is done also if `iv' is NULL.
454 void silc_cipher_set_iv(SilcCipher cipher, const unsigned char *iv);
456 /****f* silccrypt/silc_cipher_get_iv
460 * unsigned char *silc_cipher_get_iv(SilcCipher cipher);
464 * Returns the IV (initial vector) of the cipher. The returned
465 * pointer must not be freed by the caller. If the caller modifies
466 * the returned pointer the IV inside cipher is also modified.
469 unsigned char *silc_cipher_get_iv(SilcCipher cipher);
471 /****f* silccrypt/silc_cipher_get_key_len
475 * SilcUInt32 silc_cipher_get_key_len(SilcCipher cipher);
479 * Returns the key length of the cipher in bits.
482 SilcUInt32 silc_cipher_get_key_len(SilcCipher cipher);
484 /****f* silccrypt/silc_cipher_get_block_len
488 * SilcUInt32 silc_cipher_get_block_len(SilcCipher cipher);
492 * Returns the block size of the cipher in bytes.
495 SilcUInt32 silc_cipher_get_block_len(SilcCipher cipher);
497 /****f* silccrypt/silc_cipher_get_iv_len
501 * SilcUInt32 silc_cipher_get_iv_len(SilcCipher cipher);
505 * Returns the IV length of the cipher in bytes.
508 SilcUInt32 silc_cipher_get_iv_len(SilcCipher cipher);
510 /****f* silccrypt/silc_cipher_get_name
514 * const char *silc_cipher_get_name(SilcCipher cipher);
518 * Returns the full name of the cipher (eg. 'aes-256-ctr').
521 const char *silc_cipher_get_name(SilcCipher cipher);
523 /****f* silccrypt/silc_cipher_get_alg_name
527 * const char *silc_cipher_get_alg_name(SilcCipher cipher);
531 * Returns the algorithm name of the cipher (eg. 'aes').
534 const char *silc_cipher_get_alg_name(SilcCipher cipher);
536 /****f* silccrypt/silc_cipher_get_mode
540 * SilcCipherMode silc_cipher_get_mode(SilcCipher cipher);
544 * Returns the cipher mode.
547 SilcCipherMode silc_cipher_get_mode(SilcCipher cipher);
549 #endif /* SILCCIPHER_H */