lib/silccrypt/silccipher.h

   1 /*
   2
   3   silccipher.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 1997 - 2008 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 /****h* silccrypt/SILC Cipher Interface
  21  *
  22  * DESCRIPTION
  23  *
  24  * This is the interface for cipher functions.  It provides cipher
  25  * registering and unregistering routines, encryption and decryption
  26  * routines.
  27  *
  28  ***/
  29
  30 #ifndef SILCCIPHER_H
  31 #define SILCCIPHER_H
  32
  33 /* Forward declarations */
  34 typedef struct SilcCipherObjectStruct SilcCipherObject;
  35
  36 /****s* silccrypt/SilcCipherAPI/SilcCipher
  37  *
  38  * NAME
  39  *
  40  *    typedef struct SilcCipherStruct *SilcCipher;
  41  *
  42  * DESCRIPTION
  43  *
  44  *    This context is the actual cipher context and is allocated
  45  *    by silc_cipher_alloc and given as argument usually to all
  46  *    silc_cipher _* functions.  It is freed by the silc_cipher_free
  47  *    function.
  48  *
  49  ***/
  50 typedef struct SilcCipherStruct *SilcCipher;
  51
  52 /****d* silccrypt/SilcCipherAPI/SilcCipherMode
  53  *
  54  * NAME
  55  *
  56  *    typedef enum { ... } SilcCipherMode;
  57  *
  58  * DESCRIPTION
  59  *
  60  *    Cipher modes.  Notes about cipher modes and implementation:
  61  *
  62  *    SILC_CIPHER_MODE_CBC
  63  *
  64  *      The Cipher-block Chaining mode.  The CBC is mode is a standard CBC
  65  *      mode.  The plaintext length must be multiple by the cipher block size.
  66  *      If it isn't the plaintext must be padded.
  67  *
  68  *    SILC_CIPHER_MODE_CTR
  69  *
  70  *      The Counter mode.  The CTR is normal counter mode.  The CTR mode does
  71  *      not require the plaintext length to be multiple by the cipher block
  72  *      size.  If the last plaintext block is shorter the remaining bits of
  73  *      the key stream are used next time silc_cipher_encrypt is called.  If
  74  *      silc_cipher_set_iv is called it will reset the counter for a new block
  75  *      (discarding any remaining bits from previous key stream).  The counter
  76  *      mode expects MSB first ordered counter.  Note also, the counter is
  77  *      incremented when silc_cipher_encrypt is called for the first time,
  78  *      before encrypting.
  79  *
  80  *    SILC_CIPHER_MODE_CFB
  81  *
  82  *      The Cipher Feedback mode.  The CFB mode is normal cipher feedback mode.
  83  *      The CFB mode does not require the plaintext length to be multiple by
  84  *      the cipher block size.  If the last plaintext block is shorter the
  85  *      remaining bits of the stream are used next time silc_cipher_encrypt is
  86  *      called.  If silc_cipher_set_iv is called it will reset the feedback
  87  *      for a new block (discarding any remaining bits from previous stream).
  88  *
  89  *    SILC_CIPHER_MODE_OFB
  90  *
  91  *      The Output Feedback mode.
  92  *
  93  *    SILC_CIPHER_MODE_ECB
  94  *
  95  *      The Electronic Codebook mode.  This mode does not provide sufficient
  96  *      security and should not be used.
  97  *
  98  *    Each mode modifies the IV (initialization vector) of the cipher when
  99  *    silc_cipher_encrypt or silc_cipher_decrypt is called.  The IV may be
 100  *    set/reset by calling silc_cipher_set_iv and the current IV can be
 101  *    retrieved by calling silc_cipher_get_iv.
 102  *
 103  * SOURCE
 104  */
 105 typedef enum {
 106   SILC_CIPHER_MODE_ECB = 1,     /* ECB mode */
 107   SILC_CIPHER_MODE_CBC = 2,     /* CBC mode */
 108   SILC_CIPHER_MODE_CTR = 3,     /* CTR mode */
 109   SILC_CIPHER_MODE_CFB = 4,     /* CFB mode */
 110   SILC_CIPHER_MODE_OFB = 5,     /* OFB mode */
 111 } SilcCipherMode;
 112 /***/
 113
 114 #define SILC_CIPHER_MAX_IV_SIZE 16              /* Maximum IV size */
 115 #define SILC_DEFAULT_CIPHER "aes-256-cbc"       /* Default cipher */
 116
 117 /* Marks for all ciphers in silc. This can be used in silc_cipher_unregister
 118    to unregister all ciphers at once. */
 119 #define SILC_ALL_CIPHERS ((SilcCipherObject *)1)
 120
 121 #include "silccipher_i.h"
 122
 123 /* Static list of ciphers for silc_cipher_register_default(). */
 124 extern DLLAPI const SilcCipherObject silc_default_ciphers[];
 125
 126 /* Prototypes */
 127
 128 /****f* silccrypt/SilcCipherAPI/silc_cipher_register
 129  *
 130  * SYNOPSIS
 131  *
 132  *    SilcBool silc_cipher_register(const SilcCipherObject *cipher);
 133  *
 134  * DESCRIPTION
 135  *
 136  *    Register a new cipher into SILC. This is used at the initialization of
 137  *    the SILC. This function allocates a new object for the cipher to be
 138  *    registered. Therefore, if memory has been allocated for the object sent
 139  *    as argument it has to be free'd after this function returns succesfully.
 140  *
 141  ***/
 142 SilcBool silc_cipher_register(const SilcCipherObject *cipher);
 143
 144 /****f* silccrypt/SilcCipherAPI/silc_cipher_unregister
 145  *
 146  * SYNOPSIS
 147  *
 148  *    SilcBool silc_cipher_unregister(SilcCipherObject *cipher);
 149  *
 150  * DESCRIPTION
 151  *
 152  *    Unregister a cipher from the SILC.
 153  *
 154  ***/
 155 SilcBool silc_cipher_unregister(SilcCipherObject *cipher);
 156
 157 /****f* silccrypt/SilcCipherAPI/silc_cipher_register_default
 158  *
 159  * SYNOPSIS
 160  *
 161  *    SilcBool silc_cipher_register_default(void);
 162  *
 163  * DESCRIPTION
 164  *
 165  *    Function that registers all the default ciphers (all builtin ciphers).
 166  *    The application may use this to register the default ciphers if specific
 167  *    ciphers in any specific order is not wanted.
 168  *
 169  ***/
 170 SilcBool silc_cipher_register_default(void);
 171
 172 /****f* silccrypt/SilcCipherAPI/silc_cipher_unregister_all
 173  *
 174  * SYNOPSIS
 175  *
 176  *    SilcBool silc_cipher_unregister_all(void);
 177  *
 178  * DESCRIPTION
 179  *
 180  *    Unregisters all ciphers.
 181  *
 182  ***/
 183 SilcBool silc_cipher_unregister_all(void);
 184
 185 /****f* silccrypt/SilcCipherAPI/silc_cipher_alloc
 186  *
 187  * SYNOPSIS
 188  *
 189  *    SilcBool silc_cipher_alloc(const char *name,
 190  *                               SilcCipher *new_cipher);
 191  *
 192  * DESCRIPTION
 193  *
 194  *    Allocates a new SILC cipher object. Function returns TRUE on succes
 195  *    and FALSE on error. The allocated cipher is returned in new_cipher
 196  *    argument. The caller must set the key to the cipher after this
 197  *    function has returned by calling the silc_cipher_set_key.
 198  *
 199  *    The following ciphers are supported:
 200  *
 201  *    aes-256-ctr            AES-256, Counter mode
 202  *    aes-192-ctr            AES-192, Counter mode
 203  *    aes-128-ctr            AES,128, Counter mode
 204  *    aes-256-cbc            AES-256, Cipher block chaining mode
 205  *    aes-192-cbc            AES-192, Cipher block chaining mode
 206  *    aes-128-cbc            AES,128, Cipher block chaining mode
 207  *    twofish-256-cbc        Twofish-256, Cipher block chaining mode
 208  *    twofish-192-cbc        Twofish-192, Cipher block chaining mode
 209  *    twofish-128-cbc        Twofish-128, Cipher block chaining mode
 210  *
 211  *    Notes about modes:
 212  *
 213  ***/
 214 SilcBool silc_cipher_alloc(const char *name, SilcCipher *new_cipher);
 215
 216 /****f* silccrypt/SilcCipherAPI/silc_cipher_alloc
 217  *
 218  * SYNOPSIS
 219  *
 220  *    SilcBool silc_cipher_alloc_full(const char *alg_name,
 221  *                                    SilcUInt32 key_len,
 222  *                                    SilcCipherMode mode,
 223  *                                    SilcCipher *new_cipher);
 224  * DESCRIPTION
 225  *
 226  *    Same as silc_cipher_alloc but takes the cipher algorithm name,
 227  *    key length and mode as separate arguments.
 228  *
 229  ***/
 230 SilcBool silc_cipher_alloc_full(const char *alg_name, SilcUInt32 key_len,
 231                                 SilcCipherMode mode, SilcCipher *new_cipher);
 232
 233 /****f* silccrypt/SilcCipherAPI/silc_cipher_free
 234  *
 235  * SYNOPSIS
 236  *
 237  *    void silc_cipher_free(SilcCipher cipher);
 238  *
 239  * DESCRIPTION
 240  *
 241  *    Frees the given cipher.
 242  *
 243  ***/
 244 void silc_cipher_free(SilcCipher cipher);
 245
 246 /****f* silccrypt/SilcCipherAPI/silc_cipher_is_supported
 247  *
 248  * SYNOPSIS
 249  *
 250  * SilcBool silc_cipher_is_supported(const char *name);
 251  *
 252  * DESCRIPTION
 253  *
 254  *    Returns TRUE if cipher `name' is supported.
 255  *
 256  ***/
 257 SilcBool silc_cipher_is_supported(const char *name);
 258
 259 /****f* silccrypt/SilcCipherAPI/silc_cipher_get_supported
 260  *
 261  * SYNOPSIS
 262  *
 263  *    char *silc_cipher_get_supported(SilcBool only_registered);
 264  *
 265  * DESCRIPTION
 266  *
 267  *    Returns comma separated list of supported ciphers.  If `only_registered'
 268  *    is TRUE only ciphers explicitly registered with silc_cipher_register
 269  *    are returned.  If FALSE, then all registered and default builtin
 270  *    ciphers are returned.  However, if there are no registered ciphers
 271  *    and `only_registered' is TRUE, the builtin ciphers are returned.
 272  *
 273  ***/
 274 char *silc_cipher_get_supported(SilcBool only_registered);
 275
 276 /****f* silccrypt/SilcCipherAPI/silc_cipher_encrypt
 277  *
 278  * SYNOPSIS
 279  *
 280  *    SilcBool silc_cipher_encrypt(SilcCipher cipher,
 281  *                                 const unsigned char *src,
 282  *                                 unsigned char *dst, SilcUInt32 len,
 283  *                                 unsigned char *iv);
 284  *
 285  * DESCRIPTION
 286  *
 287  *    Encrypts data from `src' into `dst' with the specified cipher and
 288  *    Initial Vector (IV).  If the `iv' is NULL then the cipher's internal
 289  *    IV is used.  The `src' and `dst' maybe same buffer.
 290  *
 291  ***/
 292 SilcBool silc_cipher_encrypt(SilcCipher cipher, const unsigned char *src,
 293                              unsigned char *dst, SilcUInt32 len,
 294                              unsigned char *iv);
 295
 296 /****f* silccrypt/SilcCipherAPI/silc_cipher_decrypt
 297  *
 298  * SYNOPSIS
 299  *
 300  *    SilcBool silc_cipher_decrypt(SilcCipher cipher,
 301  *                                 const unsigned char *src,
 302  *                                 unsigned char *dst, SilcUInt32 len,
 303  *                                 unsigned char *iv);
 304  *
 305  * DESCRIPTION
 306  *
 307  *    Decrypts data from `src' into `dst' with the specified cipher and
 308  *    Initial Vector (IV).  If the `iv' is NULL then the cipher's internal
 309  *    IV is used.  The `src' and `dst' maybe same buffer.
 310  *
 311  ***/
 312 SilcBool silc_cipher_decrypt(SilcCipher cipher, const unsigned char *src,
 313                              unsigned char *dst, SilcUInt32 len,
 314                              unsigned char *iv);
 315
 316 /****f* silccrypt/SilcCipherAPI/silc_cipher_set_key
 317  *
 318  * SYNOPSIS
 319  *
 320  *    SilcBool silc_cipher_set_key(SilcCipher cipher, const unsigned char *key,
 321  *                                 SilcUInt32 bit_keylen, SilcBool encryption);
 322  *
 323  * DESCRIPTION
 324  *
 325  *    Sets the key for the cipher.  The `keylen' is the key length in
 326  *    bits.  If the `encryption' is TRUE the key is for encryption, if FALSE
 327  *    the key is for decryption.
 328  *
 329  ***/
 330 SilcBool silc_cipher_set_key(SilcCipher cipher, const unsigned char *key,
 331                              SilcUInt32 bit_keylen, SilcBool encryption);
 332
 333 /****f* silccrypt/SilcCipherAPI/silc_cipher_set_iv
 334  *
 335  * SYNOPSIS
 336  *
 337  *    void silc_cipher_set_iv(SilcCipher cipher, const unsigned char *iv);
 338  *
 339  * DESCRIPTION
 340  *
 341  *    Sets the IV (initialization vector) for the cipher.  The `iv' must be
 342  *    the size of the block size of the cipher.  If `iv' is NULL this
 343  *    does not do anything.
 344  *
 345  *    If the encryption mode is CTR (Counter mode) this also resets the
 346  *    the counter for a new block.  This is done also if `iv' is NULL.
 347  *
 348  *    If the encryption mode is CFB (cipher feedback) this also resets the
 349  *    the feedback stream for a new block.  This is done also if `iv' is NULL.
 350  *
 351  ***/
 352 void silc_cipher_set_iv(SilcCipher cipher, const unsigned char *iv);
 353
 354 /****f* silccrypt/SilcCipherAPI/silc_cipher_get_iv
 355  *
 356  * SYNOPSIS
 357  *
 358  *    unsigned char *silc_cipher_get_iv(SilcCipher cipher);
 359  *
 360  * DESCRIPTION
 361  *
 362  *    Returns the IV (initial vector) of the cipher.  The returned
 363  *    pointer must not be freed by the caller.  If the caller modifies
 364  *    the returned pointer the IV inside cipher is also modified.
 365  *
 366  ***/
 367 unsigned char *silc_cipher_get_iv(SilcCipher cipher);
 368
 369 /****f* silccrypt/SilcCipherAPI/silc_cipher_get_key_len
 370  *
 371  * SYNOPSIS
 372  *
 373  *    SilcUInt32 silc_cipher_get_key_len(SilcCipher cipher);
 374  *
 375  * DESCRIPTION
 376  *
 377  *    Returns the key length of the cipher in bits.
 378  *
 379  ***/
 380 SilcUInt32 silc_cipher_get_key_len(SilcCipher cipher);
 381
 382 /****f* silccrypt/SilcCipherAPI/silc_cipher_get_block_len
 383  *
 384  * SYNOPSIS
 385  *
 386  *    SilcUInt32 silc_cipher_get_block_len(SilcCipher cipher);
 387  *
 388  * DESCRIPTION
 389  *
 390  *    Returns the block size of the cipher in bytes.
 391  *
 392  ***/
 393 SilcUInt32 silc_cipher_get_block_len(SilcCipher cipher);
 394
 395 /****f* silccrypt/SilcCipherAPI/silc_cipher_get_iv_len
 396  *
 397  * SYNOPSIS
 398  *
 399  *    SilcUInt32 silc_cipher_get_iv_len(SilcCipher cipher);
 400  *
 401  * DESCRIPTION
 402  *
 403  *    Returns the IV length of the cipher in bytes.
 404  *
 405  ***/
 406 SilcUInt32 silc_cipher_get_iv_len(SilcCipher cipher);
 407
 408 /****f* silccrypt/SilcCipherAPI/silc_cipher_get_name
 409  *
 410  * SYNOPSIS
 411  *
 412  *    const char *silc_cipher_get_name(SilcCipher cipher);
 413  *
 414  * DESCRIPTION
 415  *
 416  *    Returns the full name of the cipher (eg. 'aes-256-ctr').
 417  *
 418  ***/
 419 const char *silc_cipher_get_name(SilcCipher cipher);
 420
 421 /****f* silccrypt/SilcCipherAPI/silc_cipher_get_alg_name
 422  *
 423  * SYNOPSIS
 424  *
 425  *    const char *silc_cipher_get_alg_name(SilcCipher cipher);
 426  *
 427  * DESCRIPTION
 428  *
 429  *    Returns the algorithm name of the cipher (eg. 'aes').
 430  *
 431  ***/
 432 const char *silc_cipher_get_alg_name(SilcCipher cipher);
 433
 434 /****f* silccrypt/SilcCipherAPI/silc_cipher_get_mode
 435  *
 436  * SYNOPSIS
 437  *
 438  *    SilcCipherMode silc_cipher_get_mode(SilcCipher cipher);
 439  *
 440  * DESCRIPTION
 441  *
 442  *    Returns the cipher mode.
 443  *
 444  ***/
 445 SilcCipherMode silc_cipher_get_mode(SilcCipher cipher);
 446
 447 #endif /* SILCCIPHER_H */