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/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/Ciphers
  53  *
  54  * NAME
  55  *
  56  *    Ciphers
  57  *
  58  * DESCRIPTION
  59  *
  60  *    Supported ciphers names.  These names can be given as argument
  61  *    to silc_cipher_alloc.
  62  *
  63  * SOURCE
  64  */
  65
  66 /* AES in CTR mode, in different key lengths */
  67 #define SILC_CIPHER_AES_256_CTR          "aes-256-ctr"
  68 #define SILC_CIPHER_AES_192_CTR          "aes-192-ctr"
  69 #define SILC_CIPHER_AES_128_CTR          "aes-128-ctr"
  70
  71 /* AES in CBC mode, in different key lengths */
  72 #define SILC_CIPHER_AES_256_CBC          "aes-256-cbc"
  73 #define SILC_CIPHER_AES_192_CBC          "aes-192-cbc"
  74 #define SILC_CIPHER_AES_128_CBC          "aes-128-cbc"
  75
  76 /* AES in CFB mode, in different key lengths */
  77 #define SILC_CIPHER_AES_256_CFB          "aes-256-cfb"
  78 #define SILC_CIPHER_AES_192_CFB          "aes-192-cfb"
  79 #define SILC_CIPHER_AES_128_CFB          "aes-128-cfb"
  80
  81 /* AES in ECB mode, in different key lengths */
  82 #define SILC_CIPHER_AES_256_ECB          "aes-256-ecb"
  83 #define SILC_CIPHER_AES_192_ECB          "aes-192-ecb"
  84 #define SILC_CIPHER_AES_128_ECB          "aes-128-ecb"
  85
  86 /* Twofish in CTR mode, in different key lengths */
  87 #define SILC_CIPHER_TWOFISH_256_CTR      "twofish-256-ctr"
  88 #define SILC_CIPHER_TWOFISH_192_CTR      "twofish-192-ctr"
  89 #define SILC_CIPHER_TWOFISH_128_CTR      "twofish-128-ctr"
  90
  91 /* Twofish in CBC mode, in different key lengths */
  92 #define SILC_CIPHER_TWOFISH_256_CBC      "twofish-256-cbc"
  93 #define SILC_CIPHER_TWOFISH_192_CBC      "twofish-192-cbc"
  94 #define SILC_CIPHER_TWOFISH_128_CBC      "twofish-128-cbc"
  95
  96 /* Twofish in CFB mode, in different key lengths */
  97 #define SILC_CIPHER_TWOFISH_256_CFB      "twofish-256-cfb"
  98 #define SILC_CIPHER_TWOFISH_192_CFB      "twofish-192-cfb"
  99 #define SILC_CIPHER_TWOFISH_128_CFB      "twofish-128-cfb"
 100
 101 /* Twofish in ECB mode, in different key lengths */
 102 #define SILC_CIPHER_TWOFISH_256_ECB      "twofish-256-ecb"
 103 #define SILC_CIPHER_TWOFISH_192_ECB      "twofish-192-ecb"
 104 #define SILC_CIPHER_TWOFISH_128_ECB      "twofish-128-ecb"
 105
 106 /* CAST-128 in CTR, CBC, CFB, ECB modes, 128-bit key length */
 107 #define SILC_CIPHER_CAST5_128_CTR        "cast5-128-ctr"
 108 #define SILC_CIPHER_CAST5_128_CBC        "cast5-128-cbc"
 109 #define SILC_CIPHER_CAST5_128_CFB        "cast5-128-cfb"
 110 #define SILC_CIPHER_CAST5_128_ECB        "cast5-128-ecb"
 111
 112 /* DES in CTR, CBC, CFB, ECB modes, 56-bit key length */
 113 #define SILC_CIPHER_DES_56_CTR           "des-56-ctr"
 114 #define SILC_CIPHER_DES_56_CBC           "des-56-cbc"
 115 #define SILC_CIPHER_DES_56_CFB           "des-56-cfb"
 116 #define SILC_CIPHER_DES_56_ECB           "des-56-ecb"
 117
 118 /* 3DES in CTR, CBC, CFB, ECB modes, 168-bit (192-bit) key length */
 119 #define SILC_CIPHER_3DES_168_CTR         "3des-168-ctr"
 120 #define SILC_CIPHER_3DES_168_CBC         "3des-168-cbc"
 121 #define SILC_CIPHER_3DES_168_CFB         "3des-168-cfb"
 122 #define SILC_CIPHER_3DES_168_ECB         "3des-168-ecb"
 123
 124 /* No encryption */
 125 #define SILC_CIPHER_NONE                 "none"
 126 /***/
 127
 128 /****d* silccrypt/Cipher Algorithms
 129  *
 130  * NAME
 131  *
 132  *    Cipher Algorithms
 133  *
 134  * DESCRIPTION
 135  *
 136  *    Supported cipher algorithm names.  These names can be give as argument
 137  *    to silc_cipher_alloc_full.
 138  *
 139  * SOURCE
 140  */
 141 #define SILC_CIPHER_AES      "aes"                 /* AES */
 142 #define SILC_CIPHER_TWOFISH  "twofish"             /* Twofish */
 143 #define SILC_CIPHER_CAST5    "cast5"               /* CAST-128 */
 144 #define SILC_CIPHER_DES      "des"                 /* DES */
 145 #define SILC_CIPHER_3DES     "3des"                /* Triple-DES */
 146 /***/
 147
 148 /****d* silccrypt/SilcCipherMode
 149  *
 150  * NAME
 151  *
 152  *    typedef enum { ... } SilcCipherMode;
 153  *
 154  * DESCRIPTION
 155  *
 156  *    Cipher modes.  Notes about cipher modes and implementation:
 157  *
 158  *    SILC_CIPHER_MODE_CBC
 159  *
 160  *      The Cipher-block Chaining mode.  The plaintext length must be
 161  *      multiple by the cipher block size.  If it isn't the plaintext must
 162  *      be padded.
 163  *
 164  *    SILC_CIPHER_MODE_CTR
 165  *
 166  *      The Counter mode.  The CTR mode does not require the plaintext length
 167  *      to be multiple by the cipher block size.  If the last plaintext block
 168  *      is shorter the remaining bits of the key stream are used next time
 169  *      silc_cipher_encrypt is called.  If silc_cipher_set_iv is called it
 170  *      will reset the counter for a new block (discarding any remaining
 171  *      bits from previous key stream).  The CTR mode expects MSB first
 172  *      ordered counter.  Note also, the counter is incremented when
 173  *      silc_cipher_encrypt is called for the first time, before encrypting.
 174  *
 175  *    SILC_CIPHER_MODE_CFB
 176  *
 177  *      The Cipher Feedback mode.  The CFB mode does not require the plaintext
 178  *      length to be multiple by the cipher block size.  If the last plaintext
 179  *      block is shorter the remaining bits of the stream are used next time
 180  *      silc_cipher_encrypt is called.  If silc_cipher_set_iv is called it
 181  *      will reset the feedback for a new block (discarding any remaining
 182  *      bits from previous stream).
 183  *
 184  *    SILC_CIPHER_MODE_OFB
 185  *
 186  *      The Output Feedback mode.
 187  *
 188  *    SILC_CIPHER_MODE_ECB
 189  *
 190  *      The Electronic Codebook mode.  This mode does not provide sufficient
 191  *      security and should not be used alone.
 192  *
 193  *    Each mode using and IV (initialization vector) modifies the IV of the
 194  *    cipher when silc_cipher_encrypt or silc_cipher_decrypt is called.  The
 195  *    IV may be set/reset by calling silc_cipher_set_iv and the current IV
 196  *    can be retrieved by calling silc_cipher_get_iv.
 197  *
 198  * SOURCE
 199  */
 200 typedef enum {
 201   SILC_CIPHER_MODE_ECB = 1,     /* ECB mode */
 202   SILC_CIPHER_MODE_CBC = 2,     /* CBC mode */
 203   SILC_CIPHER_MODE_CTR = 3,     /* CTR mode */
 204   SILC_CIPHER_MODE_CFB = 4,     /* CFB mode */
 205   SILC_CIPHER_MODE_OFB = 5,     /* OFB mode */
 206 } SilcCipherMode;
 207 /***/
 208
 209 #define SILC_CIPHER_MAX_IV_SIZE 16              /* Maximum IV size */
 210
 211 /* Marks for all ciphers in silc. This can be used in silc_cipher_unregister
 212    to unregister all ciphers at once. */
 213 #define SILC_ALL_CIPHERS ((SilcCipherObject *)1)
 214
 215 #include "silccipher_i.h"
 216
 217 /* Static list of ciphers for silc_cipher_register_default(). */
 218 extern DLLAPI const SilcCipherObject silc_default_ciphers[];
 219
 220 /* Prototypes */
 221
 222 /****f* silccrypt/silc_cipher_register
 223  *
 224  * SYNOPSIS
 225  *
 226  *    SilcBool silc_cipher_register(const SilcCipherObject *cipher);
 227  *
 228  * DESCRIPTION
 229  *
 230  *    Register a new cipher into SILC. This can be used at the initialization
 231  *    of an applicatio.  Usually this function is not needed.  The default
 232  *    ciphers are automatically registered.  This can be used to change the
 233  *    order of the registered ciphers by re-registering them in desired order,
 234  *    or add new ciphers.
 235  *
 236  ***/
 237 SilcBool silc_cipher_register(const SilcCipherObject *cipher);
 238
 239 /****f* silccrypt/silc_cipher_unregister
 240  *
 241  * SYNOPSIS
 242  *
 243  *    SilcBool silc_cipher_unregister(SilcCipherObject *cipher);
 244  *
 245  * DESCRIPTION
 246  *
 247  *    Unregister a cipher from the SILC.
 248  *
 249  ***/
 250 SilcBool silc_cipher_unregister(SilcCipherObject *cipher);
 251
 252 /****f* silccrypt/silc_cipher_register_default
 253  *
 254  * SYNOPSIS
 255  *
 256  *    SilcBool silc_cipher_register_default(void);
 257  *
 258  * DESCRIPTION
 259  *
 260  *    Function that registers all the default ciphers (all builtin ciphers).
 261  *    Application need not call this directly.  By calling silc_crypto_init
 262  *    this function is called.
 263  *
 264  ***/
 265 SilcBool silc_cipher_register_default(void);
 266
 267 /****f* silccrypt/silc_cipher_unregister_all
 268  *
 269  * SYNOPSIS
 270  *
 271  *    SilcBool silc_cipher_unregister_all(void);
 272  *
 273  * DESCRIPTION
 274  *
 275  *    Unregisters all ciphers.  Application need not call this directly.
 276  *    By calling silc_crypto_init this function is called.
 277  *
 278  ***/
 279 SilcBool silc_cipher_unregister_all(void);
 280
 281 /****f* silccrypt/silc_cipher_alloc
 282  *
 283  * SYNOPSIS
 284  *
 285  *    SilcBool silc_cipher_alloc(const char *name,
 286  *                               SilcCipher *new_cipher);
 287  *
 288  * DESCRIPTION
 289  *
 290  *    Allocates a new SILC cipher object. Function returns TRUE on succes
 291  *    and FALSE on error. The allocated cipher is returned in new_cipher
 292  *    argument. The caller must set the key to the cipher after this
 293  *    function has returned by calling the silc_cipher_set_key.
 294  *
 295  ***/
 296 SilcBool silc_cipher_alloc(const char *name, SilcCipher *new_cipher);
 297
 298 /****f* silccrypt/silc_cipher_alloc
 299  *
 300  * SYNOPSIS
 301  *
 302  *    SilcBool silc_cipher_alloc_full(const char *alg_name,
 303  *                                    SilcUInt32 key_len,
 304  *                                    SilcCipherMode mode,
 305  *                                    SilcCipher *new_cipher);
 306  * DESCRIPTION
 307  *
 308  *    Same as silc_cipher_alloc but takes the cipher algorithm name,
 309  *    key length and mode as separate arguments.
 310  *
 311  ***/
 312 SilcBool silc_cipher_alloc_full(const char *alg_name, SilcUInt32 key_len,
 313                                 SilcCipherMode mode, SilcCipher *new_cipher);
 314
 315 /****f* silccrypt/silc_cipher_free
 316  *
 317  * SYNOPSIS
 318  *
 319  *    void silc_cipher_free(SilcCipher cipher);
 320  *
 321  * DESCRIPTION
 322  *
 323  *    Frees the given cipher.
 324  *
 325  ***/
 326 void silc_cipher_free(SilcCipher cipher);
 327
 328 /****f* silccrypt/silc_cipher_is_supported
 329  *
 330  * SYNOPSIS
 331  *
 332  * SilcBool silc_cipher_is_supported(const char *name);
 333  *
 334  * DESCRIPTION
 335  *
 336  *    Returns TRUE if cipher `name' is supported.
 337  *
 338  ***/
 339 SilcBool silc_cipher_is_supported(const char *name);
 340
 341 /****f* silccrypt/silc_cipher_get_supported
 342  *
 343  * SYNOPSIS
 344  *
 345  *    char *silc_cipher_get_supported(SilcBool only_registered);
 346  *
 347  * DESCRIPTION
 348  *
 349  *    Returns comma separated list of supported ciphers.  If `only_registered'
 350  *    is TRUE only ciphers explicitly registered with silc_cipher_register
 351  *    are returned.  If FALSE, then all registered and default builtin
 352  *    ciphers are returned.  However, if there are no registered ciphers
 353  *    and `only_registered' is TRUE, the builtin ciphers are returned.
 354  *
 355  ***/
 356 char *silc_cipher_get_supported(SilcBool only_registered);
 357
 358 /****f* silccrypt/silc_cipher_encrypt
 359  *
 360  * SYNOPSIS
 361  *
 362  *    SilcBool silc_cipher_encrypt(SilcCipher cipher,
 363  *                                 const unsigned char *src,
 364  *                                 unsigned char *dst, SilcUInt32 len,
 365  *                                 unsigned char *iv);
 366  *
 367  * DESCRIPTION
 368  *
 369  *    Encrypts data from `src' into `dst' with the specified cipher and
 370  *    Initial Vector (IV).  If the `iv' is NULL then the cipher's internal
 371  *    IV is used.  The `src' and `dst' maybe same buffer.
 372  *
 373  ***/
 374 SilcBool silc_cipher_encrypt(SilcCipher cipher, const unsigned char *src,
 375                              unsigned char *dst, SilcUInt32 len,
 376                              unsigned char *iv);
 377
 378 /****f* silccrypt/silc_cipher_decrypt
 379  *
 380  * SYNOPSIS
 381  *
 382  *    SilcBool silc_cipher_decrypt(SilcCipher cipher,
 383  *                                 const unsigned char *src,
 384  *                                 unsigned char *dst, SilcUInt32 len,
 385  *                                 unsigned char *iv);
 386  *
 387  * DESCRIPTION
 388  *
 389  *    Decrypts data from `src' into `dst' with the specified cipher and
 390  *    Initial Vector (IV).  If the `iv' is NULL then the cipher's internal
 391  *    IV is used.  The `src' and `dst' maybe same buffer.
 392  *
 393  ***/
 394 SilcBool silc_cipher_decrypt(SilcCipher cipher, const unsigned char *src,
 395                              unsigned char *dst, SilcUInt32 len,
 396                              unsigned char *iv);
 397
 398 /****f* silccrypt/silc_cipher_set_key
 399  *
 400  * SYNOPSIS
 401  *
 402  *    SilcBool silc_cipher_set_key(SilcCipher cipher, const unsigned char *key,
 403  *                                 SilcUInt32 bit_keylen, SilcBool encryption);
 404  *
 405  * DESCRIPTION
 406  *
 407  *    Sets the key for the cipher.  The `keylen' is the key length in
 408  *    bits.  If the `encryption' is TRUE the key is for encryption, if FALSE
 409  *    the key is for decryption.
 410  *
 411  ***/
 412 SilcBool silc_cipher_set_key(SilcCipher cipher, const unsigned char *key,
 413                              SilcUInt32 bit_keylen, SilcBool encryption);
 414
 415 /****f* silccrypt/silc_cipher_set_iv
 416  *
 417  * SYNOPSIS
 418  *
 419  *    void silc_cipher_set_iv(SilcCipher cipher, const unsigned char *iv);
 420  *
 421  * DESCRIPTION
 422  *
 423  *    Sets the IV (initialization vector) for the cipher.  The `iv' must be
 424  *    the size of the block size of the cipher.  If `iv' is NULL this
 425  *    does not do anything.
 426  *
 427  *    If the encryption mode is CTR (Counter mode) this also resets the
 428  *    the counter for a new block.  This is done also if `iv' is NULL.
 429  *
 430  *    If the encryption mode is CFB (cipher feedback) this also resets the
 431  *    the feedback stream for a new block.  This is done also if `iv' is NULL.
 432  *
 433  ***/
 434 void silc_cipher_set_iv(SilcCipher cipher, const unsigned char *iv);
 435
 436 /****f* silccrypt/silc_cipher_get_iv
 437  *
 438  * SYNOPSIS
 439  *
 440  *    unsigned char *silc_cipher_get_iv(SilcCipher cipher);
 441  *
 442  * DESCRIPTION
 443  *
 444  *    Returns the IV (initial vector) of the cipher.  The returned
 445  *    pointer must not be freed by the caller.  If the caller modifies
 446  *    the returned pointer the IV inside cipher is also modified.
 447  *
 448  ***/
 449 unsigned char *silc_cipher_get_iv(SilcCipher cipher);
 450
 451 /****f* silccrypt/silc_cipher_get_key_len
 452  *
 453  * SYNOPSIS
 454  *
 455  *    SilcUInt32 silc_cipher_get_key_len(SilcCipher cipher);
 456  *
 457  * DESCRIPTION
 458  *
 459  *    Returns the key length of the cipher in bits.
 460  *
 461  ***/
 462 SilcUInt32 silc_cipher_get_key_len(SilcCipher cipher);
 463
 464 /****f* silccrypt/silc_cipher_get_block_len
 465  *
 466  * SYNOPSIS
 467  *
 468  *    SilcUInt32 silc_cipher_get_block_len(SilcCipher cipher);
 469  *
 470  * DESCRIPTION
 471  *
 472  *    Returns the block size of the cipher in bytes.
 473  *
 474  ***/
 475 SilcUInt32 silc_cipher_get_block_len(SilcCipher cipher);
 476
 477 /****f* silccrypt/silc_cipher_get_iv_len
 478  *
 479  * SYNOPSIS
 480  *
 481  *    SilcUInt32 silc_cipher_get_iv_len(SilcCipher cipher);
 482  *
 483  * DESCRIPTION
 484  *
 485  *    Returns the IV length of the cipher in bytes.
 486  *
 487  ***/
 488 SilcUInt32 silc_cipher_get_iv_len(SilcCipher cipher);
 489
 490 /****f* silccrypt/silc_cipher_get_name
 491  *
 492  * SYNOPSIS
 493  *
 494  *    const char *silc_cipher_get_name(SilcCipher cipher);
 495  *
 496  * DESCRIPTION
 497  *
 498  *    Returns the full name of the cipher (eg. 'aes-256-ctr').
 499  *
 500  ***/
 501 const char *silc_cipher_get_name(SilcCipher cipher);
 502
 503 /****f* silccrypt/silc_cipher_get_alg_name
 504  *
 505  * SYNOPSIS
 506  *
 507  *    const char *silc_cipher_get_alg_name(SilcCipher cipher);
 508  *
 509  * DESCRIPTION
 510  *
 511  *    Returns the algorithm name of the cipher (eg. 'aes').
 512  *
 513  ***/
 514 const char *silc_cipher_get_alg_name(SilcCipher cipher);
 515
 516 /****f* silccrypt/silc_cipher_get_mode
 517  *
 518  * SYNOPSIS
 519  *
 520  *    SilcCipherMode silc_cipher_get_mode(SilcCipher cipher);
 521  *
 522  * DESCRIPTION
 523  *
 524  *    Returns the cipher mode.
 525  *
 526  ***/
 527 SilcCipherMode silc_cipher_get_mode(SilcCipher cipher);
 528
 529 #endif /* SILCCIPHER_H */