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/SILC Cipher Interface
24 * This is the interface for cipher functions. It provides cipher
25 * registering and unregistering routines, encryption and decryption
33 /* Forward declarations */
34 typedef struct SilcCipherObjectStruct SilcCipherObject;
36 /****s* silccrypt/SilcCipherAPI/SilcCipher
40 * typedef struct SilcCipherStruct *SilcCipher;
44 * This context is the actual cipher context and is allocated
45 * by silc_cipher_alloc and given as argument usually to all
46 * silc_cipher _* functions. It is freed by the silc_cipher_free
50 typedef struct SilcCipherStruct *SilcCipher;
52 /****d* silccrypt/SilcCipherAPI/SilcCipherMode
56 * typedef enum { ... } SilcCipherMode;
60 * Cipher modes. Notes about cipher modes and implementation:
62 * SILC_CIPHER_MODE_CBC
64 * The Cipher-block Chaining mode. The CBC is mode is a standard CBC
65 * mode. The plaintext length must be multiple by the cipher block size.
66 * If it isn't the plaintext must be padded.
68 * SILC_CIPHER_MODE_CTR
70 * The Counter mode. The CTR is normal counter mode. The CTR mode does
71 * not require the plaintext length to be multiple by the cipher block
72 * size. If the last plaintext block is shorter the remaining bits of
73 * the key stream are used next time silc_cipher_encrypt is called. If
74 * silc_cipher_set_iv is called it will reset the counter for a new block
75 * (discarding any remaining bits from previous key stream). The counter
76 * mode expects MSB first ordered counter. Note also, the counter is
77 * incremented when silc_cipher_encrypt is called for the first time,
80 * SILC_CIPHER_MODE_CFB
82 * The Cipher Feedback mode. The CFB mode is normal cipher feedback mode.
83 * The CFB mode does not require the plaintext length to be multiple by
84 * the cipher block size. If the last plaintext block is shorter the
85 * remaining bits of the stream are used next time silc_cipher_encrypt is
86 * called. If silc_cipher_set_iv is called it will reset the feedback
87 * for a new block (discarding any remaining bits from previous stream).
89 * SILC_CIPHER_MODE_OFB
91 * The Output Feedback mode.
93 * SILC_CIPHER_MODE_ECB
95 * The Electronic Codebook mode. This mode does not provide sufficient
96 * security and should not be used.
98 * Each mode modifies the IV (initialization vector) of the cipher when
99 * silc_cipher_encrypt or silc_cipher_decrypt is called. The IV may be
100 * set/reset by calling silc_cipher_set_iv and the current IV can be
101 * retrieved by calling silc_cipher_get_iv.
106 SILC_CIPHER_MODE_ECB = 1, /* ECB mode */
107 SILC_CIPHER_MODE_CBC = 2, /* CBC mode */
108 SILC_CIPHER_MODE_CTR = 3, /* CTR mode */
109 SILC_CIPHER_MODE_CFB = 4, /* CFB mode */
110 SILC_CIPHER_MODE_OFB = 5, /* OFB mode */
114 #define SILC_CIPHER_MAX_IV_SIZE 16 /* Maximum IV size */
115 #define SILC_DEFAULT_CIPHER "aes-256-cbc" /* Default cipher */
117 /* Marks for all ciphers in silc. This can be used in silc_cipher_unregister
118 to unregister all ciphers at once. */
119 #define SILC_ALL_CIPHERS ((SilcCipherObject *)1)
121 #include "silccipher_i.h"
123 /* Static list of ciphers for silc_cipher_register_default(). */
124 extern DLLAPI const SilcCipherObject silc_default_ciphers[];
128 /****f* silccrypt/SilcCipherAPI/silc_cipher_register
132 * SilcBool silc_cipher_register(const SilcCipherObject *cipher);
136 * Register a new cipher into SILC. This is used at the initialization of
137 * the SILC. This function allocates a new object for the cipher to be
138 * registered. Therefore, if memory has been allocated for the object sent
139 * as argument it has to be free'd after this function returns succesfully.
142 SilcBool silc_cipher_register(const SilcCipherObject *cipher);
144 /****f* silccrypt/SilcCipherAPI/silc_cipher_unregister
148 * SilcBool silc_cipher_unregister(SilcCipherObject *cipher);
152 * Unregister a cipher from the SILC.
155 SilcBool silc_cipher_unregister(SilcCipherObject *cipher);
157 /****f* silccrypt/SilcCipherAPI/silc_cipher_register_default
161 * SilcBool silc_cipher_register_default(void);
165 * Function that registers all the default ciphers (all builtin ciphers).
166 * The application may use this to register the default ciphers if specific
167 * ciphers in any specific order is not wanted.
170 SilcBool silc_cipher_register_default(void);
172 /****f* silccrypt/SilcCipherAPI/silc_cipher_unregister_all
176 * SilcBool silc_cipher_unregister_all(void);
180 * Unregisters all ciphers.
183 SilcBool silc_cipher_unregister_all(void);
185 /****f* silccrypt/SilcCipherAPI/silc_cipher_alloc
189 * SilcBool silc_cipher_alloc(const char *name,
190 * SilcCipher *new_cipher);
194 * Allocates a new SILC cipher object. Function returns TRUE on succes
195 * and FALSE on error. The allocated cipher is returned in new_cipher
196 * argument. The caller must set the key to the cipher after this
197 * function has returned by calling the silc_cipher_set_key.
199 * The following ciphers are supported:
201 * aes-256-ctr AES-256, Counter mode
202 * aes-192-ctr AES-192, Counter mode
203 * aes-128-ctr AES,128, Counter mode
204 * aes-256-cbc AES-256, Cipher block chaining mode
205 * aes-192-cbc AES-192, Cipher block chaining mode
206 * aes-128-cbc AES,128, Cipher block chaining mode
207 * twofish-256-cbc Twofish-256, Cipher block chaining mode
208 * twofish-192-cbc Twofish-192, Cipher block chaining mode
209 * twofish-128-cbc Twofish-128, Cipher block chaining mode
214 SilcBool silc_cipher_alloc(const char *name, SilcCipher *new_cipher);
216 /****f* silccrypt/SilcCipherAPI/silc_cipher_alloc
220 * SilcBool silc_cipher_alloc_full(const char *alg_name,
221 * SilcUInt32 key_len,
222 * SilcCipherMode mode,
223 * SilcCipher *new_cipher);
226 * Same as silc_cipher_alloc but takes the cipher algorithm name,
227 * key length and mode as separate arguments.
230 SilcBool silc_cipher_alloc_full(const char *alg_name, SilcUInt32 key_len,
231 SilcCipherMode mode, SilcCipher *new_cipher);
233 /****f* silccrypt/SilcCipherAPI/silc_cipher_free
237 * void silc_cipher_free(SilcCipher cipher);
241 * Frees the given cipher.
244 void silc_cipher_free(SilcCipher cipher);
246 /****f* silccrypt/SilcCipherAPI/silc_cipher_is_supported
250 * SilcBool silc_cipher_is_supported(const char *name);
254 * Returns TRUE if cipher `name' is supported.
257 SilcBool silc_cipher_is_supported(const char *name);
259 /****f* silccrypt/SilcCipherAPI/silc_cipher_get_supported
263 * char *silc_cipher_get_supported(SilcBool only_registered);
267 * Returns comma separated list of supported ciphers. If `only_registered'
268 * is TRUE only ciphers explicitly registered with silc_cipher_register
269 * are returned. If FALSE, then all registered and default builtin
270 * ciphers are returned. However, if there are no registered ciphers
271 * and `only_registered' is TRUE, the builtin ciphers are returned.
274 char *silc_cipher_get_supported(SilcBool only_registered);
276 /****f* silccrypt/SilcCipherAPI/silc_cipher_encrypt
280 * SilcBool silc_cipher_encrypt(SilcCipher cipher,
281 * const unsigned char *src,
282 * unsigned char *dst, SilcUInt32 len,
283 * unsigned char *iv);
287 * Encrypts data from `src' into `dst' with the specified cipher and
288 * Initial Vector (IV). If the `iv' is NULL then the cipher's internal
289 * IV is used. The `src' and `dst' maybe same buffer.
292 SilcBool silc_cipher_encrypt(SilcCipher cipher, const unsigned char *src,
293 unsigned char *dst, SilcUInt32 len,
296 /****f* silccrypt/SilcCipherAPI/silc_cipher_decrypt
300 * SilcBool silc_cipher_decrypt(SilcCipher cipher,
301 * const unsigned char *src,
302 * unsigned char *dst, SilcUInt32 len,
303 * unsigned char *iv);
307 * Decrypts data from `src' into `dst' with the specified cipher and
308 * Initial Vector (IV). If the `iv' is NULL then the cipher's internal
309 * IV is used. The `src' and `dst' maybe same buffer.
312 SilcBool silc_cipher_decrypt(SilcCipher cipher, const unsigned char *src,
313 unsigned char *dst, SilcUInt32 len,
316 /****f* silccrypt/SilcCipherAPI/silc_cipher_set_key
320 * SilcBool silc_cipher_set_key(SilcCipher cipher, const unsigned char *key,
321 * SilcUInt32 bit_keylen, SilcBool encryption);
325 * Sets the key for the cipher. The `keylen' is the key length in
326 * bits. If the `encryption' is TRUE the key is for encryption, if FALSE
327 * the key is for decryption.
330 SilcBool silc_cipher_set_key(SilcCipher cipher, const unsigned char *key,
331 SilcUInt32 bit_keylen, SilcBool encryption);
333 /****f* silccrypt/SilcCipherAPI/silc_cipher_set_iv
337 * void silc_cipher_set_iv(SilcCipher cipher, const unsigned char *iv);
341 * Sets the IV (initialization vector) for the cipher. The `iv' must be
342 * the size of the block size of the cipher. If `iv' is NULL this
343 * does not do anything.
345 * If the encryption mode is CTR (Counter mode) this also resets the
346 * the counter for a new block. This is done also if `iv' is NULL.
348 * If the encryption mode is CFB (cipher feedback) this also resets the
349 * the feedback stream for a new block. This is done also if `iv' is NULL.
352 void silc_cipher_set_iv(SilcCipher cipher, const unsigned char *iv);
354 /****f* silccrypt/SilcCipherAPI/silc_cipher_get_iv
358 * unsigned char *silc_cipher_get_iv(SilcCipher cipher);
362 * Returns the IV (initial vector) of the cipher. The returned
363 * pointer must not be freed by the caller. If the caller modifies
364 * the returned pointer the IV inside cipher is also modified.
367 unsigned char *silc_cipher_get_iv(SilcCipher cipher);
369 /****f* silccrypt/SilcCipherAPI/silc_cipher_get_key_len
373 * SilcUInt32 silc_cipher_get_key_len(SilcCipher cipher);
377 * Returns the key length of the cipher in bits.
380 SilcUInt32 silc_cipher_get_key_len(SilcCipher cipher);
382 /****f* silccrypt/SilcCipherAPI/silc_cipher_get_block_len
386 * SilcUInt32 silc_cipher_get_block_len(SilcCipher cipher);
390 * Returns the block size of the cipher in bytes.
393 SilcUInt32 silc_cipher_get_block_len(SilcCipher cipher);
395 /****f* silccrypt/SilcCipherAPI/silc_cipher_get_iv_len
399 * SilcUInt32 silc_cipher_get_iv_len(SilcCipher cipher);
403 * Returns the IV length of the cipher in bytes.
406 SilcUInt32 silc_cipher_get_iv_len(SilcCipher cipher);
408 /****f* silccrypt/SilcCipherAPI/silc_cipher_get_name
412 * const char *silc_cipher_get_name(SilcCipher cipher);
416 * Returns the full name of the cipher (eg. 'aes-256-ctr').
419 const char *silc_cipher_get_name(SilcCipher cipher);
421 /****f* silccrypt/SilcCipherAPI/silc_cipher_get_alg_name
425 * const char *silc_cipher_get_alg_name(SilcCipher cipher);
429 * Returns the algorithm name of the cipher (eg. 'aes').
432 const char *silc_cipher_get_alg_name(SilcCipher cipher);
434 /****f* silccrypt/SilcCipherAPI/silc_cipher_get_mode
438 * SilcCipherMode silc_cipher_get_mode(SilcCipher cipher);
442 * Returns the cipher mode.
445 SilcCipherMode silc_cipher_get_mode(SilcCipher cipher);
447 #endif /* SILCCIPHER_H */