lib/silcacc/silcacc.h

   1 /*
   2
   3   silcacc.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 2007 - 2008 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* silcacc/Crypto Accelerator Interface
  21  *
  22  * DESCRIPTION
  23  *
  24  * SILC Crypto Accelerator Interface provides a generic interface for
  25  * cryptographic accelerators.  The interface can access different kind of
  26  * accelerators, such as hardware accelerators.  Using an accelerator can
  27  * significantly improve encryption, decryption, signature and verification
  28  * performance.
  29  *
  30  * Third-party accelerators can be registered into the accelerator interface
  31  * and used through the same generic interface.
  32  *
  33  * The interface can be used to accelerate public and private keys, and
  34  * ciphers.
  35  *
  36  ***/
  37
  38 #ifndef SILCACC_H
  39 #define SILCACC_H
  40
  41 /****s* silcacc/SilcAccelerator
  42  *
  43  * NAME
  44  *
  45  *    typedef struct SilcAcceleratorObject { ... }
  46  *                            *SilcAccelerator, SilcAcceleratorStruct;
  47  *
  48  * DESCRIPTION
  49  *
  50  *    The accelerator context.  This is given as argument to silc_acc_register
  51  *    when registering new accelerator, and it is given as argument to all
  52  *    other silc_acc_* functions.  Registered accelerator context can be
  53  *    retrieved by calling silc_acc_find.
  54  *
  55  ***/
  56 typedef struct SilcAcceleratorObject {
  57   const char *name;                         /* Accelerator's name */
  58   SilcBool (*init)(SilcSchedule schedule,
  59                    va_list va);             /* Initialize accelerator */
  60   SilcBool (*uninit)(void);                 /* Uninitialize accelerator */
  61   const SilcPKCSAlgorithm *pkcs;            /* Accelerated PKCS algorithms */
  62   const SilcCipherObject *cipher;           /* Accelerated ciphers */
  63 #if 0
  64   const SilcDHObject *dh;                   /* Accelerated Diffie-Hellmans */
  65   const SilcHashObject *hash;               /* Accelerated hashes */
  66   const SilcHmacObject *hmac;               /* Accelerated HMACs */
  67   const SilcRngObject *rng;                 /* Accelerated RNG's */
  68 #endif /* 0 */
  69 } *SilcAccelerator, SilcAcceleratorStruct;
  70
  71 /****f* silcacc/silc_acc_register
  72  *
  73  * SYNOPSIS
  74  *
  75  *    SilcBool silc_acc_register(const SilcAccelerator acc);
  76  *
  77  * DESCRIPTION
  78  *
  79  *    Register new accelerator to the accelerator library.  The `acc'
  80  *    is the accelerator context to be registered.
  81  *
  82  * NOTES
  83  *
  84  *    This needs to be called only when adding new accelerator to the
  85  *    library.  The accelerator library has some pre-registered accelerators
  86  *    that need not be registered with this call.
  87  *
  88  ***/
  89 SilcBool silc_acc_register(const SilcAccelerator acc);
  90
  91 /****f* silcacc/silc_acc_unregister
  92  *
  93  * SYNOPSIS
  94  *
  95  *    void silc_acc_unregister(SilcAccelerator acc);
  96  *
  97  * DESCRIPTION
  98  *
  99  *    Unregister the accelerator `acc' from the accelerator library.  The
 100  *    accelerator cannot be used anymore after this call has returned.
 101  *
 102  ***/
 103 void silc_acc_unregister(SilcAccelerator acc);
 104
 105 /****f* silcacc/silc_acc_find
 106  *
 107  * SYNOPSIS
 108  *
 109  *    SilcAccelerator silc_acc_find(const char *name);
 110  *
 111  * DESCRIPTION
 112  *
 113  *    Find accelerator by its name indicated by `name'.  Returns the
 114  *    accelerator context or NULL if such accelerator is not registered.
 115  *
 116  ***/
 117 SilcAccelerator silc_acc_find(const char *name);
 118
 119 /****f* silcacc/silc_acc_init
 120  *
 121  * SYNOPSIS
 122  *
 123  *    SilcBool silc_acc_init(SilcAccelerator acc, SilcSchedule schedule, ...);
 124  *
 125  * DESCRIPTION
 126  *
 127  *    Initialize accelerator `acc'.  Usually accelerator may be initialized
 128  *    only once and should be done after registering it.  The `schedule'
 129  *    must be given as argument, in case the accelerator needs to do operations
 130  *    through the scheduler.  The variable argument list is optional
 131  *    accelerator specific initialization arguments.  The argument list must
 132  *    be ended with NULL.  Returns FALSE if initialization failed.
 133  *
 134  * EXAMPLE
 135  *
 136  *    silc_acc_init(softacc, "min_threads", 2, "max_threads", 16, NULL);
 137  *
 138  ***/
 139 SilcBool silc_acc_init(SilcAccelerator acc, SilcSchedule schedule, ...);
 140
 141 /****f* silcacc/silc_acc_uninit
 142  *
 143  * SYNOPSIS
 144  *
 145  *    SilcBool silc_acc_uninit(SilcAccelerator acc);
 146  *
 147  * DESCRIPTION
 148  *
 149  *    Uninitialize the accelerator `acc'.  The accelerator may not be used
 150  *    after this call has returned.  Some accelerators may be re-initialized
 151  *    by calling silc_acc_init again.  Returns FALSE if error occurred
 152  *    during uninitializing.
 153  *
 154  ***/
 155 SilcBool silc_acc_uninit(SilcAccelerator acc);
 156
 157 /****f* silcacc/silc_acc_get_supported
 158  *
 159  * SYNOPSIS
 160  *
 161  *    SilcDList silc_acc_get_supported(void);
 162  *
 163  * DESCRIPTION
 164  *
 165  *    Returns list of registered accelerators.  The caller must free the
 166  *    returned list by calling silc_dlist_uninit.
 167  *
 168  ***/
 169 SilcDList silc_acc_get_supported(void);
 170
 171 /****f* silcacc/silc_acc_get_name
 172  *
 173  * SYNOPSIS
 174  *
 175  *    const char *silc_acc_get_name(SilcAccelerator acc);
 176  *
 177  * DESCRIPTION
 178  *
 179  *    Returns the name of the accelerator `acc'.
 180  *
 181  ***/
 182 const char *silc_acc_get_name(SilcAccelerator acc);
 183
 184 /****f* silcacc/silc_acc_public_key
 185  *
 186  * SYNOPSIS
 187  *
 188  *    SilcPublicKey silc_acc_public_key(SilcAccelerator acc,
 189  *                                      SilcPublicKey public_key);
 190  *
 191  * DESCRIPTION
 192  *
 193  *    Accelerate the public key indicated by `public_key'.  Returns new
 194  *    accelerated SilcPublicKey context.  It can be used just as normal
 195  *    public key and must be freed by calling silc_pkcs_public_key_free.
 196  *    The associated `public_key' is not freed when the accelerated public
 197  *    key is freed.  The `public_key' must not be freed as long as it is
 198  *    accelerated.
 199  *
 200  *    The associated `public_key' can be retrieved from the returned
 201  *    public key by calling silc_acc_get_public_key.
 202  *
 203  *    If this returns NULL the public key could not be accelerated.  This
 204  *    usually should not be considered serious error.  Instead, the public
 205  *    key should be used without acceleration.
 206  *
 207  ***/
 208 SilcPublicKey silc_acc_public_key(SilcAccelerator acc,
 209                                   SilcPublicKey public_key);
 210
 211 /****f* silcacc/silc_acc_private_key
 212  *
 213  * SYNOPSIS
 214  *
 215  *    SilcPrivateKey silc_acc_private_key(SilcAccelerator acc,
 216  *                                        SilcPrivateKey private_key);
 217  *
 218  * DESCRIPTION
 219  *
 220  *    Accelerate the private key indicated by `private_key'.  Returns new
 221  *    accelerated SilcPrivateKey context.  It can be used just as normal
 222  *    private key and must be freed by calling silc_pkcs_private_key_free.
 223  *    The associated `private_key' is not freed when the accelerated private
 224  *    key is freed.  The `private_key' must not be freed as long as it is
 225  *    accelerated.
 226  *
 227  *    The associated `private_key' can be retrieved from the returned
 228  *    private key by calling silc_acc_get_private_key.
 229  *
 230  *    If this returns NULL the private key could not be accelerated.  This
 231  *    usually should not be considered serious error.  Instead, the private
 232  *    key should be used without acceleration.
 233  *
 234  ***/
 235 SilcPrivateKey silc_acc_private_key(SilcAccelerator acc,
 236                                     SilcPrivateKey private_key);
 237
 238 /****f* silcacc/silc_acc_get_public_key
 239  *
 240  * SYNOPSIS
 241  *
 242  *    SilcPublicKey silc_acc_get_public_key(SilcAccelerator acc,
 243  *                                          SilcPublicKey public_key);
 244  *
 245  * DESCRIPTION
 246  *
 247  *    Returns the underlaying public key from the accelerated public key
 248  *    indicated by `public_key'.  Returns NULL if `public_key' is not
 249  *    accelerated public key.
 250  *
 251  ***/
 252 SilcPublicKey silc_acc_get_public_key(SilcAccelerator acc,
 253                                       SilcPublicKey public_key);
 254
 255 /****f* silcacc/silc_acc_get_private_key
 256  *
 257  * SYNOPSIS
 258  *
 259  *    SilcPrivateKey silc_acc_get_private_key(SilcAccelerator acc,
 260  *                                            SilcPrivateKey private_key);
 261  *
 262  * DESCRIPTION
 263  *
 264  *    Returns the underlaying private key from the accelerated private key
 265  *    indicated by `private_key'.  Returns NULL if `private_key' is not
 266  *    accelerated private key.
 267  *
 268  ***/
 269 SilcPrivateKey silc_acc_get_private_key(SilcAccelerator acc,
 270                                         SilcPrivateKey private_key);
 271
 272 /****f* silcacc/silc_acc_cipher
 273  *
 274  * SYNOPSIS
 275  *
 276  *    SilcCipher silc_acc_cipher(SilcAccelerator acc, SilcCipher cipher);
 277  *
 278  * DESCRIPTION
 279  *
 280  *    Accelerate the cipher indicated by `cipher'.  Returns new accelerated
 281  *    SilcCipher context.  It can be used just as normal cipher and must be
 282  *    freed by calilng silc_cipher_free.  The associated `cipher' is not
 283  *    freed when the accelerated cipher is freed.  The `cipher' must not be
 284  *    freed as long as it is accelerated.
 285  *
 286  *    When key and IV is set for the accelerated cipher, it is also set to
 287  *    the associated cipher.
 288  *
 289  *    The associated `cipher' can be retrieved from the accelerated cipher
 290  *    by calling silc_acc_get_cipher.
 291  *
 292  *    If this returns NULL the cipher could not be accelerated.  This
 293  *    usually should not be considered serious error.  Instead, the cipher
 294  *    should be used without acceleration.
 295  *
 296  ***/
 297 SilcCipher silc_acc_cipher(SilcAccelerator acc, SilcCipher cipher);
 298
 299 /****f* silcacc/silc_acc_get_cipher
 300  *
 301  * SYNOPSIS
 302  *
 303  *    SilcCipher silc_acc_get_cipher(SilcAccelerator acc, SilcCipher cipher);
 304  *
 305  * DESCRIPTION
 306  *
 307  *    Returns the underlaying cipher from the accelerated cipher indicated
 308  *    by `cipher'.  Returns NULL if `cipher' is not accelerated cipher.
 309  *
 310  ***/
 311 SilcCipher silc_acc_get_cipher(SilcAccelerator acc, SilcCipher cipher);
 312
 313 #endif /* SILCACC_H */