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,
 182  *                           SilcCipher *new_cipher);
 183  *
 184  * DESCRIPTION
 185  *
 186  *    Allocates a new SILC cipher object. Function returns 1 on succes and 0
 187  *    on error. The allocated cipher is returned in new_cipher argument. The
 188  *    caller must set the key to the cipher after this function has returned
 189  *    by calling the ciphers set_key function.
 190  *
 191  ***/
 192 bool silc_cipher_alloc(const unsigned char *name, SilcCipher *new_cipher);
 193
 194 /****f* silccrypt/SilcCipherAPI/silc_cipher_free
 195  *
 196  * SYNOPSIS
 197  *
 198  *    void silc_cipher_free(SilcCipher cipher);
 199  *
 200  * DESCRIPTION
 201  *
 202  *    Frees the given cipher.
 203  *
 204  ***/
 205 void silc_cipher_free(SilcCipher cipher);
 206
 207 /****f* silccrypt/SilcCipherAPI/silc_cipher_is_supported
 208  *
 209  * SYNOPSIS
 210  *
 211  * bool silc_cipher_is_supported(const unsigned char *name);
 212  *
 213  * DESCRIPTION
 214  *
 215  *    Returns TRUE if cipher `name' is supported.
 216  *
 217  ***/
 218 bool silc_cipher_is_supported(const unsigned char *name);
 219
 220 /****f* silccrypt/SilcCipherAPI/silc_cipher_get_supported
 221  *
 222  * SYNOPSIS
 223  *
 224  *    char *silc_cipher_get_supported(void);
 225  *
 226  * DESCRIPTION
 227  *
 228  *    Returns comma separated list of supported ciphers.
 229  *
 230  ***/
 231 char *silc_cipher_get_supported(void);
 232
 233 /****f* silccrypt/SilcCipherAPI/silc_cipher_encrypt
 234  *
 235  * SYNOPSIS
 236  *
 237  *    bool silc_cipher_encrypt(SilcCipher cipher, const unsigned char *src,
 238  *                             unsigned char *dst, SilcUInt32 len,
 239  *                             unsigned char *iv);
 240  *
 241  * DESCRIPTION
 242  *
 243  *    Encrypts data from `src' into `dst' with the specified cipher and
 244  *    Initial Vector (IV).  The `src' and `dst' maybe same buffer.
 245  *
 246  ***/
 247 bool 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  *    bool silc_cipher_decrypt(SilcCipher cipher, const unsigned char *src,
 256  *                             unsigned char *dst, SilcUInt32 len,
 257  *                             unsigned char *iv);
 258  *
 259  * DESCRIPTION
 260  *
 261  *    Decrypts data from `src' into `dst' with the specified cipher and
 262  *    Initial Vector (IV).  The `src' and `dst' maybe same buffer.
 263  *
 264  ***/
 265 bool silc_cipher_decrypt(SilcCipher cipher, const unsigned char *src,
 266                          unsigned char *dst, SilcUInt32 len,
 267                          unsigned char *iv);
 268
 269 /****f* silccrypt/SilcCipherAPI/silc_cipher_set_key
 270  *
 271  * SYNOPSIS
 272  *
 273  *    bool silc_cipher_set_key(SilcCipher cipher, const unsigned char *key,
 274  *                             SilcUInt32 keylen);
 275  *
 276  * DESCRIPTION
 277  *
 278  *    Sets the key for the cipher.  The `keylen' is the key length in
 279  *    bits.
 280  *
 281  ***/
 282 bool silc_cipher_set_key(SilcCipher cipher, const unsigned char *key,
 283                          SilcUInt32 keylen);
 284
 285 /****f* silccrypt/SilcCipherAPI/silc_cipher_set_iv
 286  *
 287  * SYNOPSIS
 288  *
 289  *    void silc_cipher_set_iv(SilcCipher cipher, const unsigned char *iv);
 290  *
 291  * DESCRIPTION
 292  *
 293  *    Sets the IV (initial vector) for the cipher.  The `iv' must be
 294  *    the size of the block size of the cipher.
 295  *
 296  ***/
 297 void silc_cipher_set_iv(SilcCipher cipher, const unsigned char *iv);
 298
 299 /****f* silccrypt/SilcCipherAPI/silc_cipher_get_iv
 300  *
 301  * SYNOPSIS
 302  *
 303  *    unsigned char *silc_cipher_get_iv(SilcCipher cipher);
 304  *
 305  * DESCRIPTION
 306  *
 307  *    Returns the IV (initial vector) of the cipher.  The returned
 308  *    pointer must not be freed by the caller.
 309  *
 310  ***/
 311 unsigned char *silc_cipher_get_iv(SilcCipher cipher);
 312
 313 /****f* silccrypt/SilcCipherAPI/silc_cipher_get_key_len
 314  *
 315  * SYNOPSIS
 316  *
 317  *    SilcUInt32 silc_cipher_get_key_len(SilcCipher cipher);
 318  *
 319  * DESCRIPTION
 320  *
 321  *    Returns the key length of the cipher in bits.
 322  *
 323  ***/
 324 SilcUInt32 silc_cipher_get_key_len(SilcCipher cipher);
 325
 326 /****f* silccrypt/SilcCipherAPI/silc_cipher_get_block_len
 327  *
 328  * SYNOPSIS
 329  *
 330  *    SilcUInt32 silc_cipher_get_block_len(SilcCipher cipher);
 331  *
 332  * DESCRIPTION
 333  *
 334  *    Returns the block size of the cipher in bytes.
 335  *
 336  ***/
 337 SilcUInt32 silc_cipher_get_block_len(SilcCipher cipher);
 338
 339 /****f* silccrypt/SilcCipherAPI/silc_cipher_get_name
 340  *
 341  * SYNOPSIS
 342  *
 343  *    const char *silc_cipher_get_name(SilcCipher cipher);
 344  *
 345  * DESCRIPTION
 346  *
 347  *    Returns the name of the cipher.
 348  *
 349  ***/
 350 const char *silc_cipher_get_name(SilcCipher cipher);
 351
 352 #endif