X-Git-Url: http://git.silcnet.org/gitweb/?a=blobdiff_plain;f=lib%2Fsilccrypt%2Fsilccipher.h;h=a0503c899105d6ffa06c1f3c72fde2f8e332a2af;hb=e7b6c157b80152bf9fb9266e6bdd93f9fb0db776;hp=472b0ab8edeea4ffe11b6a53b1d32acf938b3387;hpb=40f8443d8d3a6577336ee66d18e04d9ac4d956bb;p=silc.git diff --git a/lib/silccrypt/silccipher.h b/lib/silccrypt/silccipher.h index 472b0ab8..a0503c89 100644 --- a/lib/silccrypt/silccipher.h +++ b/lib/silccrypt/silccipher.h @@ -4,7 +4,7 @@ Author: Pekka Riikonen - Copyright (C) 1997 - 2005 Pekka Riikonen + Copyright (C) 1997 - 2007 Pekka Riikonen This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by @@ -17,9 +17,6 @@ */ -#ifndef SILCCIPHER_H -#define SILCCIPHER_H - /****h* silccrypt/SILC Cipher Interface * * DESCRIPTION @@ -30,11 +27,17 @@ * ***/ +#ifndef SILCCIPHER_H +#define SILCCIPHER_H + +/* Forward declarations */ +typedef struct SilcCipherObjectStruct SilcCipherObject; + /****s* silccrypt/SilcCipherAPI/SilcCipher * * NAME * - * typedef struct { ... } SilcCipher; + * typedef struct SilcCipherStruct *SilcCipher; * * DESCRIPTION * @@ -46,74 +49,80 @@ ***/ typedef struct SilcCipherStruct *SilcCipher; -/* The default SILC Cipher object to represent any cipher in SILC. */ -typedef struct { - char *name; - SilcUInt32 block_len; - SilcUInt32 key_len; - - SilcBool (*set_key)(void *, const unsigned char *, SilcUInt32); - SilcBool (*set_key_with_string)(void *, const unsigned char *, SilcUInt32); - SilcBool (*encrypt)(void *, const unsigned char *, unsigned char *, - SilcUInt32, unsigned char *); - SilcBool (*decrypt)(void *, const unsigned char *, unsigned char *, - SilcUInt32, unsigned char *); - SilcUInt32 (*context_len)(); -} SilcCipherObject; +/****d* silccrypt/SilcCipherAPI/SilcCipherMode + * + * NAME + * + * typedef enum { ... } SilcCipherMode; + * + * DESCRIPTION + * + * Cipher modes. Notes about cipher modes and implementation: + * + * 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. + * + * 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. + * + * 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). + * + * SILC_CIPHER_MODE_OFB + * + * The Output Feedback mode. + * + * SILC_CIPHER_MODE_ECB + * + * The Electronic Codebook mode. This mode does not provide sufficient + * security and should not be used. + * + * 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. + * + * SOURCE + */ +typedef enum { + SILC_CIPHER_MODE_ECB = 1, /* ECB mode */ + SILC_CIPHER_MODE_CBC = 2, /* CBC mode */ + SILC_CIPHER_MODE_CTR = 3, /* CTR mode */ + SILC_CIPHER_MODE_CFB = 4, /* CFB mode */ + SILC_CIPHER_MODE_OFB = 5, /* OFB mode */ +} SilcCipherMode; +/***/ -#define SILC_CIPHER_MAX_IV_SIZE 16 +#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. */ #define SILC_ALL_CIPHERS ((SilcCipherObject *)1) +#include "silccipher_i.h" + /* Static list of ciphers for silc_cipher_register_default(). */ extern DLLAPI const SilcCipherObject silc_default_ciphers[]; -/* Default cipher in the SILC protocol */ -#define SILC_DEFAULT_CIPHER "aes-256-cbc" - - -/* Macros */ - -/* Function names in SILC Crypto modules. The name of the cipher - is appended into these names and used to the get correct symbol out - of the module. All SILC Crypto API compliant modules must support - these function names (use macros below to assure this). */ -#define SILC_CIPHER_SIM_SET_KEY "set_key" -#define SILC_CIPHER_SIM_SET_KEY_WITH_STRING "set_key_with_string" -#define SILC_CIPHER_SIM_ENCRYPT_CBC "encrypt_cbc" -#define SILC_CIPHER_SIM_DECRYPT_CBC "decrypt_cbc" -#define SILC_CIPHER_SIM_CONTEXT_LEN "context_len" - -/* These macros can be used to implement the SILC Crypto API and to avoid - errors in the API these macros should be used always. */ -#define SILC_CIPHER_API_SET_KEY(cipher) \ -SilcBool silc_##cipher##_set_key(void *context, \ - const unsigned char *key, \ - SilcUInt32 keylen) -#define SILC_CIPHER_API_SET_KEY_WITH_STRING(cipher) \ -SilcBool silc_##cipher##_set_key_with_string(void *context, \ - const unsigned char *string, \ - SilcUInt32 stringlen) -#define SILC_CIPHER_API_ENCRYPT_CBC(cipher) \ -SilcBool silc_##cipher##_encrypt_cbc(void *context, \ - const unsigned char *src, \ - unsigned char *dst, \ - SilcUInt32 len, \ - unsigned char *iv) -#define SILC_CIPHER_API_DECRYPT_CBC(cipher) \ -SilcBool silc_##cipher##_decrypt_cbc(void *context, \ - const unsigned char *src, \ - unsigned char *dst, \ - SilcUInt32 len, \ - unsigned char *iv) - - -#define SILC_CIPHER_API_CONTEXT_LEN(cipher) \ -SilcUInt32 silc_##cipher##_context_len() - - /* Prototypes */ /****f* silccrypt/SilcCipherAPI/silc_cipher_register @@ -177,8 +186,8 @@ SilcBool silc_cipher_unregister_all(void); * * SYNOPSIS * - * SilcBool silc_cipher_alloc(const unsigned char *name, - * SilcCipher *new_cipher); + * SilcBool silc_cipher_alloc(const char *name, + * SilcCipher *new_cipher); * * DESCRIPTION * @@ -187,8 +196,22 @@ SilcBool silc_cipher_unregister_all(void); * caller must set the key to the cipher after this function has returned * by calling the ciphers set_key function. * + * 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 unsigned char *name, SilcCipher *new_cipher); +SilcBool silc_cipher_alloc(const char *name, SilcCipher *new_cipher); /****f* silccrypt/SilcCipherAPI/silc_cipher_free * @@ -207,27 +230,31 @@ void silc_cipher_free(SilcCipher cipher); * * SYNOPSIS * - * SilcBool silc_cipher_is_supported(const unsigned char *name); + * SilcBool silc_cipher_is_supported(const char *name); * * DESCRIPTION * * Returns TRUE if cipher `name' is supported. * ***/ -SilcBool silc_cipher_is_supported(const unsigned char *name); +SilcBool silc_cipher_is_supported(const char *name); /****f* silccrypt/SilcCipherAPI/silc_cipher_get_supported * * SYNOPSIS * - * char *silc_cipher_get_supported(void); + * char *silc_cipher_get_supported(SilcBool only_registered); * * DESCRIPTION * - * Returns comma separated list of supported ciphers. + * Returns comma separated list of supported ciphers. If `only_registered' + * is TRUE only ciphers explicitly registered with silc_cipher_register + * are returned. If FALSE, then all registered and default builtin + * ciphers are returned. However, if there are no registered ciphers + * and `only_registered' is TRUE, the builtin ciphers are returned. * ***/ -char *silc_cipher_get_supported(void); +char *silc_cipher_get_supported(SilcBool only_registered); /****f* silccrypt/SilcCipherAPI/silc_cipher_encrypt * @@ -274,16 +301,17 @@ SilcBool silc_cipher_decrypt(SilcCipher cipher, const unsigned char *src, * SYNOPSIS * * SilcBool silc_cipher_set_key(SilcCipher cipher, const unsigned char *key, - * SilcUInt32 keylen); + * SilcUInt32 keylen, SilcBool encryption); * * DESCRIPTION * * Sets the key for the cipher. The `keylen' is the key length in - * bits. + * bits. If the `encryption' is TRUE the key is for encryption, if FALSE + * the key is for decryption. * ***/ SilcBool silc_cipher_set_key(SilcCipher cipher, const unsigned char *key, - SilcUInt32 keylen); + SilcUInt32 keylen, SilcBool encryption); /****f* silccrypt/SilcCipherAPI/silc_cipher_set_iv * @@ -293,8 +321,15 @@ SilcBool silc_cipher_set_key(SilcCipher cipher, const unsigned char *key, * * DESCRIPTION * - * Sets the IV (initial vector) for the cipher. The `iv' must be - * the size of the block size of the cipher. + * Sets the IV (initialization vector) for the cipher. The `iv' must be + * the size of the block size of the cipher. If `iv' is NULL this + * does not do anything. + * + * If the encryption mode is CTR (Counter mode) this also resets the + * the counter for a new block. This is done also if `iv' is NULL. + * + * If the encryption mode is CFB (cipher feedback) this also resets the + * the feedback stream for a new block. This is done also if `iv' is NULL. * ***/ void silc_cipher_set_iv(SilcCipher cipher, const unsigned char *iv); @@ -308,7 +343,8 @@ void silc_cipher_set_iv(SilcCipher cipher, const unsigned char *iv); * DESCRIPTION * * Returns the IV (initial vector) of the cipher. The returned - * pointer must not be freed by the caller. + * pointer must not be freed by the caller. If the caller modifies + * the returned pointer the IV inside cipher is also modified. * ***/ unsigned char *silc_cipher_get_iv(SilcCipher cipher); @@ -339,6 +375,19 @@ SilcUInt32 silc_cipher_get_key_len(SilcCipher cipher); ***/ SilcUInt32 silc_cipher_get_block_len(SilcCipher cipher); +/****f* silccrypt/SilcCipherAPI/silc_cipher_get_iv_len + * + * SYNOPSIS + * + * SilcUInt32 silc_cipher_get_iv_len(SilcCipher cipher); + * + * DESCRIPTION + * + * Returns the IV length of the cipher in bytes. + * + ***/ +SilcUInt32 silc_cipher_get_iv_len(SilcCipher cipher); + /****f* silccrypt/SilcCipherAPI/silc_cipher_get_name * * SYNOPSIS @@ -352,4 +401,17 @@ SilcUInt32 silc_cipher_get_block_len(SilcCipher cipher); ***/ const char *silc_cipher_get_name(SilcCipher cipher); -#endif +/****f* silccrypt/SilcCipherAPI/silc_cipher_get_mode + * + * SYNOPSIS + * + * SilcCipherMode silc_cipher_get_mode(SilcCipher cipher); + * + * DESCRIPTION + * + * Returns the cipher mode. + * + ***/ +SilcCipherMode silc_cipher_get_mode(SilcCipher cipher); + +#endif /* SILCCIPHER_H */