lib/silccrypt/silccipher.h

   1 /*
   2
   3   silccipher.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 1997 - 2002 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   bool (*set_key)(void *, const unsigned char *, SilcUInt32);
  56   bool (*set_key_with_string)(void *, const unsigned char *, SilcUInt32);
  57   bool (*encrypt)(void *, const unsigned char *, unsigned char *,
  58                   SilcUInt32, unsigned char *);
  59   bool (*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 bool 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 bool 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 bool 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 bool 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  *    bool 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 bool silc_cipher_register(const SilcCipherObject *cipher);
 134
 135 /****f* silccrypt/SilcCipherAPI/silc_cipher_unregister
 136  *
 137  * SYNOPSIS
 138  *
 139  *    bool silc_cipher_unregister(SilcCipherObject *cipher);
 140  *
 141  * DESCRIPTION
 142  *
 143  *    Unregister a cipher from the SILC.
 144  *
 145  ***/
 146 bool silc_cipher_unregister(SilcCipherObject *cipher);
 147
 148 /****f* silccrypt/SilcCipherAPI/silc_cipher_register_default
 149  *
 150  * SYNOPSIS
 151  *
 152  *    bool 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 bool silc_cipher_register_default(void);
 162
 163 /****f* silccrypt/SilcCipherAPI/silc_cipher_unregister_all
 164  *
 165  * SYNOPSIS
 166  *
 167  *    bool silc_cipher_unregister_all(void);
 168  *
 169  * DESCRIPTION
 170  *
 171  *    Unregisters all ciphers.
 172  *
 173  ***/
 174 bool silc_cipher_unregister_all(void);
 175
 176 /****f* silccrypt/SilcCipherAPI/silc_cipher_alloc
 177  *
 178  * SYNOPSIS
 179  *
 180  *    bool 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 bool 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  * bool silc_cipher_is_supported(const unsigned char *name);
 211  *
 212  * DESCRIPTION
 213  *
 214  *    Returns TRUE if cipher `name' is supported.
 215  *
 216  ***/
 217 bool 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  *    bool silc_cipher_encrypt(SilcCipher cipher, const unsigned char *src,
 237  *                             unsigned char *dst, SilcUInt32 len,
 238  *                             unsigned char *iv);
 239  *
 240  * DESCRIPTION
 241  *
 242  *    Encrypts data from `src' into `dst' with the specified cipher and
 243  *    Initial Vector (IV).  If the `iv' is NULL then the cipher's internal
 244  *    IV is used.  The `src' and `dst' maybe same buffer.
 245  *
 246  ***/
 247 bool silc_cipher_encrypt(SilcCipher cipher, const unsigned char *src,
 248                          unsigned char *dst, SilcUInt32 len,
 249                          unsigned char *iv);
 250
 251 /****f* silccrypt/SilcCipherAPI/silc_cipher_decrypt
 252  *
 253  * SYNOPSIS
 254  *
 255  *    bool silc_cipher_decrypt(SilcCipher cipher, const unsigned char *src,
 256  *                             unsigned char *dst, SilcUInt32 len,
 257  *                             unsigned char *iv);
 258  *
 259  * DESCRIPTION
 260  *
 261  *    Decrypts data from `src' into `dst' with the specified cipher and
 262  *    Initial Vector (IV).  If the `iv' is NULL then the cipher's internal
 263  *    IV is used.  The `src' and `dst' maybe same buffer.
 264  *
 265  ***/
 266 bool silc_cipher_decrypt(SilcCipher cipher, const unsigned char *src,
 267                          unsigned char *dst, SilcUInt32 len,
 268                          unsigned char *iv);
 269
 270 /****f* silccrypt/SilcCipherAPI/silc_cipher_set_key
 271  *
 272  * SYNOPSIS
 273  *
 274  *    bool silc_cipher_set_key(SilcCipher cipher, const unsigned char *key,
 275  *                             SilcUInt32 keylen);
 276  *
 277  * DESCRIPTION
 278  *
 279  *    Sets the key for the cipher.  The `keylen' is the key length in
 280  *    bits.
 281  *
 282  ***/
 283 bool silc_cipher_set_key(SilcCipher cipher, const unsigned char *key,
 284                          SilcUInt32 keylen);
 285
 286 /****f* silccrypt/SilcCipherAPI/silc_cipher_set_iv
 287  *
 288  * SYNOPSIS
 289  *
 290  *    void silc_cipher_set_iv(SilcCipher cipher, const unsigned char *iv);
 291  *
 292  * DESCRIPTION
 293  *
 294  *    Sets the IV (initial vector) for the cipher.  The `iv' must be
 295  *    the size of the block size of the cipher.
 296  *
 297  ***/
 298 void silc_cipher_set_iv(SilcCipher cipher, const unsigned char *iv);
 299
 300 /****f* silccrypt/SilcCipherAPI/silc_cipher_get_iv
 301  *
 302  * SYNOPSIS
 303  *
 304  *    unsigned char *silc_cipher_get_iv(SilcCipher cipher);
 305  *
 306  * DESCRIPTION
 307  *
 308  *    Returns the IV (initial vector) of the cipher.  The returned
 309  *    pointer must not be freed by the caller.
 310  *
 311  ***/
 312 unsigned char *silc_cipher_get_iv(SilcCipher cipher);
 313
 314 /****f* silccrypt/SilcCipherAPI/silc_cipher_get_key_len
 315  *
 316  * SYNOPSIS
 317  *
 318  *    SilcUInt32 silc_cipher_get_key_len(SilcCipher cipher);
 319  *
 320  * DESCRIPTION
 321  *
 322  *    Returns the key length of the cipher in bits.
 323  *
 324  ***/
 325 SilcUInt32 silc_cipher_get_key_len(SilcCipher cipher);
 326
 327 /****f* silccrypt/SilcCipherAPI/silc_cipher_get_block_len
 328  *
 329  * SYNOPSIS
 330  *
 331  *    SilcUInt32 silc_cipher_get_block_len(SilcCipher cipher);
 332  *
 333  * DESCRIPTION
 334  *
 335  *    Returns the block size of the cipher in bytes.
 336  *
 337  ***/
 338 SilcUInt32 silc_cipher_get_block_len(SilcCipher cipher);
 339
 340 /****f* silccrypt/SilcCipherAPI/silc_cipher_get_name
 341  *
 342  * SYNOPSIS
 343  *
 344  *    const char *silc_cipher_get_name(SilcCipher cipher);
 345  *
 346  * DESCRIPTION
 347  *
 348  *    Returns the name of the cipher.
 349  *
 350  ***/
 351 const char *silc_cipher_get_name(SilcCipher cipher);
 352
 353 #endif