lib/silccrypt/silccrypto.h

   1 /*
   2
   3   silccrypto.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 2007 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 /****f* silccrypt/SilcCryptoAPI/silc_crypto_init
  48  *
  49  * SYNOPSIS
  50  *
  51  *    SilcBool silc_crypto_init(SilcStack stack);
  52  *
  53  * DESCRIPTION
  54  *
  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.
  60  *
  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'.
  65  *
  66  *    Returns FALSE if the initialization failed.  If this happens the
  67  *    SILC Crypto Toolkit cannot be used.
  68  *
  69  ***/
  70 SilcBool silc_crypto_init(SilcStack stack);
  71
  72 /****f* silccrypt/SilcCryptoAPI/silc_crypto_uninit
  73  *
  74  * SYNOPSIS
  75  *
  76  *    void silc_crypto_uninit(void);
  77  *
  78  * DESCRIPTION
  79  *
  80  *    Uninitializes the SILC Crypto Toolkit.  This should be called at the
  81  *    of the process before it is exited.
  82  *
  83  ***/
  84 void silc_crypto_uninit(void);
  85
  86 /****f* silccrypt/SilcCryptoAPI/silc_crypto_stack
  87  *
  88  * SYNOPSIS
  89  *
  90  *    SilcStack silc_crypto_stack(void);
  91  *
  92  * DESCRIPTION
  93  *
  94  *    Returns the SILC Crypto Toolkit's global stack, the memory pool.
  95  *    Returns NULL if the stack does not exist.
  96  *
  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.
 103  *
 104  * EXAMPLE
 105  *
 106  *    SilcStack stack;
 107  *
 108  *    // Get child stack from global crypto stack
 109  *    stack = silc_stack_alloc(0, silc_crypto_stack());
 110  *    ...
 111  *
 112  *    // Return memory back to the global crypto stack
 113  *    silc_stack_free(stack);
 114  *
 115  ***/
 116 SilcStack silc_crypto_stack(void);
 117
 118 #endif /* SILCCRYPTO_H */