Author: Pekka Riikonen <priikone@silcnet.org>
- Copyright (C) 1997 - 2006 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
*/
-#ifndef SILCCIPHER_H
-#define SILCCIPHER_H
-
/****h* silccrypt/SILC Cipher Interface
*
* DESCRIPTION
*
***/
+#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
*
***/
typedef struct SilcCipherStruct *SilcCipher;
-/* The default SILC Cipher object to represent any cipher in SILC. */
-typedef struct {
- char *name;
- 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)();
- unsigned int key_len : 12;
- unsigned int block_len : 10;
- unsigned int iv_len : 10;
-} SilcCipherObject;
-
-#define SILC_CIPHER_MAX_IV_SIZE 16
+/****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 /* 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
*
* SYNOPSIS
*
- * SilcBool silc_cipher_alloc(const unsigned char *name,
- * SilcCipher *new_cipher);
+ * 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:
+ *
+ * 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_alloc
+ *
+ * SYNOPSIS
+ *
+ * SilcBool silc_cipher_alloc_full(const char *alg_name,
+ * SilcUInt32 key_len,
+ * SilcCipherMode mode,
+ * SilcCipher *new_cipher);
+ * DESCRIPTION
+ *
+ * Same as silc_cipher_alloc but takes the cipher algorithm name,
+ * 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
*
*
* 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
*
* SYNOPSIS
*
* SilcBool silc_cipher_set_key(SilcCipher cipher, const unsigned char *key,
- * SilcUInt32 keylen);
+ * SilcUInt32 bit_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 bit_keylen, SilcBool encryption);
/****f* silccrypt/SilcCipherAPI/silc_cipher_set_iv
*
*
* 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);
* 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);
*
* 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);
-#endif
+/****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
+ *
+ * SilcCipherMode silc_cipher_get_mode(SilcCipher cipher);
+ *
+ * DESCRIPTION
+ *
+ * Returns the cipher mode.
+ *
+ ***/
+SilcCipherMode silc_cipher_get_mode(SilcCipher cipher);
+
+#endif /* SILCCIPHER_H */
projects / crypto.git / blobdiff