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* 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 /* Version check macro. Use this to check that package is of specific
48 version compile time. Use the __SILC_XXX_VERSION below in comparison.
51 #if __SILC_CRYPTO_VERSION < SILC_VERSION(1,2,0)
56 #define SILC_VERSION(a, b, c) (((a) << 24) + ((b) << 16) + ((c) << 8)
57 #endif /* !SILC_VERSION */
59 /* SILC Crypto Toolkit version */
60 @__CRYPTO_PACKAGE_VERSION@
66 /* We except all systems to have these include files */
71 #if defined(HAVE_CRYPTODEFS_H)
72 /* Automatically generated configuration header. These are included only
73 when the SILC Crypto Toolkit itself is compiled. */
75 #include "cryptodefs.h"
77 #include "../../symbian/silcdefs.h"
78 #endif /* SILC_SYMBIAN */
79 #include "silcdistdefs.h"
80 #include "silccompile.h"
81 #endif /* HAVE_CRYPTODEFS_H */
83 /* SILC Runtime Toolkit include */
84 #include <silcruntime.h>
86 /* SILC Crypto Toolkit includes */
89 #include <silccrypto.h>
90 #include <silccipher.h>
96 #include <silcpkcs1.h>
104 #endif /* SILC_DIST_SSH */
107 #endif /* SILC_DIST_PGP */
109 /****f* silccrypt/SilcCryptoAPI/silc_crypto_init
113 * SilcBool silc_crypto_init(SilcStack stack);
117 * Initialize SILC Crypto Toolkit. This must be called once for every
118 * process. It initializes all libraries and registers builtin algorithms
119 * to the crypto library. If user wants to change the order of the
120 * registered algorithms, user can re-register them with their
121 * corresponding registering functions in the wanted order.
123 * If `stack' is non-NULL, it will be used by some libraries as their main
124 * source for memory. A child stack is created from the `stack'. When
125 * silc_crypto_uninit is called the allocated memory is returned back to
126 * `stack' and the caller must then free `stack'.
128 * Returns FALSE if the initialization failed. If this happens the
129 * SILC Crypto Toolkit cannot be used.
132 SilcBool silc_crypto_init(SilcStack stack);
134 /****f* silccrypt/SilcCryptoAPI/silc_crypto_uninit
138 * void silc_crypto_uninit(void);
142 * Uninitializes the SILC Crypto Toolkit. This should be called at the
143 * of the process before it is exited.
146 void silc_crypto_uninit(void);
148 /****f* silccrypt/SilcCryptoAPI/silc_crypto_stack
152 * SilcStack silc_crypto_stack(void);
156 * Returns the SILC Crypto Toolkit's global stack, the memory pool.
157 * Returns NULL if the stack does not exist.
159 * A common way to use this is to allocate a child stack from the
160 * returned stack. That operation is thread-safe, usually does not
161 * allocate any memory and is very fast. Another way to use the stack
162 * is to push it when memory is needed and then pop it when it is not
163 * needed anymore. Note however, that is not thread-safe if the stack
164 * is used in multi-threaded environment.
170 * // Get child stack from global crypto stack
171 * stack = silc_stack_alloc(0, silc_crypto_stack());
174 * // Return memory back to the global crypto stack
175 * silc_stack_free(stack);
178 SilcStack silc_crypto_stack(void);
184 #endif /* SILCCRYPTO_H */