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