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;
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.
101 SILC_CIPHER_MODE_ECB = 1, /* ECB mode */
102 SILC_CIPHER_MODE_CBC = 2, /* CBC mode */
103 SILC_CIPHER_MODE_CTR = 3, /* CTR mode */
104 SILC_CIPHER_MODE_CFB = 4, /* CFB mode */
105 SILC_CIPHER_MODE_OFB = 5, /* OFB mode */
109 #define SILC_CIPHER_MAX_IV_SIZE 16 /* Maximum IV size */
110 #define SILC_DEFAULT_CIPHER "aes-256-cbc" /* Default cipher */
112 /* Marks for all ciphers in silc. This can be used in silc_cipher_unregister
113 to unregister all ciphers at once. */
114 #define SILC_ALL_CIPHERS ((SilcCipherObject *)1)
116 #include "silccipher_i.h"
118 /* Static list of ciphers for silc_cipher_register_default(). */
119 extern DLLAPI const SilcCipherObject silc_default_ciphers[];
123 /****f* silccrypt/SilcCipherAPI/silc_cipher_register
127 * SilcBool silc_cipher_register(const SilcCipherObject *cipher);
131 * Register a new cipher into SILC. This is used at the initialization of
132 * the SILC. This function allocates a new object for the cipher to be
133 * registered. Therefore, if memory has been allocated for the object sent
134 * as argument it has to be free'd after this function returns succesfully.
137 SilcBool silc_cipher_register(const SilcCipherObject *cipher);
139 /****f* silccrypt/SilcCipherAPI/silc_cipher_unregister
143 * SilcBool silc_cipher_unregister(SilcCipherObject *cipher);
147 * Unregister a cipher from the SILC.
150 SilcBool silc_cipher_unregister(SilcCipherObject *cipher);
152 /****f* silccrypt/SilcCipherAPI/silc_cipher_register_default
156 * SilcBool silc_cipher_register_default(void);
160 * Function that registers all the default ciphers (all builtin ciphers).
161 * The application may use this to register the default ciphers if specific
162 * ciphers in any specific order is not wanted.
165 SilcBool silc_cipher_register_default(void);
167 /****f* silccrypt/SilcCipherAPI/silc_cipher_unregister_all
171 * SilcBool silc_cipher_unregister_all(void);
175 * Unregisters all ciphers.
178 SilcBool silc_cipher_unregister_all(void);
180 /****f* silccrypt/SilcCipherAPI/silc_cipher_alloc
184 * SilcBool silc_cipher_alloc(const unsigned char *name,
185 * SilcCipher *new_cipher);
189 * Allocates a new SILC cipher object. Function returns 1 on succes and 0
190 * on error. The allocated cipher is returned in new_cipher argument. The
191 * caller must set the key to the cipher after this function has returned
192 * by calling the ciphers set_key function.
194 * The following ciphers are supported:
196 * aes-256-ctr AES-256, Counter mode
197 * aes-192-ctr AES-192, Counter mode
198 * aes-128-ctr AES,128, Counter mode
199 * aes-256-cbc AES-256, Cipher block chaining mode
200 * aes-192-cbc AES-192, Cipher block chaining mode
201 * aes-128-cbc AES,128, Cipher block chaining mode
202 * twofish-256-cbc Twofish-256, Cipher block chaining mode
203 * twofish-192-cbc Twofish-192, Cipher block chaining mode
204 * twofish-128-cbc Twofish-128, Cipher block chaining mode
209 SilcBool silc_cipher_alloc(const unsigned char *name, SilcCipher *new_cipher);
211 /****f* silccrypt/SilcCipherAPI/silc_cipher_free
215 * void silc_cipher_free(SilcCipher cipher);
219 * Frees the given cipher.
222 void silc_cipher_free(SilcCipher cipher);
224 /****f* silccrypt/SilcCipherAPI/silc_cipher_is_supported
228 * SilcBool silc_cipher_is_supported(const unsigned char *name);
232 * Returns TRUE if cipher `name' is supported.
235 SilcBool silc_cipher_is_supported(const unsigned char *name);
237 /****f* silccrypt/SilcCipherAPI/silc_cipher_get_supported
241 * char *silc_cipher_get_supported(SilcBool only_registered);
245 * Returns comma separated list of supported ciphers. If `only_registered'
246 * is TRUE only ciphers explicitly registered with silc_cipher_register
247 * are returned. If FALSE, then all registered and default builtin
248 * ciphers are returned. However, if there are no registered ciphers
249 * and `only_registered' is TRUE, the builtin ciphers are returned.
252 char *silc_cipher_get_supported(SilcBool only_registered);
254 /****f* silccrypt/SilcCipherAPI/silc_cipher_encrypt
258 * SilcBool silc_cipher_encrypt(SilcCipher cipher,
259 * const unsigned char *src,
260 * unsigned char *dst, SilcUInt32 len,
261 * unsigned char *iv);
265 * Encrypts data from `src' into `dst' with the specified cipher and
266 * Initial Vector (IV). If the `iv' is NULL then the cipher's internal
267 * IV is used. The `src' and `dst' maybe same buffer.
270 SilcBool silc_cipher_encrypt(SilcCipher cipher, const unsigned char *src,
271 unsigned char *dst, SilcUInt32 len,
274 /****f* silccrypt/SilcCipherAPI/silc_cipher_decrypt
278 * SilcBool silc_cipher_decrypt(SilcCipher cipher,
279 * const unsigned char *src,
280 * unsigned char *dst, SilcUInt32 len,
281 * unsigned char *iv);
285 * Decrypts data from `src' into `dst' with the specified cipher and
286 * Initial Vector (IV). If the `iv' is NULL then the cipher's internal
287 * IV is used. The `src' and `dst' maybe same buffer.
290 SilcBool silc_cipher_decrypt(SilcCipher cipher, const unsigned char *src,
291 unsigned char *dst, SilcUInt32 len,
294 /****f* silccrypt/SilcCipherAPI/silc_cipher_set_key
298 * SilcBool silc_cipher_set_key(SilcCipher cipher, const unsigned char *key,
299 * SilcUInt32 keylen, SilcBool encryption);
303 * Sets the key for the cipher. The `keylen' is the key length in
304 * bits. If the `encryption' is TRUE the key is for encryption, if FALSE
305 * the key is for decryption.
308 SilcBool silc_cipher_set_key(SilcCipher cipher, const unsigned char *key,
309 SilcUInt32 keylen, SilcBool encryption);
311 /****f* silccrypt/SilcCipherAPI/silc_cipher_set_iv
315 * void silc_cipher_set_iv(SilcCipher cipher, const unsigned char *iv);
319 * Sets the IV (initial vector) for the cipher. The `iv' must be
320 * the size of the block size of the cipher. If `iv' is NULL this
321 * does not do anything.
323 * If the encryption mode is CTR (Counter mode) this also resets the
324 * the counter for a new block. This is done also if `iv' is NULL.
327 void silc_cipher_set_iv(SilcCipher cipher, const unsigned char *iv);
329 /****f* silccrypt/SilcCipherAPI/silc_cipher_get_iv
333 * unsigned char *silc_cipher_get_iv(SilcCipher cipher);
337 * Returns the IV (initial vector) of the cipher. The returned
338 * pointer must not be freed by the caller. If the caller modifies
339 * the returned pointer the IV inside cipher is also modified.
342 unsigned char *silc_cipher_get_iv(SilcCipher cipher);
344 /****f* silccrypt/SilcCipherAPI/silc_cipher_get_key_len
348 * SilcUInt32 silc_cipher_get_key_len(SilcCipher cipher);
352 * Returns the key length of the cipher in bits.
355 SilcUInt32 silc_cipher_get_key_len(SilcCipher cipher);
357 /****f* silccrypt/SilcCipherAPI/silc_cipher_get_block_len
361 * SilcUInt32 silc_cipher_get_block_len(SilcCipher cipher);
365 * Returns the block size of the cipher in bytes.
368 SilcUInt32 silc_cipher_get_block_len(SilcCipher cipher);
370 /****f* silccrypt/SilcCipherAPI/silc_cipher_get_iv_len
374 * SilcUInt32 silc_cipher_get_iv_len(SilcCipher cipher);
378 * Returns the IV length of the cipher in bytes.
381 SilcUInt32 silc_cipher_get_iv_len(SilcCipher cipher);
383 /****f* silccrypt/SilcCipherAPI/silc_cipher_get_name
387 * const char *silc_cipher_get_name(SilcCipher cipher);
391 * Returns the name of the cipher.
394 const char *silc_cipher_get_name(SilcCipher cipher);
396 /****f* silccrypt/SilcCipherAPI/silc_cipher_get_mode
400 * SilcCipherMode silc_cipher_get_mode(SilcCipher cipher);
404 * Returns the cipher mode.
407 SilcCipherMode silc_cipher_get_mode(SilcCipher cipher);
409 #endif /* SILCCIPHER_H */