lib/silccrypt/silccrypto.h.in

   1 /*
   2
   3   silccrypto.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* silccrypt/SILC Crypto Toolkit API
  21  *
  22  * DESCRIPTION
  23  *
  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.
  28  *
  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
  33  * in desired order.
  34  *
  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
  40  * one can be used.
  41  *
  42  ***/
  43
  44 #ifndef SILCCRYPTO_H
  45 #define SILCCRYPTO_H
  46
  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.
  49    Example:
  50
  51    #if __SILC_CRYPTO_VERSION < SILC_VERSION(1,2,0)
  52      ...
  53    #endif
  54 */
  55 #ifndef SILC_VERSION
  56 #define SILC_VERSION(a, b, c) (((a) << 24) + ((b) << 16) + ((c) << 8)
  57 #endif /* !SILC_VERSION */
  58
  59 /* SILC Crypto Toolkit version */
  60 @__CRYPTO_PACKAGE_VERSION@
  61
  62 #ifdef __cplusplus
  63 extern "C" {
  64 #endif
  65
  66 /* We except all systems to have these include files */
  67 #include <stdio.h>
  68 #include <stdlib.h>
  69 #include <string.h>
  70
  71 #if defined(HAVE_CRYPTODEFS_H)
  72 /* Automatically generated configuration header.  These are included only
  73    when the SILC Crypto Toolkit itself is compiled. */
  74 #ifndef SILC_SYMBIAN
  75 #include "cryptodefs.h"
  76 #else
  77 #include "../../symbian/silcdefs.h"
  78 #endif /* SILC_SYMBIAN */
  79 #include "silcdistdefs.h"
  80 #include "silccompile.h"
  81 #endif /* HAVE_CRYPTODEFS_H */
  82
  83 /* SILC Runtime Toolkit include */
  84 #include <silcruntime.h>
  85
  86 /* SILC Crypto Toolkit includes */
  87 #include <silcmp.h>
  88 #include <silcmath.h>
  89 #include <silccrypto.h>
  90 #include <silccipher.h>
  91 #include <silchash.h>
  92 #include <silchmac.h>
  93 #include <silcrng.h>
  94 #include <silcpkcs.h>
  95 #include <silcpk.h>
  96 #include <silcpkcs1.h>
  97 #include <silcasn1.h>
  98 #include <silcber.h>
  99 #include <silcskr.h>
 100 #include <silcacc.h>
 101 #ifdef SILC_DIST_SSH
 102 #include <silcssh.h>
 103 #endif /* SILC_DIST_SSH */
 104 #ifdef SILC_DIST_PGP
 105 #include <silcpgp.h>
 106 #endif /* SILC_DIST_PGP */
 107
 108 /****f* silccrypt/SilcCryptoAPI/silc_crypto_init
 109  *
 110  * SYNOPSIS
 111  *
 112  *    SilcBool silc_crypto_init(SilcStack stack);
 113  *
 114  * DESCRIPTION
 115  *
 116  *    Initialize SILC Crypto Toolkit.  This must be called once for every
 117  *    process.  It initializes all libraries and registers builtin algorithms
 118  *    to the crypto library.  If user wants to change the order of the
 119  *    registered algorithms, user can re-register them with their
 120  *    corresponding registering functions in the wanted order.
 121  *
 122  *    If `stack' is non-NULL, it will be used by some libraries as their main
 123  *    source for memory.  A child stack is created from the `stack'.  When
 124  *    silc_crypto_uninit is called the allocated memory is returned back to
 125  *    `stack' and the caller must then free `stack'.
 126  *
 127  *    Returns FALSE if the initialization failed.  If this happens the
 128  *    SILC Crypto Toolkit cannot be used.
 129  *
 130  ***/
 131 SilcBool silc_crypto_init(SilcStack stack);
 132
 133 /****f* silccrypt/SilcCryptoAPI/silc_crypto_uninit
 134  *
 135  * SYNOPSIS
 136  *
 137  *    void silc_crypto_uninit(void);
 138  *
 139  * DESCRIPTION
 140  *
 141  *    Uninitializes the SILC Crypto Toolkit.  This should be called at the
 142  *    of the process before it is exited.
 143  *
 144  ***/
 145 void silc_crypto_uninit(void);
 146
 147 /****f* silccrypt/SilcCryptoAPI/silc_crypto_stack
 148  *
 149  * SYNOPSIS
 150  *
 151  *    SilcStack silc_crypto_stack(void);
 152  *
 153  * DESCRIPTION
 154  *
 155  *    Returns the SILC Crypto Toolkit's global stack, the memory pool.
 156  *    Returns NULL if the stack does not exist.
 157  *
 158  *    A common way to use this is to allocate a child stack from the
 159  *    returned stack.  That operation is thread-safe, usually does not
 160  *    allocate any memory and is very fast.  Another way to use the stack
 161  *    is to push it when memory is needed and then pop it when it is not
 162  *    needed anymore.  Note however, that is not thread-safe if the stack
 163  *    is used in multi-threaded environment.
 164  *
 165  * EXAMPLE
 166  *
 167  *    SilcStack stack;
 168  *
 169  *    // Get child stack from global crypto stack
 170  *    stack = silc_stack_alloc(0, silc_crypto_stack());
 171  *    ...
 172  *
 173  *    // Return memory back to the global crypto stack
 174  *    silc_stack_free(stack);
 175  *
 176  ***/
 177 SilcStack silc_crypto_stack(void);
 178
 179 #ifdef __cplusplus
 180 }
 181 #endif
 182
 183 #endif /* SILCCRYPTO_H */