lib/silccrypt/silccipher.h

   1 /*
   2
   3   silccipher.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 1997 - 2005 Pekka Riikonen
   8
   9   This program is free software; you can redistribute it and/or modify
  10   it under the terms of the GNU General Public License as published by
  11   the Free Software Foundation; version 2 of the License.
  12
  13   This program is distributed in the hope that it will be useful,
  14   but WITHOUT ANY WARRANTY; without even the implied warranty of
  15   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16   GNU General Public License for more details.
  17
  18 */
  19
  20 #ifndef SILCCIPHER_H
  21 #define SILCCIPHER_H
  22
  23 /****h* silccrypt/SILC Cipher Interface
  24  *
  25  * DESCRIPTION
  26  *
  27  * This is the interface for cipher functions.  It provides cipher
  28  * registering and unregistering routines, encryption and decryption
  29  * routines.
  30  *
  31  ***/
  32
  33 /****s* silccrypt/SilcCipherAPI/SilcCipher
  34  *
  35  * NAME
  36  *
  37  *    typedef struct { ... } SilcCipher;
  38  *
  39  * DESCRIPTION
  40  *
  41  *    This context is the actual cipher context and is allocated
  42  *    by silc_cipher_alloc and given as argument usually to all
  43  *    silc_cipher _* functions.  It is freed by the silc_cipher_free
  44  *    function.
  45  *
  46  ***/
  47 typedef struct SilcCipherStruct *SilcCipher;
  48
  49 /* The default SILC Cipher object to represent any cipher in SILC. */
  50 typedef struct {
  51   char *name;
  52   SilcUInt32 block_len;
  53   SilcUInt32 key_len;
  54
  55   SilcBool (*set_key)(void *, const unsigned char *, SilcUInt32);
  56   SilcBool (*set_key_with_string)(void *, const unsigned char *, SilcUInt32);
  57   SilcBool (*encrypt)(void *, const unsigned char *, unsigned char *,
  58                   SilcUInt32, unsigned char *);
  59   SilcBool (*decrypt)(void *, const unsigned char *, unsigned char *,
  60                   SilcUInt32, unsigned char *);
  61   SilcUInt32 (*context_len)();
  62 } SilcCipherObject;
  63
  64 #define SILC_CIPHER_MAX_IV_SIZE 16
  65
  66 /* Marks for all ciphers in silc. This can be used in silc_cipher_unregister
  67    to unregister all ciphers at once. */
  68 #define SILC_ALL_CIPHERS ((SilcCipherObject *)1)
  69
  70 /* Static list of ciphers for silc_cipher_register_default(). */
  71 extern DLLAPI const SilcCipherObject silc_default_ciphers[];
  72
  73 /* Default cipher in the SILC protocol */
  74 #define SILC_DEFAULT_CIPHER "aes-256-cbc"
  75
  76
  77 /* Macros */
  78
  79 /* Function names in SILC Crypto modules. The name of the cipher
  80    is appended into these names and used to the get correct symbol out
  81    of the module. All SILC Crypto API compliant modules must support
  82    these function names (use macros below to assure this). */
  83 #define SILC_CIPHER_SIM_SET_KEY "set_key"
  84 #define SILC_CIPHER_SIM_SET_KEY_WITH_STRING "set_key_with_string"
  85 #define SILC_CIPHER_SIM_ENCRYPT_CBC "encrypt_cbc"
  86 #define SILC_CIPHER_SIM_DECRYPT_CBC "decrypt_cbc"
  87 #define SILC_CIPHER_SIM_CONTEXT_LEN "context_len"
  88
  89 /* These macros can be used to implement the SILC Crypto API and to avoid
  90    errors in the API these macros should be used always. */
  91 #define SILC_CIPHER_API_SET_KEY(cipher)                 \
  92 SilcBool silc_##cipher##_set_key(void *context,         \
  93                              const unsigned char *key,  \
  94                              SilcUInt32 keylen)
  95 #define SILC_CIPHER_API_SET_KEY_WITH_STRING(cipher)                     \
  96 SilcBool silc_##cipher##_set_key_with_string(void *context,                     \
  97                                          const unsigned char *string,   \
  98                                          SilcUInt32 stringlen)
  99 #define SILC_CIPHER_API_ENCRYPT_CBC(cipher)                     \
 100 SilcBool silc_##cipher##_encrypt_cbc(void *context,                     \
 101                                  const unsigned char *src,      \
 102                                  unsigned char *dst,            \
 103                                  SilcUInt32 len,                \
 104                                  unsigned char *iv)
 105 #define SILC_CIPHER_API_DECRYPT_CBC(cipher)                     \
 106 SilcBool silc_##cipher##_decrypt_cbc(void *context,                     \
 107                                  const unsigned char *src,      \
 108                                  unsigned char *dst,            \
 109                                  SilcUInt32 len,                \
 110                                  unsigned char *iv)
 111
 112
 113 #define SILC_CIPHER_API_CONTEXT_LEN(cipher)                     \
 114 SilcUInt32 silc_##cipher##_context_len()
 115
 116
 117 /* Prototypes */
 118
 119 /****f* silccrypt/SilcCipherAPI/silc_cipher_register
 120  *
 121  * SYNOPSIS
 122  *
 123  *    SilcBool silc_cipher_register(const SilcCipherObject *cipher);
 124  *
 125  * DESCRIPTION
 126  *
 127  *    Register a new cipher into SILC. This is used at the initialization of
 128  *    the SILC. This function allocates a new object for the cipher to be
 129  *    registered. Therefore, if memory has been allocated for the object sent
 130  *    as argument it has to be free'd after this function returns succesfully.
 131  *
 132  ***/
 133 SilcBool silc_cipher_register(const SilcCipherObject *cipher);
 134
 135 /****f* silccrypt/SilcCipherAPI/silc_cipher_unregister
 136  *
 137  * SYNOPSIS
 138  *
 139  *    SilcBool silc_cipher_unregister(SilcCipherObject *cipher);
 140  *
 141  * DESCRIPTION
 142  *
 143  *    Unregister a cipher from the SILC.
 144  *
 145  ***/
 146 SilcBool silc_cipher_unregister(SilcCipherObject *cipher);
 147
 148 /****f* silccrypt/SilcCipherAPI/silc_cipher_register_default
 149  *
 150  * SYNOPSIS
 151  *
 152  *    SilcBool silc_cipher_register_default(void);
 153  *
 154  * DESCRIPTION
 155  *
 156  *    Function that registers all the default ciphers (all builtin ciphers).
 157  *    The application may use this to register the default ciphers if specific
 158  *    ciphers in any specific order is not wanted.
 159  *
 160  ***/
 161 SilcBool silc_cipher_register_default(void);
 162
 163 /****f* silccrypt/SilcCipherAPI/silc_cipher_unregister_all
 164  *
 165  * SYNOPSIS
 166  *
 167  *    SilcBool silc_cipher_unregister_all(void);
 168  *
 169  * DESCRIPTION
 170  *
 171  *    Unregisters all ciphers.
 172  *
 173  ***/
 174 SilcBool silc_cipher_unregister_all(void);
 175
 176 /****f* silccrypt/SilcCipherAPI/silc_cipher_alloc
 177  *
 178  * SYNOPSIS
 179  *
 180  *    SilcBool silc_cipher_alloc(const unsigned char *name,
 181  *                           SilcCipher *new_cipher);
 182  *
 183  * DESCRIPTION
 184  *
 185  *    Allocates a new SILC cipher object. Function returns 1 on succes and 0
 186  *    on error. The allocated cipher is returned in new_cipher argument. The
 187  *    caller must set the key to the cipher after this function has returned
 188  *    by calling the ciphers set_key function.
 189  *
 190  ***/
 191 SilcBool silc_cipher_alloc(const unsigned char *name, SilcCipher *new_cipher);
 192
 193 /****f* silccrypt/SilcCipherAPI/silc_cipher_free
 194  *
 195  * SYNOPSIS
 196  *
 197  *    void silc_cipher_free(SilcCipher cipher);
 198  *
 199  * DESCRIPTION
 200  *
 201  *    Frees the given cipher.
 202  *
 203  ***/
 204 void silc_cipher_free(SilcCipher cipher);
 205
 206 /****f* silccrypt/SilcCipherAPI/silc_cipher_is_supported
 207  *
 208  * SYNOPSIS
 209  *
 210  * SilcBool silc_cipher_is_supported(const unsigned char *name);
 211  *
 212  * DESCRIPTION
 213  *
 214  *    Returns TRUE if cipher `name' is supported.
 215  *
 216  ***/
 217 SilcBool silc_cipher_is_supported(const unsigned char *name);
 218
 219 /****f* silccrypt/SilcCipherAPI/silc_cipher_get_supported
 220  *
 221  * SYNOPSIS
 222  *
 223  *    char *silc_cipher_get_supported(void);
 224  *
 225  * DESCRIPTION
 226  *
 227  *    Returns comma separated list of supported ciphers.
 228  *
 229  ***/
 230 char *silc_cipher_get_supported(void);
 231
 232 /****f* silccrypt/SilcCipherAPI/silc_cipher_encrypt
 233  *
 234  * SYNOPSIS
 235  *
 236  *    SilcBool silc_cipher_encrypt(SilcCipher cipher,
 237  *                                 const unsigned char *src,
 238  *                                 unsigned char *dst, SilcUInt32 len,
 239  *                                 unsigned char *iv);
 240  *
 241  * DESCRIPTION
 242  *
 243  *    Encrypts data from `src' into `dst' with the specified cipher and
 244  *    Initial Vector (IV).  If the `iv' is NULL then the cipher's internal
 245  *    IV is used.  The `src' and `dst' maybe same buffer.
 246  *
 247  ***/
 248 SilcBool silc_cipher_encrypt(SilcCipher cipher, const unsigned char *src,
 249                              unsigned char *dst, SilcUInt32 len,
 250                              unsigned char *iv);
 251
 252 /****f* silccrypt/SilcCipherAPI/silc_cipher_decrypt
 253  *
 254  * SYNOPSIS
 255  *
 256  *    SilcBool silc_cipher_decrypt(SilcCipher cipher,
 257  *                                 const unsigned char *src,
 258  *                                 unsigned char *dst, SilcUInt32 len,
 259  *                                 unsigned char *iv);
 260  *
 261  * DESCRIPTION
 262  *
 263  *    Decrypts data from `src' into `dst' with the specified cipher and
 264  *    Initial Vector (IV).  If the `iv' is NULL then the cipher's internal
 265  *    IV is used.  The `src' and `dst' maybe same buffer.
 266  *
 267  ***/
 268 SilcBool silc_cipher_decrypt(SilcCipher cipher, const unsigned char *src,
 269                              unsigned char *dst, SilcUInt32 len,
 270                              unsigned char *iv);
 271
 272 /****f* silccrypt/SilcCipherAPI/silc_cipher_set_key
 273  *
 274  * SYNOPSIS
 275  *
 276  *    SilcBool silc_cipher_set_key(SilcCipher cipher, const unsigned char *key,
 277  *                             SilcUInt32 keylen);
 278  *
 279  * DESCRIPTION
 280  *
 281  *    Sets the key for the cipher.  The `keylen' is the key length in
 282  *    bits.
 283  *
 284  ***/
 285 SilcBool silc_cipher_set_key(SilcCipher cipher, const unsigned char *key,
 286                              SilcUInt32 keylen);
 287
 288 /****f* silccrypt/SilcCipherAPI/silc_cipher_set_iv
 289  *
 290  * SYNOPSIS
 291  *
 292  *    void silc_cipher_set_iv(SilcCipher cipher, const unsigned char *iv);
 293  *
 294  * DESCRIPTION
 295  *
 296  *    Sets the IV (initial vector) for the cipher.  The `iv' must be
 297  *    the size of the block size of the cipher.
 298  *
 299  ***/
 300 void silc_cipher_set_iv(SilcCipher cipher, const unsigned char *iv);
 301
 302 /****f* silccrypt/SilcCipherAPI/silc_cipher_get_iv
 303  *
 304  * SYNOPSIS
 305  *
 306  *    unsigned char *silc_cipher_get_iv(SilcCipher cipher);
 307  *
 308  * DESCRIPTION
 309  *
 310  *    Returns the IV (initial vector) of the cipher.  The returned
 311  *    pointer must not be freed by the caller.
 312  *
 313  ***/
 314 unsigned char *silc_cipher_get_iv(SilcCipher cipher);
 315
 316 /****f* silccrypt/SilcCipherAPI/silc_cipher_get_key_len
 317  *
 318  * SYNOPSIS
 319  *
 320  *    SilcUInt32 silc_cipher_get_key_len(SilcCipher cipher);
 321  *
 322  * DESCRIPTION
 323  *
 324  *    Returns the key length of the cipher in bits.
 325  *
 326  ***/
 327 SilcUInt32 silc_cipher_get_key_len(SilcCipher cipher);
 328
 329 /****f* silccrypt/SilcCipherAPI/silc_cipher_get_block_len
 330  *
 331  * SYNOPSIS
 332  *
 333  *    SilcUInt32 silc_cipher_get_block_len(SilcCipher cipher);
 334  *
 335  * DESCRIPTION
 336  *
 337  *    Returns the block size of the cipher in bytes.
 338  *
 339  ***/
 340 SilcUInt32 silc_cipher_get_block_len(SilcCipher cipher);
 341
 342 /****f* silccrypt/SilcCipherAPI/silc_cipher_get_name
 343  *
 344  * SYNOPSIS
 345  *
 346  *    const char *silc_cipher_get_name(SilcCipher cipher);
 347  *
 348  * DESCRIPTION
 349  *
 350  *    Returns the name of the cipher.
 351  *
 352  ***/
 353 const char *silc_cipher_get_name(SilcCipher cipher);
 354
 355 #endif