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 /****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  * SOURCE
  99  */
 100 typedef enum {
 101   SILC_CIPHER_MODE_ECB = 1,     /* ECB mode */
 102   SILC_CIPHER_MODE_CBC = 2,     /* CBC mode */
 103   SILC_CIPHER_MODE_CTR = 3,     /* CTR mode */
 104   SILC_CIPHER_MODE_CFB = 4,     /* CFB mode */
 105   SILC_CIPHER_MODE_OFB = 5,     /* OFB mode */
 106 } SilcCipherMode;
 107 /***/
 108
 109 #define SILC_CIPHER_MAX_IV_SIZE 16              /* Maximum IV size */
 110 #define SILC_DEFAULT_CIPHER "aes-256-cbc"       /* Default cipher */
 111
 112 /* Marks for all ciphers in silc. This can be used in silc_cipher_unregister
 113    to unregister all ciphers at once. */
 114 #define SILC_ALL_CIPHERS ((SilcCipherObject *)1)
 115
 116 #include "silccipher_i.h"
 117
 118 /* Static list of ciphers for silc_cipher_register_default(). */
 119 extern DLLAPI const SilcCipherObject silc_default_ciphers[];
 120
 121 /* Prototypes */
 122
 123 /****f* silccrypt/SilcCipherAPI/silc_cipher_register
 124  *
 125  * SYNOPSIS
 126  *
 127  *    SilcBool silc_cipher_register(const SilcCipherObject *cipher);
 128  *
 129  * DESCRIPTION
 130  *
 131  *    Register a new cipher into SILC. This is used at the initialization of
 132  *    the SILC. This function allocates a new object for the cipher to be
 133  *    registered. Therefore, if memory has been allocated for the object sent
 134  *    as argument it has to be free'd after this function returns succesfully.
 135  *
 136  ***/
 137 SilcBool silc_cipher_register(const SilcCipherObject *cipher);
 138
 139 /****f* silccrypt/SilcCipherAPI/silc_cipher_unregister
 140  *
 141  * SYNOPSIS
 142  *
 143  *    SilcBool silc_cipher_unregister(SilcCipherObject *cipher);
 144  *
 145  * DESCRIPTION
 146  *
 147  *    Unregister a cipher from the SILC.
 148  *
 149  ***/
 150 SilcBool silc_cipher_unregister(SilcCipherObject *cipher);
 151
 152 /****f* silccrypt/SilcCipherAPI/silc_cipher_register_default
 153  *
 154  * SYNOPSIS
 155  *
 156  *    SilcBool silc_cipher_register_default(void);
 157  *
 158  * DESCRIPTION
 159  *
 160  *    Function that registers all the default ciphers (all builtin ciphers).
 161  *    The application may use this to register the default ciphers if specific
 162  *    ciphers in any specific order is not wanted.
 163  *
 164  ***/
 165 SilcBool silc_cipher_register_default(void);
 166
 167 /****f* silccrypt/SilcCipherAPI/silc_cipher_unregister_all
 168  *
 169  * SYNOPSIS
 170  *
 171  *    SilcBool silc_cipher_unregister_all(void);
 172  *
 173  * DESCRIPTION
 174  *
 175  *    Unregisters all ciphers.
 176  *
 177  ***/
 178 SilcBool silc_cipher_unregister_all(void);
 179
 180 /****f* silccrypt/SilcCipherAPI/silc_cipher_alloc
 181  *
 182  * SYNOPSIS
 183  *
 184  *    SilcBool silc_cipher_alloc(const unsigned char *name,
 185  *                               SilcCipher *new_cipher);
 186  *
 187  * DESCRIPTION
 188  *
 189  *    Allocates a new SILC cipher object. Function returns 1 on succes and 0
 190  *    on error. The allocated cipher is returned in new_cipher argument. The
 191  *    caller must set the key to the cipher after this function has returned
 192  *    by calling the ciphers set_key function.
 193  *
 194  *    The following ciphers are supported:
 195  *
 196  *    aes-256-ctr            AES-256, Counter mode
 197  *    aes-192-ctr            AES-192, Counter mode
 198  *    aes-128-ctr            AES,128, Counter mode
 199  *    aes-256-cbc            AES-256, Cipher block chaining mode
 200  *    aes-192-cbc            AES-192, Cipher block chaining mode
 201  *    aes-128-cbc            AES,128, Cipher block chaining mode
 202  *    twofish-256-cbc        Twofish-256, Cipher block chaining mode
 203  *    twofish-192-cbc        Twofish-192, Cipher block chaining mode
 204  *    twofish-128-cbc        Twofish-128, Cipher block chaining mode
 205  *
 206  *    Notes about modes:
 207  *
 208  ***/
 209 SilcBool silc_cipher_alloc(const unsigned char *name, SilcCipher *new_cipher);
 210
 211 /****f* silccrypt/SilcCipherAPI/silc_cipher_free
 212  *
 213  * SYNOPSIS
 214  *
 215  *    void silc_cipher_free(SilcCipher cipher);
 216  *
 217  * DESCRIPTION
 218  *
 219  *    Frees the given cipher.
 220  *
 221  ***/
 222 void silc_cipher_free(SilcCipher cipher);
 223
 224 /****f* silccrypt/SilcCipherAPI/silc_cipher_is_supported
 225  *
 226  * SYNOPSIS
 227  *
 228  * SilcBool silc_cipher_is_supported(const unsigned char *name);
 229  *
 230  * DESCRIPTION
 231  *
 232  *    Returns TRUE if cipher `name' is supported.
 233  *
 234  ***/
 235 SilcBool silc_cipher_is_supported(const unsigned char *name);
 236
 237 /****f* silccrypt/SilcCipherAPI/silc_cipher_get_supported
 238  *
 239  * SYNOPSIS
 240  *
 241  *    char *silc_cipher_get_supported(SilcBool only_registered);
 242  *
 243  * DESCRIPTION
 244  *
 245  *    Returns comma separated list of supported ciphers.  If `only_registered'
 246  *    is TRUE only ciphers explicitly registered with silc_cipher_register
 247  *    are returned.  If FALSE, then all registered and default builtin
 248  *    ciphers are returned.  However, if there are no registered ciphers
 249  *    and `only_registered' is TRUE, the builtin ciphers are returned.
 250  *
 251  ***/
 252 char *silc_cipher_get_supported(SilcBool only_registered);
 253
 254 /****f* silccrypt/SilcCipherAPI/silc_cipher_encrypt
 255  *
 256  * SYNOPSIS
 257  *
 258  *    SilcBool silc_cipher_encrypt(SilcCipher cipher,
 259  *                                 const unsigned char *src,
 260  *                                 unsigned char *dst, SilcUInt32 len,
 261  *                                 unsigned char *iv);
 262  *
 263  * DESCRIPTION
 264  *
 265  *    Encrypts data from `src' into `dst' with the specified cipher and
 266  *    Initial Vector (IV).  If the `iv' is NULL then the cipher's internal
 267  *    IV is used.  The `src' and `dst' maybe same buffer.
 268  *
 269  ***/
 270 SilcBool silc_cipher_encrypt(SilcCipher cipher, const unsigned char *src,
 271                              unsigned char *dst, SilcUInt32 len,
 272                              unsigned char *iv);
 273
 274 /****f* silccrypt/SilcCipherAPI/silc_cipher_decrypt
 275  *
 276  * SYNOPSIS
 277  *
 278  *    SilcBool silc_cipher_decrypt(SilcCipher cipher,
 279  *                                 const unsigned char *src,
 280  *                                 unsigned char *dst, SilcUInt32 len,
 281  *                                 unsigned char *iv);
 282  *
 283  * DESCRIPTION
 284  *
 285  *    Decrypts 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_decrypt(SilcCipher cipher, const unsigned char *src,
 291                              unsigned char *dst, SilcUInt32 len,
 292                              unsigned char *iv);
 293
 294 /****f* silccrypt/SilcCipherAPI/silc_cipher_set_key
 295  *
 296  * SYNOPSIS
 297  *
 298  *    SilcBool silc_cipher_set_key(SilcCipher cipher, const unsigned char *key,
 299  *                                 SilcUInt32 keylen, SilcBool encryption);
 300  *
 301  * DESCRIPTION
 302  *
 303  *    Sets the key for the cipher.  The `keylen' is the key length in
 304  *    bits.  If the `encryption' is TRUE the key is for encryption, if FALSE
 305  *    the key is for decryption.
 306  *
 307  ***/
 308 SilcBool silc_cipher_set_key(SilcCipher cipher, const unsigned char *key,
 309                              SilcUInt32 keylen, SilcBool encryption);
 310
 311 /****f* silccrypt/SilcCipherAPI/silc_cipher_set_iv
 312  *
 313  * SYNOPSIS
 314  *
 315  *    void silc_cipher_set_iv(SilcCipher cipher, const unsigned char *iv);
 316  *
 317  * DESCRIPTION
 318  *
 319  *    Sets the IV (initial vector) for the cipher.  The `iv' must be
 320  *    the size of the block size of the cipher.  If `iv' is NULL this
 321  *    does not do anything.
 322  *
 323  *    If the encryption mode is CTR (Counter mode) this also resets the
 324  *    the counter for a new block.  This is done also if `iv' is NULL.
 325  *
 326  ***/
 327 void silc_cipher_set_iv(SilcCipher cipher, const unsigned char *iv);
 328
 329 /****f* silccrypt/SilcCipherAPI/silc_cipher_get_iv
 330  *
 331  * SYNOPSIS
 332  *
 333  *    unsigned char *silc_cipher_get_iv(SilcCipher cipher);
 334  *
 335  * DESCRIPTION
 336  *
 337  *    Returns the IV (initial vector) of the cipher.  The returned
 338  *    pointer must not be freed by the caller.  If the caller modifies
 339  *    the returned pointer the IV inside cipher is also modified.
 340  *
 341  ***/
 342 unsigned char *silc_cipher_get_iv(SilcCipher cipher);
 343
 344 /****f* silccrypt/SilcCipherAPI/silc_cipher_get_key_len
 345  *
 346  * SYNOPSIS
 347  *
 348  *    SilcUInt32 silc_cipher_get_key_len(SilcCipher cipher);
 349  *
 350  * DESCRIPTION
 351  *
 352  *    Returns the key length of the cipher in bits.
 353  *
 354  ***/
 355 SilcUInt32 silc_cipher_get_key_len(SilcCipher cipher);
 356
 357 /****f* silccrypt/SilcCipherAPI/silc_cipher_get_block_len
 358  *
 359  * SYNOPSIS
 360  *
 361  *    SilcUInt32 silc_cipher_get_block_len(SilcCipher cipher);
 362  *
 363  * DESCRIPTION
 364  *
 365  *    Returns the block size of the cipher in bytes.
 366  *
 367  ***/
 368 SilcUInt32 silc_cipher_get_block_len(SilcCipher cipher);
 369
 370 /****f* silccrypt/SilcCipherAPI/silc_cipher_get_iv_len
 371  *
 372  * SYNOPSIS
 373  *
 374  *    SilcUInt32 silc_cipher_get_iv_len(SilcCipher cipher);
 375  *
 376  * DESCRIPTION
 377  *
 378  *    Returns the IV length of the cipher in bytes.
 379  *
 380  ***/
 381 SilcUInt32 silc_cipher_get_iv_len(SilcCipher cipher);
 382
 383 /****f* silccrypt/SilcCipherAPI/silc_cipher_get_name
 384  *
 385  * SYNOPSIS
 386  *
 387  *    const char *silc_cipher_get_name(SilcCipher cipher);
 388  *
 389  * DESCRIPTION
 390  *
 391  *    Returns the name of the cipher.
 392  *
 393  ***/
 394 const char *silc_cipher_get_name(SilcCipher cipher);
 395
 396 /****f* silccrypt/SilcCipherAPI/silc_cipher_get_mode
 397  *
 398  * SYNOPSIS
 399  *
 400  *    SilcCipherMode silc_cipher_get_mode(SilcCipher cipher);
 401  *
 402  * DESCRIPTION
 403  *
 404  *    Returns the cipher mode.
 405  *
 406  ***/
 407 SilcCipherMode silc_cipher_get_mode(SilcCipher cipher);
 408
 409 #endif /* SILCCIPHER_H */