X-Git-Url: http://git.silcnet.org/gitweb/?p=crypto.git;a=blobdiff_plain;f=lib%2Fsilccrypt%2Fsilccipher.h;h=d86de0ebb82becae19e663af2b6b49f58d05637d;hp=e64e3149359fac4f2b20d11bbc4f4d209532cc9f;hb=57af98efbd82c4c89c81850f42b02585fed1a16a;hpb=9cb3b70fbb028d0bc059a3e5af3c4ea532a2b2f5 diff --git a/lib/silccrypt/silccipher.h b/lib/silccrypt/silccipher.h index e64e3149..d86de0eb 100644 --- a/lib/silccrypt/silccipher.h +++ b/lib/silccrypt/silccipher.h @@ -33,7 +33,7 @@ /* Forward declarations */ typedef struct SilcCipherObjectStruct SilcCipherObject; -/****s* silccrypt/SilcCipherAPI/SilcCipher +/****s* silccrypt/SilcCipher * * NAME * @@ -49,7 +49,103 @@ typedef struct SilcCipherObjectStruct SilcCipherObject; ***/ typedef struct SilcCipherStruct *SilcCipher; -/****d* silccrypt/SilcCipherAPI/SilcCipherMode +/****d* silccrypt/Ciphers + * + * NAME + * + * Ciphers + * + * DESCRIPTION + * + * Supported ciphers names. These names can be given as argument + * to silc_cipher_alloc. + * + * SOURCE + */ + +/* AES in CTR mode, in different key lengths */ +#define SILC_CIPHER_AES_256_CTR "aes-256-ctr" +#define SILC_CIPHER_AES_192_CTR "aes-192-ctr" +#define SILC_CIPHER_AES_128_CTR "aes-128-ctr" + +/* AES in CBC mode, in different key lengths */ +#define SILC_CIPHER_AES_256_CBC "aes-256-cbc" +#define SILC_CIPHER_AES_192_CBC "aes-192-cbc" +#define SILC_CIPHER_AES_128_CBC "aes-128-cbc" + +/* AES in CFB mode, in different key lengths */ +#define SILC_CIPHER_AES_256_CFB "aes-256-cfb" +#define SILC_CIPHER_AES_192_CFB "aes-192-cfb" +#define SILC_CIPHER_AES_128_CFB "aes-128-cfb" + +/* AES in ECB mode, in different key lengths */ +#define SILC_CIPHER_AES_256_ECB "aes-256-ecb" +#define SILC_CIPHER_AES_192_ECB "aes-192-ecb" +#define SILC_CIPHER_AES_128_ECB "aes-128-ecb" + +/* Twofish in CTR mode, in different key lengths */ +#define SILC_CIPHER_TWOFISH_256_CTR "twofish-256-ctr" +#define SILC_CIPHER_TWOFISH_192_CTR "twofish-192-ctr" +#define SILC_CIPHER_TWOFISH_128_CTR "twofish-128-ctr" + +/* Twofish in CBC mode, in different key lengths */ +#define SILC_CIPHER_TWOFISH_256_CBC "twofish-256-cbc" +#define SILC_CIPHER_TWOFISH_192_CBC "twofish-192-cbc" +#define SILC_CIPHER_TWOFISH_128_CBC "twofish-128-cbc" + +/* Twofish in CFB mode, in different key lengths */ +#define SILC_CIPHER_TWOFISH_256_CFB "twofish-256-cfb" +#define SILC_CIPHER_TWOFISH_192_CFB "twofish-192-cfb" +#define SILC_CIPHER_TWOFISH_128_CFB "twofish-128-cfb" + +/* Twofish in ECB mode, in different key lengths */ +#define SILC_CIPHER_TWOFISH_256_ECB "twofish-256-ecb" +#define SILC_CIPHER_TWOFISH_192_ECB "twofish-192-ecb" +#define SILC_CIPHER_TWOFISH_128_ECB "twofish-128-ecb" + +/* CAST-128 in CTR, CBC, CFB, ECB modes, 128-bit key length */ +#define SILC_CIPHER_CAST5_128_CTR "cast5-128-ctr" +#define SILC_CIPHER_CAST5_128_CBC "cast5-128-cbc" +#define SILC_CIPHER_CAST5_128_CFB "cast5-128-cfb" +#define SILC_CIPHER_CAST5_128_ECB "cast5-128-ecb" + +/* DES in CTR, CBC, CFB, ECB modes, 56-bit key length */ +#define SILC_CIPHER_DES_56_CTR "des-56-ctr" +#define SILC_CIPHER_DES_56_CBC "des-56-cbc" +#define SILC_CIPHER_DES_56_CFB "des-56-cfb" +#define SILC_CIPHER_DES_56_ECB "des-56-ecb" + +/* 3DES in CTR, CBC, CFB, ECB modes, 168-bit (192-bit) key length */ +#define SILC_CIPHER_3DES_168_CTR "3des-168-ctr" +#define SILC_CIPHER_3DES_168_CBC "3des-168-cbc" +#define SILC_CIPHER_3DES_168_CFB "3des-168-cfb" +#define SILC_CIPHER_3DES_168_ECB "3des-168-ecb" + +/* No encryption */ +#define SILC_CIPHER_NONE "none" +/***/ + +/****d* silccrypt/Cipher Algorithms + * + * NAME + * + * Cipher Algorithms + * + * DESCRIPTION + * + * Supported cipher algorithm names. These names can be give as argument + * to silc_cipher_alloc_full. + * + * SOURCE + */ +#define SILC_CIPHER_AES "aes" /* AES */ +#define SILC_CIPHER_TWOFISH "twofish" /* Twofish */ +#define SILC_CIPHER_CAST5 "cast5" /* CAST-128 */ +#define SILC_CIPHER_DES "des" /* DES */ +#define SILC_CIPHER_3DES "3des" /* Triple-DES */ +/***/ + +/****d* silccrypt/SilcCipherMode * * NAME * @@ -61,30 +157,29 @@ typedef struct SilcCipherStruct *SilcCipher; * * SILC_CIPHER_MODE_CBC * - * The Cipher-block Chaining mode. The CBC is mode is a standard CBC - * mode. The plaintext length must be multiple by the cipher block size. - * If it isn't the plaintext must be padded. + * The Cipher-block Chaining mode. The plaintext length must be + * multiple by the cipher block size. If it isn't the plaintext must + * be padded. * * SILC_CIPHER_MODE_CTR * - * The Counter mode. The CTR is normal counter mode. The CTR mode does - * not require the plaintext length to be multiple by the cipher block - * size. If the last plaintext block is shorter the remaining bits of - * the key stream are used next time silc_cipher_encrypt is called. If - * silc_cipher_set_iv is called it will reset the counter for a new block - * (discarding any remaining bits from previous key stream). The counter - * mode expects MSB first ordered counter. Note also, the counter is - * incremented when silc_cipher_encrypt is called for the first time, - * before encrypting. + * The Counter mode. The CTR mode does not require the plaintext length + * to be multiple by the cipher block size. If the last plaintext block + * is shorter the remaining bits of the key stream are used next time + * silc_cipher_encrypt is called. If silc_cipher_set_iv is called it + * will reset the counter for a new block (discarding any remaining + * bits from previous key stream). The CTR mode expects MSB first + * ordered counter. Note also, the counter is incremented when + * silc_cipher_encrypt is called for the first time, before encrypting. * * SILC_CIPHER_MODE_CFB * - * The Cipher Feedback mode. The CFB mode is normal cipher feedback mode. - * The CFB mode does not require the plaintext length to be multiple by - * the cipher block size. If the last plaintext block is shorter the - * remaining bits of the stream are used next time silc_cipher_encrypt is - * called. If silc_cipher_set_iv is called it will reset the feedback - * for a new block (discarding any remaining bits from previous stream). + * The Cipher Feedback mode. The CFB mode does not require the plaintext + * length to be multiple by the cipher block size. If the last plaintext + * block is shorter the remaining bits of the stream are used next time + * silc_cipher_encrypt is called. If silc_cipher_set_iv is called it + * will reset the feedback for a new block (discarding any remaining + * bits from previous stream). * * SILC_CIPHER_MODE_OFB * @@ -93,12 +188,12 @@ typedef struct SilcCipherStruct *SilcCipher; * SILC_CIPHER_MODE_ECB * * The Electronic Codebook mode. This mode does not provide sufficient - * security and should not be used. + * security and should not be used alone. * - * Each mode modifies the IV (initialization vector) of the cipher when - * silc_cipher_encrypt or silc_cipher_decrypt is called. The IV may be - * set/reset by calling silc_cipher_set_iv and the current IV can be - * retrieved by calling silc_cipher_get_iv. + * Each mode using and IV (initialization vector) modifies the IV of the + * cipher when silc_cipher_encrypt or silc_cipher_decrypt is called. The + * IV may be set/reset by calling silc_cipher_set_iv and the current IV + * can be retrieved by calling silc_cipher_get_iv. * * SOURCE */ @@ -112,7 +207,6 @@ typedef enum { /***/ #define SILC_CIPHER_MAX_IV_SIZE 16 /* Maximum IV size */ -#define SILC_DEFAULT_CIPHER "aes-256-cbc" /* Default cipher */ /* Marks for all ciphers in silc. This can be used in silc_cipher_unregister to unregister all ciphers at once. */ @@ -125,7 +219,7 @@ extern DLLAPI const SilcCipherObject silc_default_ciphers[]; /* Prototypes */ -/****f* silccrypt/SilcCipherAPI/silc_cipher_register +/****f* silccrypt/silc_cipher_register * * SYNOPSIS * @@ -133,15 +227,16 @@ extern DLLAPI const SilcCipherObject silc_default_ciphers[]; * * DESCRIPTION * - * Register a new cipher into SILC. This is used at the initialization of - * the SILC. This function allocates a new object for the cipher to be - * registered. Therefore, if memory has been allocated for the object sent - * as argument it has to be free'd after this function returns succesfully. + * Register a new cipher into SILC. This can be used at the initialization + * of an applicatio. Usually this function is not needed. The default + * ciphers are automatically registered. This can be used to change the + * order of the registered ciphers by re-registering them in desired order, + * or add new ciphers. * ***/ SilcBool silc_cipher_register(const SilcCipherObject *cipher); -/****f* silccrypt/SilcCipherAPI/silc_cipher_unregister +/****f* silccrypt/silc_cipher_unregister * * SYNOPSIS * @@ -154,7 +249,7 @@ SilcBool silc_cipher_register(const SilcCipherObject *cipher); ***/ SilcBool silc_cipher_unregister(SilcCipherObject *cipher); -/****f* silccrypt/SilcCipherAPI/silc_cipher_register_default +/****f* silccrypt/silc_cipher_register_default * * SYNOPSIS * @@ -163,13 +258,13 @@ SilcBool silc_cipher_unregister(SilcCipherObject *cipher); * DESCRIPTION * * Function that registers all the default ciphers (all builtin ciphers). - * The application may use this to register the default ciphers if specific - * ciphers in any specific order is not wanted. + * Application need not call this directly. By calling silc_crypto_init + * this function is called. * ***/ SilcBool silc_cipher_register_default(void); -/****f* silccrypt/SilcCipherAPI/silc_cipher_unregister_all +/****f* silccrypt/silc_cipher_unregister_all * * SYNOPSIS * @@ -177,12 +272,13 @@ SilcBool silc_cipher_register_default(void); * * DESCRIPTION * - * Unregisters all ciphers. + * Unregisters all ciphers. Application need not call this directly. + * By calling silc_crypto_init this function is called. * ***/ SilcBool silc_cipher_unregister_all(void); -/****f* silccrypt/SilcCipherAPI/silc_cipher_alloc +/****f* silccrypt/silc_cipher_alloc * * SYNOPSIS * @@ -191,29 +287,15 @@ SilcBool silc_cipher_unregister_all(void); * * DESCRIPTION * - * Allocates a new SILC cipher object. Function returns TRUE on succes + * Allocates a new SILC cipher object. Function returns TRUE on succes * and FALSE on error. The allocated cipher is returned in new_cipher * argument. The caller must set the key to the cipher after this * function has returned by calling the silc_cipher_set_key. * - * The following ciphers are supported: - * - * aes-256-ctr AES-256, Counter mode - * aes-192-ctr AES-192, Counter mode - * aes-128-ctr AES,128, Counter mode - * aes-256-cbc AES-256, Cipher block chaining mode - * aes-192-cbc AES-192, Cipher block chaining mode - * aes-128-cbc AES,128, Cipher block chaining mode - * twofish-256-cbc Twofish-256, Cipher block chaining mode - * twofish-192-cbc Twofish-192, Cipher block chaining mode - * twofish-128-cbc Twofish-128, Cipher block chaining mode - * - * Notes about modes: - * ***/ SilcBool silc_cipher_alloc(const char *name, SilcCipher *new_cipher); -/****f* silccrypt/SilcCipherAPI/silc_cipher_alloc +/****f* silccrypt/silc_cipher_alloc * * SYNOPSIS * @@ -224,13 +306,13 @@ SilcBool silc_cipher_alloc(const char *name, SilcCipher *new_cipher); * DESCRIPTION * * Same as silc_cipher_alloc but takes the cipher algorithm name, - * key length and mode as separate arguments. + * key length and mode as separate arguments. * ***/ SilcBool silc_cipher_alloc_full(const char *alg_name, SilcUInt32 key_len, SilcCipherMode mode, SilcCipher *new_cipher); -/****f* silccrypt/SilcCipherAPI/silc_cipher_free +/****f* silccrypt/silc_cipher_free * * SYNOPSIS * @@ -243,7 +325,7 @@ SilcBool silc_cipher_alloc_full(const char *alg_name, SilcUInt32 key_len, ***/ void silc_cipher_free(SilcCipher cipher); -/****f* silccrypt/SilcCipherAPI/silc_cipher_is_supported +/****f* silccrypt/silc_cipher_is_supported * * SYNOPSIS * @@ -256,7 +338,7 @@ void silc_cipher_free(SilcCipher cipher); ***/ SilcBool silc_cipher_is_supported(const char *name); -/****f* silccrypt/SilcCipherAPI/silc_cipher_get_supported +/****f* silccrypt/silc_cipher_get_supported * * SYNOPSIS * @@ -273,7 +355,7 @@ SilcBool silc_cipher_is_supported(const char *name); ***/ char *silc_cipher_get_supported(SilcBool only_registered); -/****f* silccrypt/SilcCipherAPI/silc_cipher_encrypt +/****f* silccrypt/silc_cipher_encrypt * * SYNOPSIS * @@ -293,7 +375,7 @@ SilcBool silc_cipher_encrypt(SilcCipher cipher, const unsigned char *src, unsigned char *dst, SilcUInt32 len, unsigned char *iv); -/****f* silccrypt/SilcCipherAPI/silc_cipher_decrypt +/****f* silccrypt/silc_cipher_decrypt * * SYNOPSIS * @@ -313,7 +395,7 @@ SilcBool silc_cipher_decrypt(SilcCipher cipher, const unsigned char *src, unsigned char *dst, SilcUInt32 len, unsigned char *iv); -/****f* silccrypt/SilcCipherAPI/silc_cipher_set_key +/****f* silccrypt/silc_cipher_set_key * * SYNOPSIS * @@ -330,7 +412,7 @@ SilcBool silc_cipher_decrypt(SilcCipher cipher, const unsigned char *src, SilcBool silc_cipher_set_key(SilcCipher cipher, const unsigned char *key, SilcUInt32 bit_keylen, SilcBool encryption); -/****f* silccrypt/SilcCipherAPI/silc_cipher_set_iv +/****f* silccrypt/silc_cipher_set_iv * * SYNOPSIS * @@ -351,7 +433,7 @@ SilcBool silc_cipher_set_key(SilcCipher cipher, const unsigned char *key, ***/ void silc_cipher_set_iv(SilcCipher cipher, const unsigned char *iv); -/****f* silccrypt/SilcCipherAPI/silc_cipher_get_iv +/****f* silccrypt/silc_cipher_get_iv * * SYNOPSIS * @@ -366,7 +448,7 @@ void silc_cipher_set_iv(SilcCipher cipher, const unsigned char *iv); ***/ unsigned char *silc_cipher_get_iv(SilcCipher cipher); -/****f* silccrypt/SilcCipherAPI/silc_cipher_get_key_len +/****f* silccrypt/silc_cipher_get_key_len * * SYNOPSIS * @@ -379,7 +461,7 @@ unsigned char *silc_cipher_get_iv(SilcCipher cipher); ***/ SilcUInt32 silc_cipher_get_key_len(SilcCipher cipher); -/****f* silccrypt/SilcCipherAPI/silc_cipher_get_block_len +/****f* silccrypt/silc_cipher_get_block_len * * SYNOPSIS * @@ -392,7 +474,7 @@ SilcUInt32 silc_cipher_get_key_len(SilcCipher cipher); ***/ SilcUInt32 silc_cipher_get_block_len(SilcCipher cipher); -/****f* silccrypt/SilcCipherAPI/silc_cipher_get_iv_len +/****f* silccrypt/silc_cipher_get_iv_len * * SYNOPSIS * @@ -405,7 +487,7 @@ SilcUInt32 silc_cipher_get_block_len(SilcCipher cipher); ***/ SilcUInt32 silc_cipher_get_iv_len(SilcCipher cipher); -/****f* silccrypt/SilcCipherAPI/silc_cipher_get_name +/****f* silccrypt/silc_cipher_get_name * * SYNOPSIS * @@ -418,7 +500,7 @@ SilcUInt32 silc_cipher_get_iv_len(SilcCipher cipher); ***/ const char *silc_cipher_get_name(SilcCipher cipher); -/****f* silccrypt/SilcCipherAPI/silc_cipher_get_alg_name +/****f* silccrypt/silc_cipher_get_alg_name * * SYNOPSIS * @@ -431,7 +513,7 @@ const char *silc_cipher_get_name(SilcCipher cipher); ***/ const char *silc_cipher_get_alg_name(SilcCipher cipher); -/****f* silccrypt/SilcCipherAPI/silc_cipher_get_mode +/****f* silccrypt/silc_cipher_get_mode * * SYNOPSIS *