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  *    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  *                              SilcPKCS *return_pkcs,
  49  *                              SilcPublicKey *return_public_key,
  50  *                              SilcPrivateKey *return_private_key,
  51  *                              SilcBool interactive);
  52  *
  53  * DESCRIPTION
  54  *
  55  *    This routine can be used to generate new public key and private key
  56  *    pair.  The `pkcs_name' is the name of public key algorithm, or if
  57  *    NULL it defaults to "rsa".  The `key_len_bits' is the key length
  58  *    in bits and if zero (0) it defaults to 2048 bits.  The `pub_filename'
  59  *    and `prv_filename' is the public key and private key filenames.
  60  *    The `pub_identifier' is the public key identifier (for example:
  61  *    "UN=foobar, HN=hostname"), or if NULL the routine generates it
  62  *    automatically.
  63  *
  64  *    The `passphrase' is the passphrase that is used to encrypt the
  65  *    private key file.  It is recommended that you would protect your
  66  *    private key file with a passphrase.
  67  *
  68  *    The routine returns FALSE if error occurs during key generation.
  69  *    Function returns TRUE when success and returns the created SilcPKCS
  70  *    object, which can be used to perform public key cryptography into
  71  *    `return_pkcs' pointer, created public key into `return_public_key',
  72  *    and created private key into `return_private_key' pointer.
  73  *
  74  *    If the `interactive' is TRUE then this asks the user (by blocking
  75  *    the process for input) some questions about key generation (like
  76  *    public key algorithm, key length, filenames, etc).  If all
  77  *    arguments are provided to this function already then `interactive'
  78  *    has no effect.
  79  *
  80  * NOTES
  81  *
  82  *    Before calling this function the application must have initialized
  83  *    the crypto library by registering the public key algorithms with
  84  *    silc_pkcs_register_default function.
  85  *
  86  ***/
  87 SilcBool silc_create_key_pair(const char *pkcs_name,
  88                           SilcUInt32 key_len_bits,
  89                           const char *pub_filename,
  90                           const char *prv_filename,
  91                           const char *pub_identifier,
  92                           const char *passphrase,
  93                           SilcPKCS *return_pkcs,
  94                           SilcPublicKey *return_public_key,
  95                           SilcPrivateKey *return_private_key,
  96                           SilcBool interactive);
  97
  98 /****f* silcutil/SilcAppUtil/silc_load_key_pair
  99  *
 100  * SYNOPSIS
 101  *
 102  *    SilcBool silc_load_key_pair(const char *pub_filename,
 103  *                            const char *prv_filename,
 104  *                            const char *passphrase,
 105  *                            SilcPKCS *return_pkcs,
 106  *                            SilcPublicKey *return_public_key,
 107  *                            SilcPrivateKey *return_private_key);
 108  *
 109  * DESCRIPTION
 110  *
 111  *    This routine can be used to load the public key and private key
 112  *    from files.  This retuns FALSE it either of the key could not be
 113  *    loaded.  This function returns TRUE on success and returns the
 114  *    public key into `return_public_key' pointer, private key into
 115  *    `return_private_key' pointer and the SilcPKCS object to the
 116  *    `return_pkcs'.  The SilcPKCS can be used to perform public key
 117  *    cryptographic operations.  The `passphrase' is the passphrase
 118  *    which will be used to decrypt the private key file.
 119  *
 120  ***/
 121 SilcBool silc_load_key_pair(const char *pub_filename,
 122                         const char *prv_filename,
 123                         const char *passphrase,
 124                         SilcPKCS *return_pkcs,
 125                         SilcPublicKey *return_public_key,
 126                         SilcPrivateKey *return_private_key);
 127
 128 /****f* silcutil/SilcAppUtil/silc_show_public_key
 129  *
 130  * SYNOPSIS
 131  *
 132  *    SilcBool silc_show_public_key(const char *pub_filename);
 133  *
 134  * DESCRIPTION
 135  *
 136  *    This routine can be used to dump the contents of the public key
 137  *    in the public key file `pub_filename'.  This dumps the public key
 138  *    into human readable form into stdout.  Returns FALSE on error.
 139  *
 140  ***/
 141 SilcBool silc_show_public_key(const char *pub_filename);
 142
 143 /****f* silcutil/SilcAppUtil/silc_change_private_key_passphrase
 144  *
 145  * SYNOPSIS
 146  *
 147  *    SilcBool silc_change_private_key_passphrase(const char *prv_filename,
 148  *                                            const char *old_passphrase,
 149  *                                            const char *new_passphrase);
 150  *
 151  * DESCRIPTION
 152  *
 153  *    This routine can be used to change the passphrase of the private
 154  *    key file, which is used to encrypt the private key.  If the old
 155  *    and new passphrase is not provided for this function this will
 156  *    prompt for them.
 157  *
 158  ***/
 159 SilcBool silc_change_private_key_passphrase(const char *prv_filename,
 160                                         const char *old_passphrase,
 161                                         const char *new_passphrase);
 162
 163 #endif /* SILCAPPUTIL_H */