lib/silcutil/silcapputil.h

   1 /*
   2
   3   silcapputil.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 2002 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* silcutil/SILC Application Utilities
  21  *
  22  * DESCRIPTION
  23  *
  24  * This interface provides utility functions for applications'
  25  * convenience.  It provides functions that may be used for example by
  26  * command line applications but also other applications may find some
  27  * routines helpful.  None of these routines are mandatory in any other
  28  * SILC routines or libraries, and are purely provided for convenience.
  29  * These routines for example provide simple public key and private key
  30  * pair generation, public key and private key file saving and loading
  31  * for application, and other similar routines.
  32  *
  33  ***/
  34
  35 #ifndef SILCAPPUTIL_H
  36 #define SILCAPPUTIL_H
  37
  38 /****f* silcutil/SilcAppUtil/silc_create_key_pair
  39  *
  40  * SYNOPSIS
  41  *
  42  *    bool silc_create_key_pair(const char *pkcs_name,
  43  *                              SilcUInt32 key_len_bits,
  44  *                              const char *pub_filename,
  45  *                              const char *prv_filename,
  46  *                              const char *pub_identifier,
  47  *                              SilcPKCS *return_pkcs,
  48  *                              SilcPublicKey *return_public_key,
  49  *                              SilcPrivateKey *return_private_key,
  50  *                              bool interactive);
  51  *
  52  * DESCRIPTION
  53  *
  54  *    This routine can be used to generate new public key and private key
  55  *    pair.  The `pkcs_name' is the name of public key algorithm, or if
  56  *    NULL it defaults to "rsa".  The `key_len_bits' is the key length
  57  *    in bits and if zero (0) it defaults to 2048 bits.  The `pub_filename'
  58  *    and `prv_filename' is the public key and private key filenames.
  59  *    The `pub_identifier' is the public key identifier (for example:
  60  *    "UN=foobar, HN=hostname"), or if NULL the routine generates it
  61  *    automatically.
  62  *
  63  *    The routine returns FALSE if error occurs during key generation.
  64  *    Function returns TRUE when success and returns the created SilcPKCS
  65  *    object, which can be used to perform public key cryptography into
  66  *    `return_pkcs' pointer, created public key into `return_public_key',
  67  *    and created private key into `return_private_key' pointer.
  68  *
  69  *    If the `interactive' is TRUE then this asks the user (by blocking
  70  *    the process for input) some questions about key generation (like
  71  *    public key algorithm, key length, filenames, etc).  If all
  72  *    arguments are provided to this function already then `interactive'
  73  *    has no effect.
  74  *
  75  * NOTES
  76  *
  77  *    Before calling this function the application must have initialized
  78  *    the crypto library by registering the public key algorithms with
  79  *    silc_pkcs_register_default function.
  80  *
  81  ***/
  82 bool silc_create_key_pair(const char *pkcs_name,
  83                           SilcUInt32 key_len_bits,
  84                           const char *pub_filename,
  85                           const char *prv_filename,
  86                           const char *pub_identifier,
  87                           SilcPKCS *return_pkcs,
  88                           SilcPublicKey *return_public_key,
  89                           SilcPrivateKey *return_private_key,
  90                           bool interactive);
  91
  92 /****f* silcutil/SilcAppUtil/silc_load_key_pair
  93  *
  94  * SYNOPSIS
  95  *
  96  *    bool silc_load_key_pair(const char *pub_filename,
  97  *                            const char *prv_filename,
  98  *                            SilcPKCS *return_pkcs,
  99  *                            SilcPublicKey *return_public_key,
 100  *                            SilcPrivateKey *return_private_key);
 101  *
 102  * DESCRIPTION
 103  *
 104  *    This routine can be used to load the public key and private key
 105  *    from files.  This retuns FALSE it either of the key could not be
 106  *    loaded.  This function returns TRUE on success and returns the
 107  *    public key into `return_public_key' pointer, private key into
 108  *    `return_private_key' pointer and the SilcPKCS object to the
 109  *    `return_pkcs'.  The SilcPKCS can be used to perform public key
 110  *    cryptographic operations.
 111  *
 112  ***/
 113 bool silc_load_key_pair(const char *pub_filename,
 114                         const char *prv_filename,
 115                         SilcPKCS *return_pkcs,
 116                         SilcPublicKey *return_public_key,
 117                         SilcPrivateKey *return_private_key);
 118
 119 /****f* silcutil/SilcAppUtil/silc_show_public_key
 120  *
 121  * SYNOPSIS
 122  *
 123  *    bool silc_show_public_key(const char *pub_filename);
 124  *
 125  * DESCRIPTION
 126  *
 127  *    This routine can be used to dump the contents of the public key
 128  *    in the public key file `pub_filename'.  This dumps the public key
 129  *    into human readable form into stdout.  Returns FALSE on error.
 130  *
 131  ***/
 132 bool silc_show_public_key(const char *pub_filename);
 133
 134 #endif /* SILCAPPUTIL_H */