lib/silcutil/silcapputil.h

   1 /*
   2
   3   silcapputil.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 2002 - 2005 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  *    SilcBool 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  *                                  const char *passphrase,
  48  *                                  SilcPublicKey *return_public_key,
  49  *                                  SilcPrivateKey *return_private_key,
  50  *                                  SilcBool 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 `passphrase' is the passphrase that is used to encrypt the
  64  *    private key file.  It is recommended that you would protect your
  65  *    private key file with a passphrase.
  66  *
  67  *    If the `interactive' is TRUE then this asks the user (by blocking
  68  *    the process for input) some questions about key generation (like
  69  *    public key algorithm, key length, filenames, etc).  If all
  70  *    arguments are provided to this function already then `interactive'
  71  *    has no effect.
  72  *
  73  * NOTES
  74  *
  75  *    Before calling this function the application must have initialized
  76  *    the crypto library by registering the public key algorithms with
  77  *    silc_pkcs_register_default function.
  78  *
  79  ***/
  80 SilcBool silc_create_key_pair(const char *pkcs_name,
  81                               SilcUInt32 key_len_bits,
  82                               const char *pub_filename,
  83                               const char *prv_filename,
  84                               const char *pub_identifier,
  85                               const char *passphrase,
  86                               SilcPublicKey *return_public_key,
  87                               SilcPrivateKey *return_private_key,
  88                               SilcBool interactive);
  89
  90 /****f* silcutil/SilcAppUtil/silc_load_key_pair
  91  *
  92  * SYNOPSIS
  93  *
  94  *    SilcBool silc_load_key_pair(const char *pub_filename,
  95  *                                const char *prv_filename,
  96  *                                const char *passphrase,
  97  *                                SilcPublicKey *return_public_key,
  98  *                                SilcPrivateKey *return_private_key);
  99  *
 100  * DESCRIPTION
 101  *
 102  *    This routine can be used to load the public key and private key
 103  *    from files.  This retuns FALSE it either of the key could not be
 104  *    loaded.  This function returns TRUE on success and returns the
 105  *    public key into `return_public_key' pointer and private key into
 106  *    `return_private_key'.  The `passphrase' is the passphrase which
 107  *    will be used to decrypt the private key file.
 108  *
 109  ***/
 110 SilcBool silc_load_key_pair(const char *pub_filename,
 111                             const char *prv_filename,
 112                             const char *passphrase,
 113                             SilcPublicKey *return_public_key,
 114                             SilcPrivateKey *return_private_key);
 115
 116 /****f* silcutil/SilcAppUtil/silc_show_public_key
 117  *
 118  * SYNOPSIS
 119  *
 120  *    SilcBool silc_show_public_key(const char *pub_filename);
 121  *
 122  * DESCRIPTION
 123  *
 124  *    This routine can be used to dump the contents of the public key
 125  *    in the public key file `pub_filename'.  This dumps the public key
 126  *    into human readable form into stdout.  Returns FALSE on error.
 127  *
 128  ***/
 129 SilcBool silc_show_public_key(const char *pub_filename);
 130
 131 /****f* silcutil/SilcAppUtil/silc_change_private_key_passphrase
 132  *
 133  * SYNOPSIS
 134  *
 135  *    SilcBool silc_change_private_key_passphrase(const char *prv_filename,
 136  *                                                const char *old_passphrase,
 137  *                                                const char *new_passphrase);
 138  *
 139  * DESCRIPTION
 140  *
 141  *    This routine can be used to change the passphrase of the private
 142  *    key file, which is used to encrypt the private key.  If the old
 143  *    and new passphrase is not provided for this function this will
 144  *    prompt for them.
 145  *
 146  ***/
 147 SilcBool silc_change_private_key_passphrase(const char *prv_filename,
 148                                             const char *old_passphrase,
 149                                             const char *new_passphrase);
 150
 151 #endif /* SILCAPPUTIL_H */