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).  If the `iv' is NULL then the cipher's internal
 245  *    IV is used.  The `src' and `dst' maybe same buffer.
 246  *
 247  ***/
 248 bool silc_cipher_encrypt(SilcCipher cipher, const unsigned char *src,
 249                          unsigned char *dst, SilcUInt32 len,
 250                          unsigned char *iv);
 251
 252 /****f* silccrypt/SilcCipherAPI/silc_cipher_decrypt
 253  *
 254  * SYNOPSIS
 255  *
 256  *    bool silc_cipher_decrypt(SilcCipher cipher, 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 bool 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  *    bool silc_cipher_set_key(SilcCipher cipher, const unsigned char *key,
 276  *                             SilcUInt32 keylen);
 277  *
 278  * DESCRIPTION
 279  *
 280  *    Sets the key for the cipher.  The `keylen' is the key length in
 281  *    bits.
 282  *
 283  ***/
 284 bool silc_cipher_set_key(SilcCipher cipher, const unsigned char *key,
 285                          SilcUInt32 keylen);
 286
 287 /****f* silccrypt/SilcCipherAPI/silc_cipher_set_iv
 288  *
 289  * SYNOPSIS
 290  *
 291  *    void silc_cipher_set_iv(SilcCipher cipher, const unsigned char *iv);
 292  *
 293  * DESCRIPTION
 294  *
 295  *    Sets the IV (initial vector) for the cipher.  The `iv' must be
 296  *    the size of the block size of the cipher.
 297  *
 298  ***/
 299 void silc_cipher_set_iv(SilcCipher cipher, const unsigned char *iv);
 300
 301 /****f* silccrypt/SilcCipherAPI/silc_cipher_get_iv
 302  *
 303  * SYNOPSIS
 304  *
 305  *    unsigned char *silc_cipher_get_iv(SilcCipher cipher);
 306  *
 307  * DESCRIPTION
 308  *
 309  *    Returns the IV (initial vector) of the cipher.  The returned
 310  *    pointer must not be freed by the caller.
 311  *
 312  ***/
 313 unsigned char *silc_cipher_get_iv(SilcCipher cipher);
 314
 315 /****f* silccrypt/SilcCipherAPI/silc_cipher_get_key_len
 316  *
 317  * SYNOPSIS
 318  *
 319  *    SilcUInt32 silc_cipher_get_key_len(SilcCipher cipher);
 320  *
 321  * DESCRIPTION
 322  *
 323  *    Returns the key length of the cipher in bits.
 324  *
 325  ***/
 326 SilcUInt32 silc_cipher_get_key_len(SilcCipher cipher);
 327
 328 /****f* silccrypt/SilcCipherAPI/silc_cipher_get_block_len
 329  *
 330  * SYNOPSIS
 331  *
 332  *    SilcUInt32 silc_cipher_get_block_len(SilcCipher cipher);
 333  *
 334  * DESCRIPTION
 335  *
 336  *    Returns the block size of the cipher in bytes.
 337  *
 338  ***/
 339 SilcUInt32 silc_cipher_get_block_len(SilcCipher cipher);
 340
 341 /****f* silccrypt/SilcCipherAPI/silc_cipher_get_name
 342  *
 343  * SYNOPSIS
 344  *
 345  *    const char *silc_cipher_get_name(SilcCipher cipher);
 346  *
 347  * DESCRIPTION
 348  *
 349  *    Returns the name of the cipher.
 350  *
 351  ***/
 352 const char *silc_cipher_get_name(SilcCipher cipher);
 353
 354 #endif