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 <silcacc.h>
  98 #ifdef SILC_DIST_SSH
  99 #include <silcssh.h>
 100 #endif /* SILC_DIST_SSH */
 101 #include <silcasn1.h>
 102 #include <silcber.h>
 103 #include <silcskr.h>
 104
 105 /****f* silccrypt/SilcCryptoAPI/silc_crypto_init
 106  *
 107  * SYNOPSIS
 108  *
 109  *    SilcBool silc_crypto_init(SilcStack stack);
 110  *
 111  * DESCRIPTION
 112  *
 113  *    Initialize SILC Crypto Toolkit.  This must be called once for every
 114  *    process.  It initializes all libraries and registers builtin algorithms
 115  *    to the crypto library.  If user wants to change the order of the
 116  *    registered algorithms, user can re-register them with their
 117  *    corresponding registering functions in the wanted order.
 118  *
 119  *    If `stack' is non-NULL, it will be used by some libraries as their main
 120  *    source for memory.  A child stack is created from the `stack'.  When
 121  *    silc_crypto_uninit is called the allocated memory is returned back to
 122  *    `stack' and the caller must then free `stack'.
 123  *
 124  *    Returns FALSE if the initialization failed.  If this happens the
 125  *    SILC Crypto Toolkit cannot be used.
 126  *
 127  ***/
 128 SilcBool silc_crypto_init(SilcStack stack);
 129
 130 /****f* silccrypt/SilcCryptoAPI/silc_crypto_uninit
 131  *
 132  * SYNOPSIS
 133  *
 134  *    void silc_crypto_uninit(void);
 135  *
 136  * DESCRIPTION
 137  *
 138  *    Uninitializes the SILC Crypto Toolkit.  This should be called at the
 139  *    of the process before it is exited.
 140  *
 141  ***/
 142 void silc_crypto_uninit(void);
 143
 144 /****f* silccrypt/SilcCryptoAPI/silc_crypto_stack
 145  *
 146  * SYNOPSIS
 147  *
 148  *    SilcStack silc_crypto_stack(void);
 149  *
 150  * DESCRIPTION
 151  *
 152  *    Returns the SILC Crypto Toolkit's global stack, the memory pool.
 153  *    Returns NULL if the stack does not exist.
 154  *
 155  *    A common way to use this is to allocate a child stack from the
 156  *    returned stack.  That operation is thread-safe, usually does not
 157  *    allocate any memory and is very fast.  Another way to use the stack
 158  *    is to push it when memory is needed and then pop it when it is not
 159  *    needed anymore.  Note however, that is not thread-safe if the stack
 160  *    is used in multi-threaded environment.
 161  *
 162  * EXAMPLE
 163  *
 164  *    SilcStack stack;
 165  *
 166  *    // Get child stack from global crypto stack
 167  *    stack = silc_stack_alloc(0, silc_crypto_stack());
 168  *    ...
 169  *
 170  *    // Return memory back to the global crypto stack
 171  *    silc_stack_free(stack);
 172  *
 173  ***/
 174 SilcStack silc_crypto_stack(void);
 175
 176 #ifdef __cplusplus
 177 }
 178 #endif
 179
 180 #endif /* SILCCRYPTO_H */