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