5 Author: Pekka Riikonen <priikone@silcnet.org>
7 Copyright (C) 2002 Pekka Riikonen
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.
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.
20 /****h* silcutil/SILC Application Utilities
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.
38 /****f* silcutil/SilcAppUtil/silc_create_key_pair
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 * const char *passphrase,
48 * SilcPKCS *return_pkcs,
49 * SilcPublicKey *return_public_key,
50 * SilcPrivateKey *return_private_key,
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
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.
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.
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'
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.
87 bool 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,
98 /****f* silcutil/SilcAppUtil/silc_load_key_pair
102 * bool 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);
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.
121 bool 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);
128 /****f* silcutil/SilcAppUtil/silc_show_public_key
132 * bool silc_show_public_key(const char *pub_filename);
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.
141 bool silc_show_public_key(const char *pub_filename);
143 /****f* silcutil/SilcAppUtil/silc_change_private_key_passphrase
147 * bool silc_change_private_key_passphrase(const char *prv_filename,
148 * const char *old_passphrase,
149 * const char *new_passphrase);
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
159 bool silc_change_private_key_passphrase(const char *prv_filename,
160 const char *old_passphrase,
161 const char *new_passphrase);
163 #endif /* SILCAPPUTIL_H */