silccipher.h
- Author: Pekka Riikonen <priikone@poseidon.pspt.fi>
+ Author: Pekka Riikonen <priikone@silcnet.org>
- Copyright (C) 1997 - 2001 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
- the Free Software Foundation; either version 2 of the License, or
- (at your option) any later version.
-
+ the Free Software Foundation; version 2 of the License.
+
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
*/
+/****h* silccrypt/SILC Cipher Interface
+ *
+ * DESCRIPTION
+ *
+ * This is the interface for cipher functions. It provides cipher
+ * registering and unregistering routines, encryption and decryption
+ * routines.
+ *
+ ***/
+
#ifndef SILCCIPHER_H
#define SILCCIPHER_H
-/*
- SILC Cipher object.
+/* Forward declarations */
+typedef struct SilcCipherObjectStruct SilcCipherObject;
- Default SILC cipher object to represent any cipher. The function
- pointers are the stub functions for each implemented cipher. Following
- short description of the fields:
+/****s* silccrypt/SilcCipher
+ *
+ * NAME
+ *
+ * typedef struct SilcCipherStruct *SilcCipher;
+ *
+ * DESCRIPTION
+ *
+ * This context is the actual cipher context and is allocated
+ * by silc_cipher_alloc and given as argument usually to all
+ * silc_cipher _* functions. It is freed by the silc_cipher_free
+ * function.
+ *
+ ***/
+typedef struct SilcCipherStruct *SilcCipher;
- char *name
+/****d* silccrypt/Ciphers
+ *
+ * NAME
+ *
+ * Ciphers
+ *
+ * DESCRIPTION
+ *
+ * Supported ciphers names. These names can be given as argument
+ * to silc_cipher_alloc.
+ *
+ * SOURCE
+ */
- Logical name of the cipher.
+/* 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"
- uint32 block_len
+/* 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"
- Block size of the cipher.
+/* 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"
- uint32 key_len
+/* 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"
- Length of the key of the cipher (in bits).
+/* 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"
-*/
-typedef struct {
- char *name;
- uint32 block_len;
- uint32 key_len;
-
- int (*set_key)(void *, const unsigned char *, uint32);
- int (*set_key_with_string)(void *, const unsigned char *, uint32);
- int (*encrypt)(void *, const unsigned char *, unsigned char *,
- uint32, unsigned char *);
- int (*decrypt)(void *, const unsigned char *, unsigned char *,
- uint32, unsigned char *);
- uint32 (*context_len)();
-} SilcCipherObject;
-
-#define SILC_CIPHER_MAX_IV_SIZE 16
-
-/* The main SilcCipher structure. Use SilcCipher instead of SilcCipherStruct.
- Also remember that SilcCipher is a pointer. */
-typedef struct SilcCipherStruct {
- SilcCipherObject *cipher;
- void *context;
- unsigned char iv[SILC_CIPHER_MAX_IV_SIZE];
-
- void (*set_iv)(struct SilcCipherStruct *, const unsigned char *);
- void (*get_iv)(struct SilcCipherStruct *, unsigned char *);
- uint32 (*get_key_len)(struct SilcCipherStruct *);
- uint32 (*get_block_len)(struct SilcCipherStruct *);
-} *SilcCipher;
-
-/* List of all registered ciphers. */
-extern struct SilcCipherListStruct *silc_cipher_list;
+/* 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
+ *
+ * typedef enum { ... } SilcCipherMode;
+ *
+ * DESCRIPTION
+ *
+ * Cipher modes. Notes about cipher modes and implementation:
+ *
+ * SILC_CIPHER_MODE_CBC
+ *
+ * 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 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 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 alone.
+ *
+ * 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
+ */
+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 */
/* 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)
-/* 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) \
-int silc_##cipher##_set_key(void *context, \
- const unsigned char *key, \
- uint32 keylen)
-#define SILC_CIPHER_API_SET_KEY_WITH_STRING(cipher) \
-int silc_##cipher##_set_key_with_string(void *context, \
- const unsigned char *string, \
- uint32 stringlen)
-#define SILC_CIPHER_API_ENCRYPT_CBC(cipher) \
-int silc_##cipher##_encrypt_cbc(void *context, \
- const unsigned char *src, \
- unsigned char *dst, \
- uint32 len, \
- unsigned char *iv)
-#define SILC_CIPHER_API_DECRYPT_CBC(cipher) \
-int silc_##cipher##_decrypt_cbc(void *context, \
- const unsigned char *src, \
- unsigned char *dst, \
- uint32 len, \
- unsigned char *iv)
-#define SILC_CIPHER_API_CONTEXT_LEN(cipher) \
-uint32 silc_##cipher##_context_len()
+#include "silccipher_i.h"
+
+/* Static list of ciphers for silc_cipher_register_default(). */
+extern DLLAPI const SilcCipherObject silc_default_ciphers[];
/* Prototypes */
-int silc_cipher_register(SilcCipherObject *cipher);
-int silc_cipher_unregister(SilcCipherObject *cipher);
-int silc_cipher_alloc(const unsigned char *name, SilcCipher *new_cipher);
+
+/****f* silccrypt/silc_cipher_register
+ *
+ * SYNOPSIS
+ *
+ * SilcBool silc_cipher_register(const SilcCipherObject *cipher);
+ *
+ * DESCRIPTION
+ *
+ * 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/silc_cipher_unregister
+ *
+ * SYNOPSIS
+ *
+ * SilcBool silc_cipher_unregister(SilcCipherObject *cipher);
+ *
+ * DESCRIPTION
+ *
+ * Unregister a cipher from the SILC.
+ *
+ ***/
+SilcBool silc_cipher_unregister(SilcCipherObject *cipher);
+
+/****f* silccrypt/silc_cipher_register_default
+ *
+ * SYNOPSIS
+ *
+ * SilcBool silc_cipher_register_default(void);
+ *
+ * DESCRIPTION
+ *
+ * Function that registers all the default ciphers (all builtin ciphers).
+ * Application need not call this directly. By calling silc_crypto_init
+ * this function is called.
+ *
+ ***/
+SilcBool silc_cipher_register_default(void);
+
+/****f* silccrypt/silc_cipher_unregister_all
+ *
+ * SYNOPSIS
+ *
+ * SilcBool silc_cipher_unregister_all(void);
+ *
+ * DESCRIPTION
+ *
+ * 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/silc_cipher_alloc
+ *
+ * SYNOPSIS
+ *
+ * SilcBool silc_cipher_alloc(const char *name,
+ * SilcCipher *new_cipher);
+ *
+ * DESCRIPTION
+ *
+ * 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.
+ *
+ ***/
+SilcBool silc_cipher_alloc(const char *name, SilcCipher *new_cipher);
+
+/****f* silccrypt/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/silc_cipher_free
+ *
+ * SYNOPSIS
+ *
+ * void silc_cipher_free(SilcCipher cipher);
+ *
+ * DESCRIPTION
+ *
+ * Frees the given cipher.
+ *
+ ***/
void silc_cipher_free(SilcCipher cipher);
-int silc_cipher_is_supported(const unsigned char *name);
-char *silc_cipher_get_supported();
-int silc_cipher_encrypt(SilcCipher cipher, const unsigned char *src,
- unsigned char *dst, uint32 len,
- unsigned char *iv);
-int silc_cipher_decrypt(SilcCipher cipher, const unsigned char *src,
- unsigned char *dst, uint32 len,
- unsigned char *iv);
-int silc_cipher_set_key(SilcCipher cipher, const unsigned char *key,
- uint32 keylen);
+
+/****f* silccrypt/silc_cipher_is_supported
+ *
+ * SYNOPSIS
+ *
+ * SilcBool silc_cipher_is_supported(const char *name);
+ *
+ * DESCRIPTION
+ *
+ * Returns TRUE if cipher `name' is supported.
+ *
+ ***/
+SilcBool silc_cipher_is_supported(const char *name);
+
+/****f* silccrypt/silc_cipher_get_supported
+ *
+ * SYNOPSIS
+ *
+ * char *silc_cipher_get_supported(SilcBool only_registered);
+ *
+ * DESCRIPTION
+ *
+ * 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(SilcBool only_registered);
+
+/****f* silccrypt/silc_cipher_encrypt
+ *
+ * SYNOPSIS
+ *
+ * SilcBool silc_cipher_encrypt(SilcCipher cipher,
+ * const unsigned char *src,
+ * unsigned char *dst, SilcUInt32 len,
+ * unsigned char *iv);
+ *
+ * DESCRIPTION
+ *
+ * Encrypts data from `src' into `dst' with the specified cipher and
+ * Initial Vector (IV). If the `iv' is NULL then the cipher's internal
+ * IV is used. The `src' and `dst' maybe same buffer.
+ *
+ ***/
+SilcBool silc_cipher_encrypt(SilcCipher cipher, const unsigned char *src,
+ unsigned char *dst, SilcUInt32 len,
+ unsigned char *iv);
+
+/****f* silccrypt/silc_cipher_decrypt
+ *
+ * SYNOPSIS
+ *
+ * SilcBool silc_cipher_decrypt(SilcCipher cipher,
+ * const unsigned char *src,
+ * unsigned char *dst, SilcUInt32 len,
+ * unsigned char *iv);
+ *
+ * DESCRIPTION
+ *
+ * Decrypts data from `src' into `dst' with the specified cipher and
+ * Initial Vector (IV). If the `iv' is NULL then the cipher's internal
+ * IV is used. The `src' and `dst' maybe same buffer.
+ *
+ ***/
+SilcBool silc_cipher_decrypt(SilcCipher cipher, const unsigned char *src,
+ unsigned char *dst, SilcUInt32 len,
+ unsigned char *iv);
+
+/****f* silccrypt/silc_cipher_set_key
+ *
+ * SYNOPSIS
+ *
+ * SilcBool silc_cipher_set_key(SilcCipher cipher, const unsigned char *key,
+ * SilcUInt32 bit_keylen, SilcBool encryption);
+ *
+ * DESCRIPTION
+ *
+ * Sets the key for the cipher. The `keylen' is the key length in
+ * 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 bit_keylen, SilcBool encryption);
+
+/****f* silccrypt/silc_cipher_set_iv
+ *
+ * SYNOPSIS
+ *
+ * void silc_cipher_set_iv(SilcCipher cipher, const unsigned char *iv);
+ *
+ * DESCRIPTION
+ *
+ * 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);
-void silc_cipher_get_iv(SilcCipher cipher, unsigned char *iv);
-uint32 silc_cipher_get_key_len(SilcCipher cipher);
-uint32 silc_cipher_get_block_len(SilcCipher cipher);
-#endif
+/****f* silccrypt/silc_cipher_get_iv
+ *
+ * SYNOPSIS
+ *
+ * unsigned char *silc_cipher_get_iv(SilcCipher cipher);
+ *
+ * DESCRIPTION
+ *
+ * Returns the IV (initial vector) of the cipher. The returned
+ * 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);
+
+/****f* silccrypt/silc_cipher_get_key_len
+ *
+ * SYNOPSIS
+ *
+ * SilcUInt32 silc_cipher_get_key_len(SilcCipher cipher);
+ *
+ * DESCRIPTION
+ *
+ * Returns the key length of the cipher in bits.
+ *
+ ***/
+SilcUInt32 silc_cipher_get_key_len(SilcCipher cipher);
+
+/****f* silccrypt/silc_cipher_get_block_len
+ *
+ * SYNOPSIS
+ *
+ * SilcUInt32 silc_cipher_get_block_len(SilcCipher cipher);
+ *
+ * DESCRIPTION
+ *
+ * Returns the block size of the cipher in bytes.
+ *
+ ***/
+SilcUInt32 silc_cipher_get_block_len(SilcCipher cipher);
+
+/****f* silccrypt/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/silc_cipher_get_name
+ *
+ * SYNOPSIS
+ *
+ * const char *silc_cipher_get_name(SilcCipher cipher);
+ *
+ * DESCRIPTION
+ *
+ * Returns the full name of the cipher (eg. 'aes-256-ctr').
+ *
+ ***/
+const char *silc_cipher_get_name(SilcCipher cipher);
+
+/****f* silccrypt/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/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