lib/silcacc/silcacc.h

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