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 1 on succes and 0
195 * on error. The allocated cipher is returned in new_cipher argument. The
196 * caller must set the key to the cipher after this function has returned
197 * by calling the ciphers set_key function.
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_free
220 * void silc_cipher_free(SilcCipher cipher);
224 * Frees the given cipher.
227 void silc_cipher_free(SilcCipher cipher);
229 /****f* silccrypt/SilcCipherAPI/silc_cipher_is_supported
233 * SilcBool silc_cipher_is_supported(const char *name);
237 * Returns TRUE if cipher `name' is supported.
240 SilcBool silc_cipher_is_supported(const char *name);
242 /****f* silccrypt/SilcCipherAPI/silc_cipher_get_supported
246 * char *silc_cipher_get_supported(SilcBool only_registered);
250 * Returns comma separated list of supported ciphers. If `only_registered'
251 * is TRUE only ciphers explicitly registered with silc_cipher_register
252 * are returned. If FALSE, then all registered and default builtin
253 * ciphers are returned. However, if there are no registered ciphers
254 * and `only_registered' is TRUE, the builtin ciphers are returned.
257 char *silc_cipher_get_supported(SilcBool only_registered);
259 /****f* silccrypt/SilcCipherAPI/silc_cipher_encrypt
263 * SilcBool silc_cipher_encrypt(SilcCipher cipher,
264 * const unsigned char *src,
265 * unsigned char *dst, SilcUInt32 len,
266 * unsigned char *iv);
270 * Encrypts data from `src' into `dst' with the specified cipher and
271 * Initial Vector (IV). If the `iv' is NULL then the cipher's internal
272 * IV is used. The `src' and `dst' maybe same buffer.
275 SilcBool silc_cipher_encrypt(SilcCipher cipher, const unsigned char *src,
276 unsigned char *dst, SilcUInt32 len,
279 /****f* silccrypt/SilcCipherAPI/silc_cipher_decrypt
283 * SilcBool silc_cipher_decrypt(SilcCipher cipher,
284 * const unsigned char *src,
285 * unsigned char *dst, SilcUInt32 len,
286 * unsigned char *iv);
290 * Decrypts data from `src' into `dst' with the specified cipher and
291 * Initial Vector (IV). If the `iv' is NULL then the cipher's internal
292 * IV is used. The `src' and `dst' maybe same buffer.
295 SilcBool silc_cipher_decrypt(SilcCipher cipher, const unsigned char *src,
296 unsigned char *dst, SilcUInt32 len,
299 /****f* silccrypt/SilcCipherAPI/silc_cipher_set_key
303 * SilcBool silc_cipher_set_key(SilcCipher cipher, const unsigned char *key,
304 * SilcUInt32 bit_keylen, SilcBool encryption);
308 * Sets the key for the cipher. The `keylen' is the key length in
309 * bits. If the `encryption' is TRUE the key is for encryption, if FALSE
310 * the key is for decryption.
313 SilcBool silc_cipher_set_key(SilcCipher cipher, const unsigned char *key,
314 SilcUInt32 bit_keylen, SilcBool encryption);
316 /****f* silccrypt/SilcCipherAPI/silc_cipher_set_iv
320 * void silc_cipher_set_iv(SilcCipher cipher, const unsigned char *iv);
324 * Sets the IV (initialization vector) for the cipher. The `iv' must be
325 * the size of the block size of the cipher. If `iv' is NULL this
326 * does not do anything.
328 * If the encryption mode is CTR (Counter mode) this also resets the
329 * the counter for a new block. This is done also if `iv' is NULL.
331 * If the encryption mode is CFB (cipher feedback) this also resets the
332 * the feedback stream for a new block. This is done also if `iv' is NULL.
335 void silc_cipher_set_iv(SilcCipher cipher, const unsigned char *iv);
337 /****f* silccrypt/SilcCipherAPI/silc_cipher_get_iv
341 * unsigned char *silc_cipher_get_iv(SilcCipher cipher);
345 * Returns the IV (initial vector) of the cipher. The returned
346 * pointer must not be freed by the caller. If the caller modifies
347 * the returned pointer the IV inside cipher is also modified.
350 unsigned char *silc_cipher_get_iv(SilcCipher cipher);
352 /****f* silccrypt/SilcCipherAPI/silc_cipher_get_key_len
356 * SilcUInt32 silc_cipher_get_key_len(SilcCipher cipher);
360 * Returns the key length of the cipher in bits.
363 SilcUInt32 silc_cipher_get_key_len(SilcCipher cipher);
365 /****f* silccrypt/SilcCipherAPI/silc_cipher_get_block_len
369 * SilcUInt32 silc_cipher_get_block_len(SilcCipher cipher);
373 * Returns the block size of the cipher in bytes.
376 SilcUInt32 silc_cipher_get_block_len(SilcCipher cipher);
378 /****f* silccrypt/SilcCipherAPI/silc_cipher_get_iv_len
382 * SilcUInt32 silc_cipher_get_iv_len(SilcCipher cipher);
386 * Returns the IV length of the cipher in bytes.
389 SilcUInt32 silc_cipher_get_iv_len(SilcCipher cipher);
391 /****f* silccrypt/SilcCipherAPI/silc_cipher_get_name
395 * const char *silc_cipher_get_name(SilcCipher cipher);
399 * Returns the name of the cipher.
402 const char *silc_cipher_get_name(SilcCipher cipher);
404 /****f* silccrypt/SilcCipherAPI/silc_cipher_get_mode
408 * SilcCipherMode silc_cipher_get_mode(SilcCipher cipher);
412 * Returns the cipher mode.
415 SilcCipherMode silc_cipher_get_mode(SilcCipher cipher);
417 #endif /* SILCCIPHER_H */