5 Author: Pekka Riikonen <priikone@silcnet.org>
7 Copyright (C) 2002 - 2006 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* silcapputil/SilcAppUtil/silc_create_key_pair
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);
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
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.
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'
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.
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);
90 /****f* silcapputil/SilcAppUtil/silc_load_key_pair
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);
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.
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);
116 /****f* silcapputil/SilcAppUtil/silc_show_public_key
120 * SilcBool silc_show_public_key(const char *pub_filename);
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.
129 SilcBool silc_show_public_key(const char *pub_filename);
131 /****f* silcapputil/SilcAppUtil/silc_change_private_key_passphrase
135 * SilcBool silc_change_private_key_passphrase(const char *prv_filename,
136 * const char *old_passphrase,
137 * const char *new_passphrase);
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
147 SilcBool silc_change_private_key_passphrase(const char *prv_filename,
148 const char *old_passphrase,
149 const char *new_passphrase);
152 /****f* silcapputil/SilcAppUtil/silc_identifier_check
157 * silc_identifier_check(const unsigned char *identifier,
158 * SilcUInt32 identifier_len,
159 * SilcStringEncoding identifier_encoding,
160 * SilcUInt32 max_allowed_length,
161 * SilcUInt32 *out_len);
165 * Checks that the 'identifier' string is valid identifier string
166 * and does not contain any unassigned or prohibited character. This
167 * function is used to check for valid nicknames, server names,
168 * usernames, hostnames, service names, algorithm names, other security
169 * property names, and SILC Public Key name.
171 * If the 'max_allowed_length' is non-zero the identifier cannot be
172 * longer than that, and NULL is returned if it is. If zero (0), no
173 * length limit exist. For nicknames the max length must be 128 bytes.
174 * Other identifiers has no default limit, but application may choose
177 * Returns the validated string, that the caller must free. Returns
178 * NULL if the identifier string is not valid or contain unassigned or
179 * prohibited characters. Such identifier strings must not be used
180 * SILC protocol. The returned string is always in UTF-8 encoding.
181 * The length of the returned string is in 'out_len'.
185 * In addition of validating the identifier string, this function
186 * may map characters to other characters or remove characters from the
187 * original string. This is done as defined in the SILC protocol. Error
188 * is returned only if the string contains unassigned or prohibited
189 * characters. The original 'identifier' is not modified at any point.
192 unsigned char *silc_identifier_check(const unsigned char *identifier,
193 SilcUInt32 identifier_len,
194 SilcStringEncoding identifier_encoding,
195 SilcUInt32 max_allowed_length,
196 SilcUInt32 *out_len);
198 /****f* silcapputil/SilcAppUtil/silc_identifier_verify
203 * silc_identifier_check(const unsigned char *identifier,
204 * SilcUInt32 identifier_len,
205 * SilcStringEncoding identifier_encoding,
206 * SilcUInt32 max_allowed_length);
210 * Checks that the 'identifier' string is valid identifier string
211 * and does not contain any unassigned or prohibited character. This
212 * function is used to check for valid nicknames, server names,
213 * usernames, hostnames, service names, algorithm names, other security
214 * property names, and SILC Public Key name.
216 * If the 'max_allowed_length' is non-zero the identifier cannot be
217 * longer than that, and NULL is returned if it is. If zero (0), no
218 * length limit exist. For nicknames the max length must be 128 bytes.
219 * Other identifiers has no default limit, but application may choose
222 * Returns TRUE if the string is valid and FALSE if it is prohibited.
225 SilcBool silc_identifier_verify(const unsigned char *identifier,
226 SilcUInt32 identifier_len,
227 SilcStringEncoding identifier_encoding,
228 SilcUInt32 max_allowed_length);
230 /****f* silcapputil/SilcAppUtil/silc_channel_name_check
235 * silc_channel_name_check(const unsigned char *identifier,
236 * SilcUInt32 identifier_len,
237 * SilcStringEncoding identifier_encoding,
238 * SilcUInt32 max_allowed_length,
239 * SilcUInt32 *out_len);
243 * Checks that the 'identifier' string is valid channel name string
244 * and does not contain any unassigned or prohibited character.
246 * If the 'max_allowed_length' is non-zero the identifier cannot be
247 * longer than that, and NULL is returned if it is. If zero (0), no
248 * length limit exist. For channel names the max length must be 256
251 * Returns the validated string, that the caller must free. Returns
252 * NULL if the identifier string is not valid or contain unassigned or
253 * prohibited characters. Such identifier strings must not be used
254 * SILC protocol. The returned string is always in UTF-8 encoding.
255 * The length of the returned string is in 'out_len'.
259 * In addition of validating the channel name string, this function
260 * may map characters to other characters or remove characters from the
261 * original string. This is done as defined in the SILC protocol. Error
262 * is returned only if the string contains unassigned or prohibited
263 * characters. The original 'identifier' is not modified at any point.
266 unsigned char *silc_channel_name_check(const unsigned char *identifier,
267 SilcUInt32 identifier_len,
268 SilcStringEncoding identifier_encoding,
269 SilcUInt32 max_allowed_length,
270 SilcUInt32 *out_len);
272 /****f* silcapputil/SilcAppUtil/silc_channel_name_verify
277 * silc_channel_name_check(const unsigned char *identifier,
278 * SilcUInt32 identifier_len,
279 * SilcStringEncoding identifier_encoding,
280 * SilcUInt32 max_allowed_length);
284 * Checks that the 'identifier' string is valid channel name string
285 * and does not contain any unassigned or prohibited character.
287 * If the 'max_allowed_length' is non-zero the identifier cannot be
288 * longer than that, and NULL is returned if it is. If zero (0), no
289 * length limit exist. For channel names the max length must be 256
292 * Returns TRUE if the string is valid and FALSE if it is prohibited.
295 SilcBool silc_channel_name_verify(const unsigned char *identifier,
296 SilcUInt32 identifier_len,
297 SilcStringEncoding identifier_encoding,
298 SilcUInt32 max_allowed_length);
300 #endif /* SILCAPPUTIL_H */