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, schedule,
 137  *                  "min_threads", 2, "max_threads", 16, NULL);
 138  *
 139  ***/
 140 SilcBool silc_acc_init(SilcAccelerator acc, SilcSchedule schedule, ...);
 141
 142 /****f* silcacc/silc_acc_uninit
 143  *
 144  * SYNOPSIS
 145  *
 146  *    SilcBool silc_acc_uninit(SilcAccelerator acc);
 147  *
 148  * DESCRIPTION
 149  *
 150  *    Uninitialize the accelerator `acc'.  The accelerator may not be used
 151  *    after this call has returned.  Some accelerators may be re-initialized
 152  *    by calling silc_acc_init again.  Returns FALSE if error occurred
 153  *    during uninitializing.
 154  *
 155  ***/
 156 SilcBool silc_acc_uninit(SilcAccelerator acc);
 157
 158 /****f* silcacc/silc_acc_get_supported
 159  *
 160  * SYNOPSIS
 161  *
 162  *    SilcDList silc_acc_get_supported(void);
 163  *
 164  * DESCRIPTION
 165  *
 166  *    Returns list of registered accelerators.  The caller must free the
 167  *    returned list by calling silc_dlist_uninit.
 168  *
 169  ***/
 170 SilcDList silc_acc_get_supported(void);
 171
 172 /****f* silcacc/silc_acc_get_name
 173  *
 174  * SYNOPSIS
 175  *
 176  *    const char *silc_acc_get_name(SilcAccelerator acc);
 177  *
 178  * DESCRIPTION
 179  *
 180  *    Returns the name of the accelerator `acc'.
 181  *
 182  ***/
 183 const char *silc_acc_get_name(SilcAccelerator acc);
 184
 185 /****f* silcacc/silc_acc_public_key
 186  *
 187  * SYNOPSIS
 188  *
 189  *    SilcPublicKey silc_acc_public_key(SilcAccelerator acc,
 190  *                                      SilcPublicKey public_key);
 191  *
 192  * DESCRIPTION
 193  *
 194  *    Accelerate the public key indicated by `public_key'.  Returns new
 195  *    accelerated SilcPublicKey context.  It can be used just as normal
 196  *    public key and must be freed by calling silc_pkcs_public_key_free.
 197  *    The associated `public_key' is not freed when the accelerated public
 198  *    key is freed.  The `public_key' must not be freed as long as it is
 199  *    accelerated.
 200  *
 201  *    The associated `public_key' can be retrieved from the returned
 202  *    public key by calling silc_acc_get_public_key.
 203  *
 204  *    If this returns NULL the public key could not be accelerated.  This
 205  *    usually should not be considered serious error.  Instead, the public
 206  *    key should be used without acceleration.
 207  *
 208  ***/
 209 SilcPublicKey silc_acc_public_key(SilcAccelerator acc,
 210                                   SilcPublicKey public_key);
 211
 212 /****f* silcacc/silc_acc_private_key
 213  *
 214  * SYNOPSIS
 215  *
 216  *    SilcPrivateKey silc_acc_private_key(SilcAccelerator acc,
 217  *                                        SilcPrivateKey private_key);
 218  *
 219  * DESCRIPTION
 220  *
 221  *    Accelerate the private key indicated by `private_key'.  Returns new
 222  *    accelerated SilcPrivateKey context.  It can be used just as normal
 223  *    private key and must be freed by calling silc_pkcs_private_key_free.
 224  *    The associated `private_key' is not freed when the accelerated private
 225  *    key is freed.  The `private_key' must not be freed as long as it is
 226  *    accelerated.
 227  *
 228  *    The associated `private_key' can be retrieved from the returned
 229  *    private key by calling silc_acc_get_private_key.
 230  *
 231  *    If this returns NULL the private key could not be accelerated.  This
 232  *    usually should not be considered serious error.  Instead, the private
 233  *    key should be used without acceleration.
 234  *
 235  ***/
 236 SilcPrivateKey silc_acc_private_key(SilcAccelerator acc,
 237                                     SilcPrivateKey private_key);
 238
 239 /****f* silcacc/silc_acc_get_public_key
 240  *
 241  * SYNOPSIS
 242  *
 243  *    SilcPublicKey silc_acc_get_public_key(SilcAccelerator acc,
 244  *                                          SilcPublicKey public_key);
 245  *
 246  * DESCRIPTION
 247  *
 248  *    Returns the underlaying public key from the accelerated public key
 249  *    indicated by `public_key'.  Returns NULL if `public_key' is not
 250  *    accelerated public key.
 251  *
 252  ***/
 253 SilcPublicKey silc_acc_get_public_key(SilcAccelerator acc,
 254                                       SilcPublicKey public_key);
 255
 256 /****f* silcacc/silc_acc_get_private_key
 257  *
 258  * SYNOPSIS
 259  *
 260  *    SilcPrivateKey silc_acc_get_private_key(SilcAccelerator acc,
 261  *                                            SilcPrivateKey private_key);
 262  *
 263  * DESCRIPTION
 264  *
 265  *    Returns the underlaying private key from the accelerated private key
 266  *    indicated by `private_key'.  Returns NULL if `private_key' is not
 267  *    accelerated private key.
 268  *
 269  ***/
 270 SilcPrivateKey silc_acc_get_private_key(SilcAccelerator acc,
 271                                         SilcPrivateKey private_key);
 272
 273 /****f* silcacc/silc_acc_cipher
 274  *
 275  * SYNOPSIS
 276  *
 277  *    SilcCipher silc_acc_cipher(SilcAccelerator acc, SilcCipher cipher);
 278  *
 279  * DESCRIPTION
 280  *
 281  *    Accelerate the cipher indicated by `cipher'.  Returns new accelerated
 282  *    SilcCipher context.  It can be used just as normal cipher and must be
 283  *    freed by calilng silc_cipher_free.  The associated `cipher' is not
 284  *    freed when the accelerated cipher is freed.  The `cipher' must not be
 285  *    freed as long as it is accelerated.
 286  *
 287  *    When key and IV is set for the accelerated cipher, it is also set to
 288  *    the associated cipher.
 289  *
 290  *    The associated `cipher' can be retrieved from the accelerated cipher
 291  *    by calling silc_acc_get_cipher.
 292  *
 293  *    If this returns NULL the cipher could not be accelerated.  This
 294  *    usually should not be considered serious error.  Instead, the cipher
 295  *    should be used without acceleration.
 296  *
 297  ***/
 298 SilcCipher silc_acc_cipher(SilcAccelerator acc, SilcCipher cipher);
 299
 300 /****f* silcacc/silc_acc_get_cipher
 301  *
 302  * SYNOPSIS
 303  *
 304  *    SilcCipher silc_acc_get_cipher(SilcAccelerator acc, SilcCipher cipher);
 305  *
 306  * DESCRIPTION
 307  *
 308  *    Returns the underlaying cipher from the accelerated cipher indicated
 309  *    by `cipher'.  Returns NULL if `cipher' is not accelerated cipher.
 310  *
 311  ***/
 312 SilcCipher silc_acc_get_cipher(SilcAccelerator acc, SilcCipher cipher);
 313
 314 #endif /* SILCACC_H */