5 Author: Pekka Riikonen <priikone@silcnet.org>
7 Copyright (C) 2007 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* silccrypt/SILC Crypto Toolkit API
24 * This interface is used to initialize and uninitialize the SILC Crypto
25 * Toolkit. SILC Crypto Toolkit is initialized by calling the
26 * silc_crypto_init function. It needs to be called only once per-process
27 * but must be called before any crypto functions are used.
29 * In initialization all builtin ciphers, hash functions, HMACs, PKCSs
30 * and other algorithms will be registered to the crypto library. If user
31 * wants to register new algorithms or change the order of the automatically
32 * registered algorithms, user can do this by re-registering the algorithms
35 * A global SilcStack, a memory pool, can be associated with the Crypto
36 * Toolkit. If it is set in initialization, all routines in the Crypto
37 * Toolkit will use that stack as its memory source. Some interfaces and
38 * libraries in the SILC Crypto Toolkit support also providing the SilcStack
39 * as an additional argument, in which case a different stack from the global
47 /****f* silccrypt/SilcCryptoAPI/silc_crypto_init
51 * SilcBool silc_crypto_init(SilcStack stack);
55 * Initialize SILC Crypto Toolkit. This must be called once for every
56 * process. It initializes all libraries and registers builtin algorithms
57 * to the crypto library. If user wants to change the order of the
58 * registered algorithms, user can re-register them with their
59 * corresponding registering functions in the wanted order.
61 * If `stack' is non-NULL, it will be used by some libraries as their main
62 * source for memory. A child stack is created from the `stack'. When
63 * silc_crypto_uninit is called the allocated memory is returned back to
64 * `stack' and the caller must then free `stack'.
66 * Returns FALSE if the initialization failed. If this happens the
67 * SILC Crypto Toolkit cannot be used.
70 SilcBool silc_crypto_init(SilcStack stack);
72 /****f* silccrypt/SilcCryptoAPI/silc_crypto_uninit
76 * void silc_crypto_uninit(void);
80 * Uninitializes the SILC Crypto Toolkit. This should be called at the
81 * of the process before it is exited.
84 void silc_crypto_uninit(void);
86 /****f* silccrypt/SilcCryptoAPI/silc_crypto_stack
90 * SilcStack silc_crypto_stack(void);
94 * Returns the SILC Crypto Toolkit's global stack, the memory pool.
95 * Returns NULL if the stack does not exist.
97 * A common way to use this is to allocate a child stack from the
98 * returned stack. That operation is thread-safe, usually does not
99 * allocate any memory and is very fast. Another way to use the stack
100 * is to push it when memory is needed and then pop it when it is not
101 * needed anymore. Note however, that is not thread-safe if the stack
102 * is used in multi-threaded environment.
108 * // Get child stack from global crypto stack
109 * stack = silc_stack_alloc(0, silc_crypto_stack());
112 * // Return memory back to the global crypto stack
113 * silc_stack_free(stack);
116 SilcStack silc_crypto_stack(void);
118 #endif /* SILCCRYPTO_H */