X-Git-Url: http://git.silcnet.org/gitweb/?a=blobdiff_plain;f=lib%2Fsilccrypt%2Fsilccipher.h;h=e64e3149359fac4f2b20d11bbc4f4d209532cc9f;hb=9f20f0382b6229eca740925a73f96294f6dcedc6;hp=5981ce73caef15718e3e5b3171518998a6fb4e3e;hpb=3ed0f4669135b422c1dd094992ec0fe4cb318bca;p=crypto.git diff --git a/lib/silccrypt/silccipher.h b/lib/silccrypt/silccipher.h index 5981ce73..e64e3149 100644 --- a/lib/silccrypt/silccipher.h +++ b/lib/silccrypt/silccipher.h @@ -4,7 +4,7 @@ Author: Pekka Riikonen - Copyright (C) 1997 - 2007 Pekka Riikonen + Copyright (C) 1997 - 2008 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 @@ -57,7 +57,48 @@ typedef struct SilcCipherStruct *SilcCipher; * * DESCRIPTION * - * Cipher modes. + * 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 */ @@ -145,15 +186,15 @@ SilcBool silc_cipher_unregister_all(void); * * SYNOPSIS * - * SilcBool silc_cipher_alloc(const unsigned char *name, + * SilcBool silc_cipher_alloc(const char *name, * SilcCipher *new_cipher); * * DESCRIPTION * - * Allocates a new SILC cipher object. Function returns 1 on succes and 0 - * 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 ciphers set_key function. + * 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: * @@ -169,21 +210,25 @@ SilcBool silc_cipher_unregister_all(void); * * Notes about modes: * - * 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. + ***/ +SilcBool silc_cipher_alloc(const char *name, SilcCipher *new_cipher); + +/****f* silccrypt/SilcCipherAPI/silc_cipher_alloc + * + * SYNOPSIS + * + * SilcBool silc_cipher_alloc_full(const char *alg_name, + * SilcUInt32 key_len, + * SilcCipherMode mode, + * SilcCipher *new_cipher); + * DESCRIPTION * - * 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. + * Same as silc_cipher_alloc but takes the cipher algorithm name, + * key length and mode as separate arguments. * ***/ -SilcBool silc_cipher_alloc(const unsigned char *name, SilcCipher *new_cipher); +SilcBool silc_cipher_alloc_full(const char *alg_name, SilcUInt32 key_len, + SilcCipherMode mode, SilcCipher *new_cipher); /****f* silccrypt/SilcCipherAPI/silc_cipher_free * @@ -202,14 +247,14 @@ 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 * @@ -273,7 +318,7 @@ SilcBool silc_cipher_decrypt(SilcCipher cipher, const unsigned char *src, * SYNOPSIS * * SilcBool silc_cipher_set_key(SilcCipher cipher, const unsigned char *key, - * SilcUInt32 keylen, SilcBool encryption); + * SilcUInt32 bit_keylen, SilcBool encryption); * * DESCRIPTION * @@ -283,7 +328,7 @@ SilcBool silc_cipher_decrypt(SilcCipher cipher, const unsigned char *src, * ***/ SilcBool silc_cipher_set_key(SilcCipher cipher, const unsigned char *key, - SilcUInt32 keylen, SilcBool encryption); + SilcUInt32 bit_keylen, SilcBool encryption); /****f* silccrypt/SilcCipherAPI/silc_cipher_set_iv * @@ -293,13 +338,16 @@ SilcBool silc_cipher_set_key(SilcCipher cipher, const unsigned char *key, * * DESCRIPTION * - * Sets the IV (initial vector) for the cipher. The `iv' must be + * 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); @@ -365,11 +413,24 @@ SilcUInt32 silc_cipher_get_iv_len(SilcCipher cipher); * * DESCRIPTION * - * Returns the name of the cipher. + * Returns the full name of the cipher (eg. 'aes-256-ctr'). * ***/ const char *silc_cipher_get_name(SilcCipher cipher); +/****f* silccrypt/SilcCipherAPI/silc_cipher_get_alg_name + * + * SYNOPSIS + * + * const char *silc_cipher_get_alg_name(SilcCipher cipher); + * + * DESCRIPTION + * + * Returns the algorithm name of the cipher (eg. 'aes'). + * + ***/ +const char *silc_cipher_get_alg_name(SilcCipher cipher); + /****f* silccrypt/SilcCipherAPI/silc_cipher_get_mode * * SYNOPSIS