lib/silccrypt/silccipher.h

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