Added SILC Thread Queue API

[silc.git] / lib / silccrypt / silccipher.h

diff --git a/lib/silccrypt/silccipher.h b/lib/silccrypt/silccipher.h
index 5981ce73caef15718e3e5b3171518998a6fb4e3e..a0503c899105d6ffa06c1f3c72fde2f8e332a2af 100644 (file)
--- a/lib/silccrypt/silccipher.h
+++ b/lib/silccrypt/silccipher.h
@@ -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,7 +186,7 @@ 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
@@ -169,21 +210,8 @@ 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.
- *
- *    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.
- *
  ***/
-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
  *
@@ -202,14 +230,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
  *
@@ -293,13 +321,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);