lib/silccrypt/silccipher.h

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