lib/silccrypt/silccipher.h

   1 /*
   2
   3   silccipher.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 1997 - 2006 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 #ifndef SILCCIPHER_H
  21 #define SILCCIPHER_H
  22
  23 /****h* silccrypt/SILC Cipher Interface
  24  *
  25  * DESCRIPTION
  26  *
  27  * This is the interface for cipher functions.  It provides cipher
  28  * registering and unregistering routines, encryption and decryption
  29  * routines.
  30  *
  31  ***/
  32
  33 /****s* silccrypt/SilcCipherAPI/SilcCipher
  34  *
  35  * NAME
  36  *
  37  *    typedef struct { ... } SilcCipher;
  38  *
  39  * DESCRIPTION
  40  *
  41  *    This context is the actual cipher context and is allocated
  42  *    by silc_cipher_alloc and given as argument usually to all
  43  *    silc_cipher _* functions.  It is freed by the silc_cipher_free
  44  *    function.
  45  *
  46  ***/
  47 typedef struct SilcCipherStruct *SilcCipher;
  48
  49 /* The default SILC Cipher object to represent any cipher in SILC. */
  50 typedef struct {
  51   char *name;
  52   SilcBool (*set_key)(void *, const unsigned char *, SilcUInt32, SilcBool);
  53   SilcBool (*encrypt)(void *, const unsigned char *, unsigned char *,
  54                   SilcUInt32, unsigned char *);
  55   SilcBool (*decrypt)(void *, const unsigned char *, unsigned char *,
  56                   SilcUInt32, unsigned char *);
  57   SilcUInt32 (*context_len)();
  58   unsigned int key_len   : 12;
  59   unsigned int block_len : 10;
  60   unsigned int iv_len    : 10;
  61 } SilcCipherObject;
  62
  63 #define SILC_CIPHER_MAX_IV_SIZE 16
  64
  65 /* Marks for all ciphers in silc. This can be used in silc_cipher_unregister
  66    to unregister all ciphers at once. */
  67 #define SILC_ALL_CIPHERS ((SilcCipherObject *)1)
  68
  69 /* Static list of ciphers for silc_cipher_register_default(). */
  70 extern DLLAPI const SilcCipherObject silc_default_ciphers[];
  71
  72 /* Default cipher in the SILC protocol */
  73 #define SILC_DEFAULT_CIPHER "aes-256-cbc"
  74
  75 /* Macros */
  76
  77 /* Function names in SILC Crypto modules. The name of the cipher
  78    is appended into these names and used to the get correct symbol out
  79    of the module. All SILC Crypto API compliant modules must support
  80    these function names (use macros below to assure this). */
  81 #define SILC_CIPHER_SIM_SET_KEY "set_key"
  82 #define SILC_CIPHER_SIM_ENCRYPT_CBC "encrypt_cbc"
  83 #define SILC_CIPHER_SIM_DECRYPT_CBC "decrypt_cbc"
  84 #define SILC_CIPHER_SIM_CONTEXT_LEN "context_len"
  85
  86 /* These macros can be used to implement the SILC Crypto API and to avoid
  87    errors in the API these macros should be used always. */
  88 #define SILC_CIPHER_API_SET_KEY(cipher)                 \
  89 SilcBool silc_##cipher##_set_key(void *context,         \
  90                              const unsigned char *key,  \
  91                              SilcUInt32 keylen,         \
  92                              SilcBool encryption)
  93 #define SILC_CIPHER_API_ENCRYPT_CBC(cipher)                     \
  94 SilcBool silc_##cipher##_encrypt_cbc(void *context,                     \
  95                                  const unsigned char *src,      \
  96                                  unsigned char *dst,            \
  97                                  SilcUInt32 len,                \
  98                                  unsigned char *iv)
  99 #define SILC_CIPHER_API_DECRYPT_CBC(cipher)                     \
 100 SilcBool silc_##cipher##_decrypt_cbc(void *context,                     \
 101                                  const unsigned char *src,      \
 102                                  unsigned char *dst,            \
 103                                  SilcUInt32 len,                \
 104                                  unsigned char *iv)
 105 #define SILC_CIPHER_API_CONTEXT_LEN(cipher)                     \
 106 SilcUInt32 silc_##cipher##_context_len()
 107
 108 /* Prototypes */
 109
 110 /****f* silccrypt/SilcCipherAPI/silc_cipher_register
 111  *
 112  * SYNOPSIS
 113  *
 114  *    SilcBool silc_cipher_register(const SilcCipherObject *cipher);
 115  *
 116  * DESCRIPTION
 117  *
 118  *    Register a new cipher into SILC. This is used at the initialization of
 119  *    the SILC. This function allocates a new object for the cipher to be
 120  *    registered. Therefore, if memory has been allocated for the object sent
 121  *    as argument it has to be free'd after this function returns succesfully.
 122  *
 123  ***/
 124 SilcBool silc_cipher_register(const SilcCipherObject *cipher);
 125
 126 /****f* silccrypt/SilcCipherAPI/silc_cipher_unregister
 127  *
 128  * SYNOPSIS
 129  *
 130  *    SilcBool silc_cipher_unregister(SilcCipherObject *cipher);
 131  *
 132  * DESCRIPTION
 133  *
 134  *    Unregister a cipher from the SILC.
 135  *
 136  ***/
 137 SilcBool silc_cipher_unregister(SilcCipherObject *cipher);
 138
 139 /****f* silccrypt/SilcCipherAPI/silc_cipher_register_default
 140  *
 141  * SYNOPSIS
 142  *
 143  *    SilcBool silc_cipher_register_default(void);
 144  *
 145  * DESCRIPTION
 146  *
 147  *    Function that registers all the default ciphers (all builtin ciphers).
 148  *    The application may use this to register the default ciphers if specific
 149  *    ciphers in any specific order is not wanted.
 150  *
 151  ***/
 152 SilcBool silc_cipher_register_default(void);
 153
 154 /****f* silccrypt/SilcCipherAPI/silc_cipher_unregister_all
 155  *
 156  * SYNOPSIS
 157  *
 158  *    SilcBool silc_cipher_unregister_all(void);
 159  *
 160  * DESCRIPTION
 161  *
 162  *    Unregisters all ciphers.
 163  *
 164  ***/
 165 SilcBool silc_cipher_unregister_all(void);
 166
 167 /****f* silccrypt/SilcCipherAPI/silc_cipher_alloc
 168  *
 169  * SYNOPSIS
 170  *
 171  *    SilcBool silc_cipher_alloc(const unsigned char *name,
 172  *                           SilcCipher *new_cipher);
 173  *
 174  * DESCRIPTION
 175  *
 176  *    Allocates a new SILC cipher object. Function returns 1 on succes and 0
 177  *    on error. The allocated cipher is returned in new_cipher argument. The
 178  *    caller must set the key to the cipher after this function has returned
 179  *    by calling the ciphers set_key function.
 180  *
 181  ***/
 182 SilcBool silc_cipher_alloc(const unsigned char *name, SilcCipher *new_cipher);
 183
 184 /****f* silccrypt/SilcCipherAPI/silc_cipher_free
 185  *
 186  * SYNOPSIS
 187  *
 188  *    void silc_cipher_free(SilcCipher cipher);
 189  *
 190  * DESCRIPTION
 191  *
 192  *    Frees the given cipher.
 193  *
 194  ***/
 195 void silc_cipher_free(SilcCipher cipher);
 196
 197 /****f* silccrypt/SilcCipherAPI/silc_cipher_is_supported
 198  *
 199  * SYNOPSIS
 200  *
 201  * SilcBool silc_cipher_is_supported(const unsigned char *name);
 202  *
 203  * DESCRIPTION
 204  *
 205  *    Returns TRUE if cipher `name' is supported.
 206  *
 207  ***/
 208 SilcBool silc_cipher_is_supported(const unsigned char *name);
 209
 210 /****f* silccrypt/SilcCipherAPI/silc_cipher_get_supported
 211  *
 212  * SYNOPSIS
 213  *
 214  *    char *silc_cipher_get_supported(void);
 215  *
 216  * DESCRIPTION
 217  *
 218  *    Returns comma separated list of supported ciphers.
 219  *
 220  ***/
 221 char *silc_cipher_get_supported(void);
 222
 223 /****f* silccrypt/SilcCipherAPI/silc_cipher_encrypt
 224  *
 225  * SYNOPSIS
 226  *
 227  *    SilcBool silc_cipher_encrypt(SilcCipher cipher,
 228  *                                 const unsigned char *src,
 229  *                                 unsigned char *dst, SilcUInt32 len,
 230  *                                 unsigned char *iv);
 231  *
 232  * DESCRIPTION
 233  *
 234  *    Encrypts data from `src' into `dst' with the specified cipher and
 235  *    Initial Vector (IV).  If the `iv' is NULL then the cipher's internal
 236  *    IV is used.  The `src' and `dst' maybe same buffer.
 237  *
 238  ***/
 239 SilcBool silc_cipher_encrypt(SilcCipher cipher, const unsigned char *src,
 240                              unsigned char *dst, SilcUInt32 len,
 241                              unsigned char *iv);
 242
 243 /****f* silccrypt/SilcCipherAPI/silc_cipher_decrypt
 244  *
 245  * SYNOPSIS
 246  *
 247  *    SilcBool silc_cipher_decrypt(SilcCipher cipher,
 248  *                                 const unsigned char *src,
 249  *                                 unsigned char *dst, SilcUInt32 len,
 250  *                                 unsigned char *iv);
 251  *
 252  * DESCRIPTION
 253  *
 254  *    Decrypts data from `src' into `dst' with the specified cipher and
 255  *    Initial Vector (IV).  If the `iv' is NULL then the cipher's internal
 256  *    IV is used.  The `src' and `dst' maybe same buffer.
 257  *
 258  ***/
 259 SilcBool silc_cipher_decrypt(SilcCipher cipher, const unsigned char *src,
 260                              unsigned char *dst, SilcUInt32 len,
 261                              unsigned char *iv);
 262
 263 /****f* silccrypt/SilcCipherAPI/silc_cipher_set_key
 264  *
 265  * SYNOPSIS
 266  *
 267  *    SilcBool silc_cipher_set_key(SilcCipher cipher, const unsigned char *key,
 268  *                                 SilcUInt32 keylen, SilcBool encryption);
 269  *
 270  * DESCRIPTION
 271  *
 272  *    Sets the key for the cipher.  The `keylen' is the key length in
 273  *    bits.  If the `encryption' is TRUE the key is for encryption, if FALSE
 274  *    the key is for decryption.
 275  *
 276  ***/
 277 SilcBool silc_cipher_set_key(SilcCipher cipher, const unsigned char *key,
 278                              SilcUInt32 keylen, SilcBool encryption);
 279
 280 /****f* silccrypt/SilcCipherAPI/silc_cipher_set_iv
 281  *
 282  * SYNOPSIS
 283  *
 284  *    void silc_cipher_set_iv(SilcCipher cipher, const unsigned char *iv);
 285  *
 286  * DESCRIPTION
 287  *
 288  *    Sets the IV (initial vector) for the cipher.  The `iv' must be
 289  *    the size of the block size of the cipher.
 290  *
 291  ***/
 292 void silc_cipher_set_iv(SilcCipher cipher, const unsigned char *iv);
 293
 294 /****f* silccrypt/SilcCipherAPI/silc_cipher_get_iv
 295  *
 296  * SYNOPSIS
 297  *
 298  *    unsigned char *silc_cipher_get_iv(SilcCipher cipher);
 299  *
 300  * DESCRIPTION
 301  *
 302  *    Returns the IV (initial vector) of the cipher.  The returned
 303  *    pointer must not be freed by the caller.
 304  *
 305  ***/
 306 unsigned char *silc_cipher_get_iv(SilcCipher cipher);
 307
 308 /****f* silccrypt/SilcCipherAPI/silc_cipher_get_key_len
 309  *
 310  * SYNOPSIS
 311  *
 312  *    SilcUInt32 silc_cipher_get_key_len(SilcCipher cipher);
 313  *
 314  * DESCRIPTION
 315  *
 316  *    Returns the key length of the cipher in bits.
 317  *
 318  ***/
 319 SilcUInt32 silc_cipher_get_key_len(SilcCipher cipher);
 320
 321 /****f* silccrypt/SilcCipherAPI/silc_cipher_get_block_len
 322  *
 323  * SYNOPSIS
 324  *
 325  *    SilcUInt32 silc_cipher_get_block_len(SilcCipher cipher);
 326  *
 327  * DESCRIPTION
 328  *
 329  *    Returns the block size of the cipher in bytes.
 330  *
 331  ***/
 332 SilcUInt32 silc_cipher_get_block_len(SilcCipher cipher);
 333
 334 /****f* silccrypt/SilcCipherAPI/silc_cipher_get_iv_len
 335  *
 336  * SYNOPSIS
 337  *
 338  *    SilcUInt32 silc_cipher_get_iv_len(SilcCipher cipher);
 339  *
 340  * DESCRIPTION
 341  *
 342  *    Returns the IV length of the cipher in bytes.
 343  *
 344  ***/
 345 SilcUInt32 silc_cipher_get_iv_len(SilcCipher cipher);
 346
 347 /****f* silccrypt/SilcCipherAPI/silc_cipher_get_name
 348  *
 349  * SYNOPSIS
 350  *
 351  *    const char *silc_cipher_get_name(SilcCipher cipher);
 352  *
 353  * DESCRIPTION
 354  *
 355  *    Returns the name of the cipher.
 356  *
 357  ***/
 358 const char *silc_cipher_get_name(SilcCipher cipher);
 359
 360 #endif /* SILCCIPHER_H */