lib/silccrypt/silccipher.h

   1 /*
   2
   3   silccipher.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 1997 - 2006 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   SilcBool (*set_key)(void *, const unsigned char *, SilcUInt32, SilcBool);
  53   SilcBool (*encrypt)(void *, const unsigned char *, unsigned char *,
  54                       SilcUInt32, unsigned char *);
  55   SilcBool (*decrypt)(void *, const unsigned char *, unsigned char *,
  56                       SilcUInt32, unsigned char *);
  57   SilcUInt32 (*context_len)();
  58   unsigned int key_len   : 10;
  59   unsigned int block_len : 8;
  60   unsigned int iv_len    : 8;
  61   unsigned int mode      : 6;
  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 /* Macros */
  77
  78 /* Function names in SILC Crypto modules. The name of the cipher
  79    is appended into these names and used to the get correct symbol out
  80    of the module. All SILC Crypto API compliant modules must support
  81    these function names (use macros below to assure this). */
  82 #define SILC_CIPHER_SIM_SET_KEY "set_key"
  83 #define SILC_CIPHER_SIM_ENCRYPT "encrypt"
  84 #define SILC_CIPHER_SIM_DECRYPT "decrypt"
  85 #define SILC_CIPHER_SIM_CONTEXT_LEN "context_len"
  86
  87 /* These macros can be used to implement the SILC Crypto API and to avoid
  88    errors in the API these macros should be used always. */
  89 #define SILC_CIPHER_API_SET_KEY(cipher)                         \
  90 SilcBool silc_##cipher##_set_key(void *context,                 \
  91                                  const unsigned char *key,      \
  92                                  SilcUInt32 keylen,             \
  93                                  SilcBool encryption)
  94 #define SILC_CIPHER_API_ENCRYPT(cipher)                         \
  95 SilcBool silc_##cipher##_encrypt(void *context,                 \
  96                                  const unsigned char *src,      \
  97                                  unsigned char *dst,            \
  98                                  SilcUInt32 len,                \
  99                                  unsigned char *iv)
 100 #define SILC_CIPHER_API_DECRYPT(cipher)                         \
 101 SilcBool silc_##cipher##_decrypt(void *context,                 \
 102                                  const unsigned char *src,      \
 103                                  unsigned char *dst,            \
 104                                  SilcUInt32 len,                \
 105                                  unsigned char *iv)
 106 #define SILC_CIPHER_API_CONTEXT_LEN(cipher)     \
 107 SilcUInt32 silc_##cipher##_context_len()
 108
 109 /****d* silccrypt/SilcCipherAPI/SilcCipherMode
 110  *
 111  * NAME
 112  *
 113  *    typedef enum { ... } SilcCipherMode;
 114  *
 115  * DESCRIPTION
 116  *
 117  *    Cipher modes.
 118  *
 119  * SOURCE
 120  */
 121 typedef enum {
 122   SILC_CIPHER_MODE_ECB = 1,     /* ECB mode */
 123   SILC_CIPHER_MODE_CBC = 2,     /* CBC mode */
 124   SILC_CIPHER_MODE_CTR = 3,     /* CTR mode */
 125   SILC_CIPHER_MODE_CFB = 4,     /* CFB mode */
 126   SILC_CIPHER_MODE_OFB = 5,     /* OFB mode */
 127 } SilcCipherMode;
 128 /***/
 129
 130 /* Prototypes */
 131
 132 /****f* silccrypt/SilcCipherAPI/silc_cipher_register
 133  *
 134  * SYNOPSIS
 135  *
 136  *    SilcBool silc_cipher_register(const SilcCipherObject *cipher);
 137  *
 138  * DESCRIPTION
 139  *
 140  *    Register a new cipher into SILC. This is used at the initialization of
 141  *    the SILC. This function allocates a new object for the cipher to be
 142  *    registered. Therefore, if memory has been allocated for the object sent
 143  *    as argument it has to be free'd after this function returns succesfully.
 144  *
 145  ***/
 146 SilcBool silc_cipher_register(const SilcCipherObject *cipher);
 147
 148 /****f* silccrypt/SilcCipherAPI/silc_cipher_unregister
 149  *
 150  * SYNOPSIS
 151  *
 152  *    SilcBool silc_cipher_unregister(SilcCipherObject *cipher);
 153  *
 154  * DESCRIPTION
 155  *
 156  *    Unregister a cipher from the SILC.
 157  *
 158  ***/
 159 SilcBool silc_cipher_unregister(SilcCipherObject *cipher);
 160
 161 /****f* silccrypt/SilcCipherAPI/silc_cipher_register_default
 162  *
 163  * SYNOPSIS
 164  *
 165  *    SilcBool silc_cipher_register_default(void);
 166  *
 167  * DESCRIPTION
 168  *
 169  *    Function that registers all the default ciphers (all builtin ciphers).
 170  *    The application may use this to register the default ciphers if specific
 171  *    ciphers in any specific order is not wanted.
 172  *
 173  ***/
 174 SilcBool silc_cipher_register_default(void);
 175
 176 /****f* silccrypt/SilcCipherAPI/silc_cipher_unregister_all
 177  *
 178  * SYNOPSIS
 179  *
 180  *    SilcBool silc_cipher_unregister_all(void);
 181  *
 182  * DESCRIPTION
 183  *
 184  *    Unregisters all ciphers.
 185  *
 186  ***/
 187 SilcBool silc_cipher_unregister_all(void);
 188
 189 /****f* silccrypt/SilcCipherAPI/silc_cipher_alloc
 190  *
 191  * SYNOPSIS
 192  *
 193  *    SilcBool silc_cipher_alloc(const unsigned char *name,
 194  *                           SilcCipher *new_cipher);
 195  *
 196  * DESCRIPTION
 197  *
 198  *    Allocates a new SILC cipher object. Function returns 1 on succes and 0
 199  *    on error. The allocated cipher is returned in new_cipher argument. The
 200  *    caller must set the key to the cipher after this function has returned
 201  *    by calling the ciphers set_key function.
 202  *
 203  ***/
 204 SilcBool silc_cipher_alloc(const unsigned char *name, SilcCipher *new_cipher);
 205
 206 /****f* silccrypt/SilcCipherAPI/silc_cipher_free
 207  *
 208  * SYNOPSIS
 209  *
 210  *    void silc_cipher_free(SilcCipher cipher);
 211  *
 212  * DESCRIPTION
 213  *
 214  *    Frees the given cipher.
 215  *
 216  ***/
 217 void silc_cipher_free(SilcCipher cipher);
 218
 219 /****f* silccrypt/SilcCipherAPI/silc_cipher_is_supported
 220  *
 221  * SYNOPSIS
 222  *
 223  * SilcBool silc_cipher_is_supported(const unsigned char *name);
 224  *
 225  * DESCRIPTION
 226  *
 227  *    Returns TRUE if cipher `name' is supported.
 228  *
 229  ***/
 230 SilcBool silc_cipher_is_supported(const unsigned char *name);
 231
 232 /****f* silccrypt/SilcCipherAPI/silc_cipher_get_supported
 233  *
 234  * SYNOPSIS
 235  *
 236  *    char *silc_cipher_get_supported(void);
 237  *
 238  * DESCRIPTION
 239  *
 240  *    Returns comma separated list of supported ciphers.
 241  *
 242  ***/
 243 char *silc_cipher_get_supported(void);
 244
 245 /****f* silccrypt/SilcCipherAPI/silc_cipher_encrypt
 246  *
 247  * SYNOPSIS
 248  *
 249  *    SilcBool silc_cipher_encrypt(SilcCipher cipher,
 250  *                                 const unsigned char *src,
 251  *                                 unsigned char *dst, SilcUInt32 len,
 252  *                                 unsigned char *iv);
 253  *
 254  * DESCRIPTION
 255  *
 256  *    Encrypts data from `src' into `dst' with the specified cipher and
 257  *    Initial Vector (IV).  If the `iv' is NULL then the cipher's internal
 258  *    IV is used.  The `src' and `dst' maybe same buffer.
 259  *
 260  ***/
 261 SilcBool silc_cipher_encrypt(SilcCipher cipher, const unsigned char *src,
 262                              unsigned char *dst, SilcUInt32 len,
 263                              unsigned char *iv);
 264
 265 /****f* silccrypt/SilcCipherAPI/silc_cipher_decrypt
 266  *
 267  * SYNOPSIS
 268  *
 269  *    SilcBool silc_cipher_decrypt(SilcCipher cipher,
 270  *                                 const unsigned char *src,
 271  *                                 unsigned char *dst, SilcUInt32 len,
 272  *                                 unsigned char *iv);
 273  *
 274  * DESCRIPTION
 275  *
 276  *    Decrypts data from `src' into `dst' with the specified cipher and
 277  *    Initial Vector (IV).  If the `iv' is NULL then the cipher's internal
 278  *    IV is used.  The `src' and `dst' maybe same buffer.
 279  *
 280  ***/
 281 SilcBool silc_cipher_decrypt(SilcCipher cipher, const unsigned char *src,
 282                              unsigned char *dst, SilcUInt32 len,
 283                              unsigned char *iv);
 284
 285 /****f* silccrypt/SilcCipherAPI/silc_cipher_set_key
 286  *
 287  * SYNOPSIS
 288  *
 289  *    SilcBool silc_cipher_set_key(SilcCipher cipher, const unsigned char *key,
 290  *                                 SilcUInt32 keylen, SilcBool encryption);
 291  *
 292  * DESCRIPTION
 293  *
 294  *    Sets the key for the cipher.  The `keylen' is the key length in
 295  *    bits.  If the `encryption' is TRUE the key is for encryption, if FALSE
 296  *    the key is for decryption.
 297  *
 298  ***/
 299 SilcBool silc_cipher_set_key(SilcCipher cipher, const unsigned char *key,
 300                              SilcUInt32 keylen, SilcBool encryption);
 301
 302 /****f* silccrypt/SilcCipherAPI/silc_cipher_set_iv
 303  *
 304  * SYNOPSIS
 305  *
 306  *    void silc_cipher_set_iv(SilcCipher cipher, const unsigned char *iv);
 307  *
 308  * DESCRIPTION
 309  *
 310  *    Sets the IV (initial vector) for the cipher.  The `iv' must be
 311  *    the size of the block size of the cipher.
 312  *
 313  ***/
 314 void silc_cipher_set_iv(SilcCipher cipher, const unsigned char *iv);
 315
 316 /****f* silccrypt/SilcCipherAPI/silc_cipher_get_iv
 317  *
 318  * SYNOPSIS
 319  *
 320  *    unsigned char *silc_cipher_get_iv(SilcCipher cipher);
 321  *
 322  * DESCRIPTION
 323  *
 324  *    Returns the IV (initial vector) of the cipher.  The returned
 325  *    pointer must not be freed by the caller.  If the caller modifies
 326  *    the returned pointer the IV inside cipher is also modified.
 327  *
 328  ***/
 329 unsigned char *silc_cipher_get_iv(SilcCipher cipher);
 330
 331 /****f* silccrypt/SilcCipherAPI/silc_cipher_get_key_len
 332  *
 333  * SYNOPSIS
 334  *
 335  *    SilcUInt32 silc_cipher_get_key_len(SilcCipher cipher);
 336  *
 337  * DESCRIPTION
 338  *
 339  *    Returns the key length of the cipher in bits.
 340  *
 341  ***/
 342 SilcUInt32 silc_cipher_get_key_len(SilcCipher cipher);
 343
 344 /****f* silccrypt/SilcCipherAPI/silc_cipher_get_block_len
 345  *
 346  * SYNOPSIS
 347  *
 348  *    SilcUInt32 silc_cipher_get_block_len(SilcCipher cipher);
 349  *
 350  * DESCRIPTION
 351  *
 352  *    Returns the block size of the cipher in bytes.
 353  *
 354  ***/
 355 SilcUInt32 silc_cipher_get_block_len(SilcCipher cipher);
 356
 357 /****f* silccrypt/SilcCipherAPI/silc_cipher_get_iv_len
 358  *
 359  * SYNOPSIS
 360  *
 361  *    SilcUInt32 silc_cipher_get_iv_len(SilcCipher cipher);
 362  *
 363  * DESCRIPTION
 364  *
 365  *    Returns the IV length of the cipher in bytes.
 366  *
 367  ***/
 368 SilcUInt32 silc_cipher_get_iv_len(SilcCipher cipher);
 369
 370 /****f* silccrypt/SilcCipherAPI/silc_cipher_get_name
 371  *
 372  * SYNOPSIS
 373  *
 374  *    const char *silc_cipher_get_name(SilcCipher cipher);
 375  *
 376  * DESCRIPTION
 377  *
 378  *    Returns the name of the cipher.
 379  *
 380  ***/
 381 const char *silc_cipher_get_name(SilcCipher cipher);
 382
 383 /****f* silccrypt/SilcCipherAPI/silc_cipher_get_mode
 384  *
 385  * SYNOPSIS
 386  *
 387  *    SilcCipherMode silc_cipher_get_mode(SilcCipher cipher);
 388  *
 389  * DESCRIPTION
 390  *
 391  *    Returns the cipher mode.
 392  *
 393  ***/
 394 SilcCipherMode silc_cipher_get_mode(SilcCipher cipher);
 395
 396 #endif /* SILCCIPHER_H */