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 1 on succes and 0
 195  *    on error. The allocated cipher is returned in new_cipher argument. The
 196  *    caller must set the key to the cipher after this function has returned
 197  *    by calling the ciphers set_key function.
 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_free
 217  *
 218  * SYNOPSIS
 219  *
 220  *    void silc_cipher_free(SilcCipher cipher);
 221  *
 222  * DESCRIPTION
 223  *
 224  *    Frees the given cipher.
 225  *
 226  ***/
 227 void silc_cipher_free(SilcCipher cipher);
 228
 229 /****f* silccrypt/SilcCipherAPI/silc_cipher_is_supported
 230  *
 231  * SYNOPSIS
 232  *
 233  * SilcBool silc_cipher_is_supported(const char *name);
 234  *
 235  * DESCRIPTION
 236  *
 237  *    Returns TRUE if cipher `name' is supported.
 238  *
 239  ***/
 240 SilcBool silc_cipher_is_supported(const char *name);
 241
 242 /****f* silccrypt/SilcCipherAPI/silc_cipher_get_supported
 243  *
 244  * SYNOPSIS
 245  *
 246  *    char *silc_cipher_get_supported(SilcBool only_registered);
 247  *
 248  * DESCRIPTION
 249  *
 250  *    Returns comma separated list of supported ciphers.  If `only_registered'
 251  *    is TRUE only ciphers explicitly registered with silc_cipher_register
 252  *    are returned.  If FALSE, then all registered and default builtin
 253  *    ciphers are returned.  However, if there are no registered ciphers
 254  *    and `only_registered' is TRUE, the builtin ciphers are returned.
 255  *
 256  ***/
 257 char *silc_cipher_get_supported(SilcBool only_registered);
 258
 259 /****f* silccrypt/SilcCipherAPI/silc_cipher_encrypt
 260  *
 261  * SYNOPSIS
 262  *
 263  *    SilcBool silc_cipher_encrypt(SilcCipher cipher,
 264  *                                 const unsigned char *src,
 265  *                                 unsigned char *dst, SilcUInt32 len,
 266  *                                 unsigned char *iv);
 267  *
 268  * DESCRIPTION
 269  *
 270  *    Encrypts data from `src' into `dst' with the specified cipher and
 271  *    Initial Vector (IV).  If the `iv' is NULL then the cipher's internal
 272  *    IV is used.  The `src' and `dst' maybe same buffer.
 273  *
 274  ***/
 275 SilcBool silc_cipher_encrypt(SilcCipher cipher, const unsigned char *src,
 276                              unsigned char *dst, SilcUInt32 len,
 277                              unsigned char *iv);
 278
 279 /****f* silccrypt/SilcCipherAPI/silc_cipher_decrypt
 280  *
 281  * SYNOPSIS
 282  *
 283  *    SilcBool silc_cipher_decrypt(SilcCipher cipher,
 284  *                                 const unsigned char *src,
 285  *                                 unsigned char *dst, SilcUInt32 len,
 286  *                                 unsigned char *iv);
 287  *
 288  * DESCRIPTION
 289  *
 290  *    Decrypts data from `src' into `dst' with the specified cipher and
 291  *    Initial Vector (IV).  If the `iv' is NULL then the cipher's internal
 292  *    IV is used.  The `src' and `dst' maybe same buffer.
 293  *
 294  ***/
 295 SilcBool silc_cipher_decrypt(SilcCipher cipher, const unsigned char *src,
 296                              unsigned char *dst, SilcUInt32 len,
 297                              unsigned char *iv);
 298
 299 /****f* silccrypt/SilcCipherAPI/silc_cipher_set_key
 300  *
 301  * SYNOPSIS
 302  *
 303  *    SilcBool silc_cipher_set_key(SilcCipher cipher, const unsigned char *key,
 304  *                                 SilcUInt32 bit_keylen, SilcBool encryption);
 305  *
 306  * DESCRIPTION
 307  *
 308  *    Sets the key for the cipher.  The `keylen' is the key length in
 309  *    bits.  If the `encryption' is TRUE the key is for encryption, if FALSE
 310  *    the key is for decryption.
 311  *
 312  ***/
 313 SilcBool silc_cipher_set_key(SilcCipher cipher, const unsigned char *key,
 314                              SilcUInt32 bit_keylen, SilcBool encryption);
 315
 316 /****f* silccrypt/SilcCipherAPI/silc_cipher_set_iv
 317  *
 318  * SYNOPSIS
 319  *
 320  *    void silc_cipher_set_iv(SilcCipher cipher, const unsigned char *iv);
 321  *
 322  * DESCRIPTION
 323  *
 324  *    Sets the IV (initialization vector) for the cipher.  The `iv' must be
 325  *    the size of the block size of the cipher.  If `iv' is NULL this
 326  *    does not do anything.
 327  *
 328  *    If the encryption mode is CTR (Counter mode) this also resets the
 329  *    the counter for a new block.  This is done also if `iv' is NULL.
 330  *
 331  *    If the encryption mode is CFB (cipher feedback) this also resets the
 332  *    the feedback stream for a new block.  This is done also if `iv' is NULL.
 333  *
 334  ***/
 335 void silc_cipher_set_iv(SilcCipher cipher, const unsigned char *iv);
 336
 337 /****f* silccrypt/SilcCipherAPI/silc_cipher_get_iv
 338  *
 339  * SYNOPSIS
 340  *
 341  *    unsigned char *silc_cipher_get_iv(SilcCipher cipher);
 342  *
 343  * DESCRIPTION
 344  *
 345  *    Returns the IV (initial vector) of the cipher.  The returned
 346  *    pointer must not be freed by the caller.  If the caller modifies
 347  *    the returned pointer the IV inside cipher is also modified.
 348  *
 349  ***/
 350 unsigned char *silc_cipher_get_iv(SilcCipher cipher);
 351
 352 /****f* silccrypt/SilcCipherAPI/silc_cipher_get_key_len
 353  *
 354  * SYNOPSIS
 355  *
 356  *    SilcUInt32 silc_cipher_get_key_len(SilcCipher cipher);
 357  *
 358  * DESCRIPTION
 359  *
 360  *    Returns the key length of the cipher in bits.
 361  *
 362  ***/
 363 SilcUInt32 silc_cipher_get_key_len(SilcCipher cipher);
 364
 365 /****f* silccrypt/SilcCipherAPI/silc_cipher_get_block_len
 366  *
 367  * SYNOPSIS
 368  *
 369  *    SilcUInt32 silc_cipher_get_block_len(SilcCipher cipher);
 370  *
 371  * DESCRIPTION
 372  *
 373  *    Returns the block size of the cipher in bytes.
 374  *
 375  ***/
 376 SilcUInt32 silc_cipher_get_block_len(SilcCipher cipher);
 377
 378 /****f* silccrypt/SilcCipherAPI/silc_cipher_get_iv_len
 379  *
 380  * SYNOPSIS
 381  *
 382  *    SilcUInt32 silc_cipher_get_iv_len(SilcCipher cipher);
 383  *
 384  * DESCRIPTION
 385  *
 386  *    Returns the IV length of the cipher in bytes.
 387  *
 388  ***/
 389 SilcUInt32 silc_cipher_get_iv_len(SilcCipher cipher);
 390
 391 /****f* silccrypt/SilcCipherAPI/silc_cipher_get_name
 392  *
 393  * SYNOPSIS
 394  *
 395  *    const char *silc_cipher_get_name(SilcCipher cipher);
 396  *
 397  * DESCRIPTION
 398  *
 399  *    Returns the name of the cipher.
 400  *
 401  ***/
 402 const char *silc_cipher_get_name(SilcCipher cipher);
 403
 404 /****f* silccrypt/SilcCipherAPI/silc_cipher_get_mode
 405  *
 406  * SYNOPSIS
 407  *
 408  *    SilcCipherMode silc_cipher_get_mode(SilcCipher cipher);
 409  *
 410  * DESCRIPTION
 411  *
 412  *    Returns the cipher mode.
 413  *
 414  ***/
 415 SilcCipherMode silc_cipher_get_mode(SilcCipher cipher);
 416
 417 #endif /* SILCCIPHER_H */