5 Author: Pekka Riikonen <priikone@silcnet.org>
7 Copyright (C) 1997 - 2007 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;
65 SILC_CIPHER_MODE_ECB = 1, /* ECB mode */
66 SILC_CIPHER_MODE_CBC = 2, /* CBC mode */
67 SILC_CIPHER_MODE_CTR = 3, /* CTR mode */
68 SILC_CIPHER_MODE_CFB = 4, /* CFB mode */
69 SILC_CIPHER_MODE_OFB = 5, /* OFB mode */
73 #define SILC_CIPHER_MAX_IV_SIZE 16 /* Maximum IV size */
74 #define SILC_DEFAULT_CIPHER "aes-256-cbc" /* Default cipher */
76 /* Marks for all ciphers in silc. This can be used in silc_cipher_unregister
77 to unregister all ciphers at once. */
78 #define SILC_ALL_CIPHERS ((SilcCipherObject *)1)
80 #include "silccipher_i.h"
82 /* Static list of ciphers for silc_cipher_register_default(). */
83 extern DLLAPI const SilcCipherObject silc_default_ciphers[];
87 /****f* silccrypt/SilcCipherAPI/silc_cipher_register
91 * SilcBool silc_cipher_register(const SilcCipherObject *cipher);
95 * Register a new cipher into SILC. This is used at the initialization of
96 * the SILC. This function allocates a new object for the cipher to be
97 * registered. Therefore, if memory has been allocated for the object sent
98 * as argument it has to be free'd after this function returns succesfully.
101 SilcBool silc_cipher_register(const SilcCipherObject *cipher);
103 /****f* silccrypt/SilcCipherAPI/silc_cipher_unregister
107 * SilcBool silc_cipher_unregister(SilcCipherObject *cipher);
111 * Unregister a cipher from the SILC.
114 SilcBool silc_cipher_unregister(SilcCipherObject *cipher);
116 /****f* silccrypt/SilcCipherAPI/silc_cipher_register_default
120 * SilcBool silc_cipher_register_default(void);
124 * Function that registers all the default ciphers (all builtin ciphers).
125 * The application may use this to register the default ciphers if specific
126 * ciphers in any specific order is not wanted.
129 SilcBool silc_cipher_register_default(void);
131 /****f* silccrypt/SilcCipherAPI/silc_cipher_unregister_all
135 * SilcBool silc_cipher_unregister_all(void);
139 * Unregisters all ciphers.
142 SilcBool silc_cipher_unregister_all(void);
144 /****f* silccrypt/SilcCipherAPI/silc_cipher_alloc
148 * SilcBool silc_cipher_alloc(const unsigned char *name,
149 * SilcCipher *new_cipher);
153 * Allocates a new SILC cipher object. Function returns 1 on succes and 0
154 * on error. The allocated cipher is returned in new_cipher argument. The
155 * caller must set the key to the cipher after this function has returned
156 * by calling the ciphers set_key function.
158 * The following ciphers are supported:
160 * aes-256-ctr AES-256, Counter mode
161 * aes-192-ctr AES-192, Counter mode
162 * aes-128-ctr AES,128, Counter mode
163 * aes-256-cbc AES-256, Cipher block chaining mode
164 * aes-192-cbc AES-192, Cipher block chaining mode
165 * aes-128-cbc AES,128, Cipher block chaining mode
166 * twofish-256-cbc Twofish-256, Cipher block chaining mode
167 * twofish-192-cbc Twofish-192, Cipher block chaining mode
168 * twofish-128-cbc Twofish-128, Cipher block chaining mode
172 * The CTR is normal counter mode. The CTR mode does not require the
173 * plaintext length to be multiple by the cipher block size. If the last
174 * plaintext block is shorter the remaining bits of the key stream are
175 * used next time silc_cipher_encrypt is called. If silc_cipher_set_iv
176 * is called it will reset the counter for a new block (discarding any
177 * remaining bits from previous key stream). The counter mode expects
178 * MSB first ordered counter. Note also, the counter is incremented when
179 * silc_cipher_encrypt is called for the first time, before encrypting.
181 * The CBC is mode is a standard CBC mode. The plaintext length must be
182 * multiple by the cipher block size. If it isn't the plaintext must be
186 SilcBool silc_cipher_alloc(const unsigned char *name, SilcCipher *new_cipher);
188 /****f* silccrypt/SilcCipherAPI/silc_cipher_free
192 * void silc_cipher_free(SilcCipher cipher);
196 * Frees the given cipher.
199 void silc_cipher_free(SilcCipher cipher);
201 /****f* silccrypt/SilcCipherAPI/silc_cipher_is_supported
205 * SilcBool silc_cipher_is_supported(const unsigned char *name);
209 * Returns TRUE if cipher `name' is supported.
212 SilcBool silc_cipher_is_supported(const unsigned char *name);
214 /****f* silccrypt/SilcCipherAPI/silc_cipher_get_supported
218 * char *silc_cipher_get_supported(SilcBool only_registered);
222 * Returns comma separated list of supported ciphers. If `only_registered'
223 * is TRUE only ciphers explicitly registered with silc_cipher_register
224 * are returned. If FALSE, then all registered and default builtin
225 * ciphers are returned. However, if there are no registered ciphers
226 * and `only_registered' is TRUE, the builtin ciphers are returned.
229 char *silc_cipher_get_supported(SilcBool only_registered);
231 /****f* silccrypt/SilcCipherAPI/silc_cipher_encrypt
235 * SilcBool silc_cipher_encrypt(SilcCipher cipher,
236 * const unsigned char *src,
237 * unsigned char *dst, SilcUInt32 len,
238 * unsigned char *iv);
242 * Encrypts data from `src' into `dst' with the specified cipher and
243 * Initial Vector (IV). If the `iv' is NULL then the cipher's internal
244 * IV is used. The `src' and `dst' maybe same buffer.
247 SilcBool silc_cipher_encrypt(SilcCipher cipher, const unsigned char *src,
248 unsigned char *dst, SilcUInt32 len,
251 /****f* silccrypt/SilcCipherAPI/silc_cipher_decrypt
255 * SilcBool silc_cipher_decrypt(SilcCipher cipher,
256 * const unsigned char *src,
257 * unsigned char *dst, SilcUInt32 len,
258 * unsigned char *iv);
262 * Decrypts data from `src' into `dst' with the specified cipher and
263 * Initial Vector (IV). If the `iv' is NULL then the cipher's internal
264 * IV is used. The `src' and `dst' maybe same buffer.
267 SilcBool silc_cipher_decrypt(SilcCipher cipher, const unsigned char *src,
268 unsigned char *dst, SilcUInt32 len,
271 /****f* silccrypt/SilcCipherAPI/silc_cipher_set_key
275 * SilcBool silc_cipher_set_key(SilcCipher cipher, const unsigned char *key,
276 * SilcUInt32 keylen, SilcBool encryption);
280 * Sets the key for the cipher. The `keylen' is the key length in
281 * bits. If the `encryption' is TRUE the key is for encryption, if FALSE
282 * the key is for decryption.
285 SilcBool silc_cipher_set_key(SilcCipher cipher, const unsigned char *key,
286 SilcUInt32 keylen, SilcBool encryption);
288 /****f* silccrypt/SilcCipherAPI/silc_cipher_set_iv
292 * void silc_cipher_set_iv(SilcCipher cipher, const unsigned char *iv);
296 * Sets the IV (initial vector) for the cipher. The `iv' must be
297 * the size of the block size of the cipher. If `iv' is NULL this
298 * does not do anything.
300 * If the encryption mode is CTR (Counter mode) this also resets the
301 * the counter for a new block. This is done also if `iv' is NULL.
304 void silc_cipher_set_iv(SilcCipher cipher, const unsigned char *iv);
306 /****f* silccrypt/SilcCipherAPI/silc_cipher_get_iv
310 * unsigned char *silc_cipher_get_iv(SilcCipher cipher);
314 * Returns the IV (initial vector) of the cipher. The returned
315 * pointer must not be freed by the caller. If the caller modifies
316 * the returned pointer the IV inside cipher is also modified.
319 unsigned char *silc_cipher_get_iv(SilcCipher cipher);
321 /****f* silccrypt/SilcCipherAPI/silc_cipher_get_key_len
325 * SilcUInt32 silc_cipher_get_key_len(SilcCipher cipher);
329 * Returns the key length of the cipher in bits.
332 SilcUInt32 silc_cipher_get_key_len(SilcCipher cipher);
334 /****f* silccrypt/SilcCipherAPI/silc_cipher_get_block_len
338 * SilcUInt32 silc_cipher_get_block_len(SilcCipher cipher);
342 * Returns the block size of the cipher in bytes.
345 SilcUInt32 silc_cipher_get_block_len(SilcCipher cipher);
347 /****f* silccrypt/SilcCipherAPI/silc_cipher_get_iv_len
351 * SilcUInt32 silc_cipher_get_iv_len(SilcCipher cipher);
355 * Returns the IV length of the cipher in bytes.
358 SilcUInt32 silc_cipher_get_iv_len(SilcCipher cipher);
360 /****f* silccrypt/SilcCipherAPI/silc_cipher_get_name
364 * const char *silc_cipher_get_name(SilcCipher cipher);
368 * Returns the name of the cipher.
371 const char *silc_cipher_get_name(SilcCipher cipher);
373 /****f* silccrypt/SilcCipherAPI/silc_cipher_get_mode
377 * SilcCipherMode silc_cipher_get_mode(SilcCipher cipher);
381 * Returns the cipher mode.
384 SilcCipherMode silc_cipher_get_mode(SilcCipher cipher);
386 #endif /* SILCCIPHER_H */