5 Author: Pekka Riikonen <priikone@silcnet.org>
7 Copyright (C) 2007 - 2008 Pekka Riikonen
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.
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.
20 /****h* silcacc/Crypto Accelerator Interface
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
30 * Third-party accelerators can be registered into the accelerator interface
31 * and used through the same generic interface.
33 * The interface can be used to accelerate public and private keys, and
41 /****s* silcacc/SilcAccelerator
45 * typedef struct SilcAcceleratorObject { ... }
46 * *SilcAccelerator, SilcAcceleratorStruct;
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.
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 */
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 */
69 } *SilcAccelerator, SilcAcceleratorStruct;
71 /****f* silcacc/silc_acc_register
75 * SilcBool silc_acc_register(const SilcAccelerator acc);
79 * Register new accelerator to the accelerator library. The `acc'
80 * is the accelerator context to be registered.
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.
89 SilcBool silc_acc_register(const SilcAccelerator acc);
91 /****f* silcacc/silc_acc_unregister
95 * void silc_acc_unregister(SilcAccelerator acc);
99 * Unregister the accelerator `acc' from the accelerator library. The
100 * accelerator cannot be used anymore after this call has returned.
103 void silc_acc_unregister(SilcAccelerator acc);
105 /****f* silcacc/silc_acc_find
109 * SilcAccelerator silc_acc_find(const char *name);
113 * Find accelerator by its name indicated by `name'. Returns the
114 * accelerator context or NULL if such accelerator is not registered.
117 SilcAccelerator silc_acc_find(const char *name);
119 /****f* silcacc/silc_acc_init
123 * SilcBool silc_acc_init(SilcAccelerator acc, SilcSchedule schedule, ...);
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.
136 * silc_acc_init(softacc, schedule,
137 * "min_threads", 2, "max_threads", 16, NULL);
140 SilcBool silc_acc_init(SilcAccelerator acc, SilcSchedule schedule, ...);
142 /****f* silcacc/silc_acc_uninit
146 * SilcBool silc_acc_uninit(SilcAccelerator acc);
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.
156 SilcBool silc_acc_uninit(SilcAccelerator acc);
158 /****f* silcacc/silc_acc_get_supported
162 * SilcDList silc_acc_get_supported(void);
166 * Returns list of registered accelerators. The caller must free the
167 * returned list by calling silc_dlist_uninit.
170 SilcDList silc_acc_get_supported(void);
172 /****f* silcacc/silc_acc_get_name
176 * const char *silc_acc_get_name(SilcAccelerator acc);
180 * Returns the name of the accelerator `acc'.
183 const char *silc_acc_get_name(SilcAccelerator acc);
185 /****f* silcacc/silc_acc_public_key
189 * SilcPublicKey silc_acc_public_key(SilcAccelerator acc,
190 * SilcPublicKey public_key);
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
201 * The associated `public_key' can be retrieved from the returned
202 * public key by calling silc_acc_get_public_key.
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.
209 SilcPublicKey silc_acc_public_key(SilcAccelerator acc,
210 SilcPublicKey public_key);
212 /****f* silcacc/silc_acc_private_key
216 * SilcPrivateKey silc_acc_private_key(SilcAccelerator acc,
217 * SilcPrivateKey private_key);
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
228 * The associated `private_key' can be retrieved from the returned
229 * private key by calling silc_acc_get_private_key.
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.
236 SilcPrivateKey silc_acc_private_key(SilcAccelerator acc,
237 SilcPrivateKey private_key);
239 /****f* silcacc/silc_acc_get_public_key
243 * SilcPublicKey silc_acc_get_public_key(SilcAccelerator acc,
244 * SilcPublicKey public_key);
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.
253 SilcPublicKey silc_acc_get_public_key(SilcAccelerator acc,
254 SilcPublicKey public_key);
256 /****f* silcacc/silc_acc_get_private_key
260 * SilcPrivateKey silc_acc_get_private_key(SilcAccelerator acc,
261 * SilcPrivateKey private_key);
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.
270 SilcPrivateKey silc_acc_get_private_key(SilcAccelerator acc,
271 SilcPrivateKey private_key);
273 /****f* silcacc/silc_acc_cipher
277 * SilcCipher silc_acc_cipher(SilcAccelerator acc, SilcCipher cipher);
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.
287 * When key and IV is set for the accelerated cipher, it is also set to
288 * the associated cipher.
290 * The associated `cipher' can be retrieved from the accelerated cipher
291 * by calling silc_acc_get_cipher.
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.
298 SilcCipher silc_acc_cipher(SilcAccelerator acc, SilcCipher cipher);
300 /****f* silcacc/silc_acc_get_cipher
304 * SilcCipher silc_acc_get_cipher(SilcAccelerator acc, SilcCipher cipher);
308 * Returns the underlaying cipher from the accelerated cipher indicated
309 * by `cipher'. Returns NULL if `cipher' is not accelerated cipher.
312 SilcCipher silc_acc_get_cipher(SilcAccelerator acc, SilcCipher cipher);
314 #endif /* SILCACC_H */