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* silcapputil/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
61 * automatically. The `return_public_key' and `return_private_key' may
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 * If the `interactive' is TRUE then this asks the user (by blocking
69 * the process for input) some questions about key generation (like
70 * public key algorithm, key length, filenames, etc). If all
71 * arguments are provided to this function already then `interactive'
76 * Before calling this function the application must have initialized
77 * the crypto library by registering the public key algorithms with
78 * silc_pkcs_register_default function.
81 SilcBool silc_create_key_pair(const char *pkcs_name,
82 SilcUInt32 key_len_bits,
83 const char *pub_filename,
84 const char *prv_filename,
85 const char *pub_identifier,
86 const char *passphrase,
87 SilcPublicKey *return_public_key,
88 SilcPrivateKey *return_private_key,
89 SilcBool interactive);
91 /****f* silcapputil/SilcAppUtil/silc_load_key_pair
95 * SilcBool silc_load_key_pair(const char *pub_filename,
96 * const char *prv_filename,
97 * const char *passphrase,
98 * SilcPublicKey *return_public_key,
99 * SilcPrivateKey *return_private_key);
103 * This routine can be used to load the public key and private key
104 * from files. This retuns FALSE it either of the key could not be
105 * loaded. This function returns TRUE on success and returns the
106 * public key into `return_public_key' pointer and private key into
107 * `return_private_key'. The `passphrase' is the passphrase which
108 * will be used to decrypt the private key file.
111 SilcBool silc_load_key_pair(const char *pub_filename,
112 const char *prv_filename,
113 const char *passphrase,
114 SilcPublicKey *return_public_key,
115 SilcPrivateKey *return_private_key);
117 /****f* silcapputil/SilcAppUtil/silc_show_public_key
121 * SilcBool silc_show_public_key(SilcPublicKey public_key);
125 * This routine can be used to dump the SILC public key into human
126 * readable form into stdout. Returns FALSE on error.
129 SilcBool silc_show_public_key(SilcPublicKey public_key);
131 /****f* silcapputil/SilcAppUtil/silc_show_public_key_file
135 * SilcBool silc_show_public_key_file(const char *pub_filename);
139 * This routine can be used to dump the contents of the public key
140 * in the public key file `pub_filename'. This dumps the public key
141 * into human readable form into stdout. Returns FALSE on error.
144 SilcBool silc_show_public_key_file(const char *pub_filename);
146 /****f* silcapputil/SilcAppUtil/silc_change_private_key_passphrase
150 * SilcBool silc_change_private_key_passphrase(const char *prv_filename,
151 * const char *old_passphrase,
152 * const char *new_passphrase);
156 * This routine can be used to change the passphrase of the private
157 * key file, which is used to encrypt the private key. If the old
158 * and new passphrase is not provided for this function this will
162 SilcBool silc_change_private_key_passphrase(const char *prv_filename,
163 const char *old_passphrase,
164 const char *new_passphrase);
167 /****f* silcapputil/SilcAppUtil/silc_identifier_check
172 * silc_identifier_check(const unsigned char *identifier,
173 * SilcUInt32 identifier_len,
174 * SilcStringEncoding identifier_encoding,
175 * SilcUInt32 max_allowed_length,
176 * SilcUInt32 *out_len);
180 * Checks that the 'identifier' string is valid identifier string
181 * and does not contain any unassigned or prohibited character. This
182 * function is used to check for valid nicknames, server names,
183 * usernames, hostnames, service names, algorithm names, other security
184 * property names, and SILC Public Key name.
186 * If the 'max_allowed_length' is non-zero the identifier cannot be
187 * longer than that, and NULL is returned if it is. If zero (0), no
188 * length limit exist. For nicknames the max length must be 128 bytes.
189 * Other identifiers has no default limit, but application may choose
192 * Returns the validated string, that the caller must free. Returns
193 * NULL if the identifier string is not valid or contain unassigned or
194 * prohibited characters. Such identifier strings must not be used
195 * SILC protocol. The returned string is always in UTF-8 encoding.
196 * The length of the returned string is in 'out_len'.
200 * In addition of validating the identifier string, this function
201 * may map characters to other characters or remove characters from the
202 * original string. This is done as defined in the SILC protocol. Error
203 * is returned only if the string contains unassigned or prohibited
204 * characters. The original 'identifier' is not modified at any point.
207 unsigned char *silc_identifier_check(const unsigned char *identifier,
208 SilcUInt32 identifier_len,
209 SilcStringEncoding identifier_encoding,
210 SilcUInt32 max_allowed_length,
211 SilcUInt32 *out_len);
213 /****f* silcapputil/SilcAppUtil/silc_identifier_verify
218 * silc_identifier_check(const unsigned char *identifier,
219 * SilcUInt32 identifier_len,
220 * SilcStringEncoding identifier_encoding,
221 * SilcUInt32 max_allowed_length);
225 * Checks that the 'identifier' string is valid identifier string
226 * and does not contain any unassigned or prohibited character. This
227 * function is used to check for valid nicknames, server names,
228 * usernames, hostnames, service names, algorithm names, other security
229 * property names, and SILC Public Key name.
231 * If the 'max_allowed_length' is non-zero the identifier cannot be
232 * longer than that, and NULL is returned if it is. If zero (0), no
233 * length limit exist. For nicknames the max length must be 128 bytes.
234 * Other identifiers has no default limit, but application may choose
237 * Returns TRUE if the string is valid and FALSE if it is prohibited.
240 SilcBool silc_identifier_verify(const unsigned char *identifier,
241 SilcUInt32 identifier_len,
242 SilcStringEncoding identifier_encoding,
243 SilcUInt32 max_allowed_length);
245 /****f* silcapputil/SilcAppUtil/silc_channel_name_check
250 * silc_channel_name_check(const unsigned char *identifier,
251 * SilcUInt32 identifier_len,
252 * SilcStringEncoding identifier_encoding,
253 * SilcUInt32 max_allowed_length,
254 * SilcUInt32 *out_len);
258 * Checks that the 'identifier' string is valid channel name string
259 * and does not contain any unassigned or prohibited character.
261 * If the 'max_allowed_length' is non-zero the identifier cannot be
262 * longer than that, and NULL is returned if it is. If zero (0), no
263 * length limit exist. For channel names the max length must be 256
266 * Returns the validated string, that the caller must free. Returns
267 * NULL if the identifier string is not valid or contain unassigned or
268 * prohibited characters. Such identifier strings must not be used
269 * SILC protocol. The returned string is always in UTF-8 encoding.
270 * The length of the returned string is in 'out_len'.
274 * In addition of validating the channel name string, this function
275 * may map characters to other characters or remove characters from the
276 * original string. This is done as defined in the SILC protocol. Error
277 * is returned only if the string contains unassigned or prohibited
278 * characters. The original 'identifier' is not modified at any point.
281 unsigned char *silc_channel_name_check(const unsigned char *identifier,
282 SilcUInt32 identifier_len,
283 SilcStringEncoding identifier_encoding,
284 SilcUInt32 max_allowed_length,
285 SilcUInt32 *out_len);
287 /****f* silcapputil/SilcAppUtil/silc_channel_name_verify
292 * silc_channel_name_check(const unsigned char *identifier,
293 * SilcUInt32 identifier_len,
294 * SilcStringEncoding identifier_encoding,
295 * SilcUInt32 max_allowed_length);
299 * Checks that the 'identifier' string is valid channel name string
300 * and does not contain any unassigned or prohibited character.
302 * If the 'max_allowed_length' is non-zero the identifier cannot be
303 * longer than that, and NULL is returned if it is. If zero (0), no
304 * length limit exist. For channel names the max length must be 256
307 * Returns TRUE if the string is valid and FALSE if it is prohibited.
310 SilcBool silc_channel_name_verify(const unsigned char *identifier,
311 SilcUInt32 identifier_len,
312 SilcStringEncoding identifier_encoding,
313 SilcUInt32 max_allowed_length);
315 /****f* silcapputil/SilcAppUtil/silc_get_mode_list
319 * SilcBool silc_get_mode_list(SilcBuffer mode_list,
320 * SilcUInt32 mode_list_count,
321 * SilcUInt32 **list);
325 * Returns modes from list of 32 bit MSB first order values that are
326 * encoded one after the other in the `mode_list' into the `list'
327 * array. The caller must free the returned list. Return FALSE if
328 * there is error parsing the list.
331 SilcBool silc_get_mode_list(SilcBuffer mode_list, SilcUInt32 mode_list_count,
334 /****f* silcapputil/SilcAppUtil/silc_get_status_message
338 * char *silc_get_status_message(SilcStatus status)
342 * Returns status message string
345 const char *silc_get_status_message(unsigned char status);
347 /****f* silcapputil/SilcAppUtil/silc_get_packet_name
351 * char *silc_get_packet_name(SilcPacketType type);
355 * Returns the name corresponding packet type `type'.
358 const char *silc_get_packet_name(unsigned char type);
360 /****f* silcapputil/SilcAppUtil/silc_get_command_name
364 * char *silc_get_command_name(SilcCommand command);
368 * Returns the name corresponding SILC command `command'.
371 const char *silc_get_command_name(unsigned char command);
373 /****f* silcapputil/SilcAppUtil/silc_parse_version_string
377 * SilcBool silc_parse_version_string(const char *version,
378 * SilcUInt32 *protocol_version,
379 * char **protocol_version_string,
380 * SilcUInt32 *software_version,
381 * char **software_version_string,
382 * char **vendor_version);
386 * Parses SILC protocol style version string.
389 SilcBool silc_parse_version_string(const char *version,
390 SilcUInt32 *protocol_version,
391 char **protocol_version_string,
392 SilcUInt32 *software_version,
393 char **software_version_string,
394 char **vendor_version);
396 /****f* silcapputil/SilcAppUtil/silc_version_to_num
400 * SilcUInt32 silc_version_to_num(const char *version);
404 * Converts version string x.x into number representation.
407 SilcUInt32 silc_version_to_num(const char *version);
409 /****f* silcapputil/SilcAppUtil/silc_client_chmode
413 * char *silc_client_chmode(SilcUInt32 mode, const char *cipher,
418 * Parses mode mask and returns the mode as string.
421 char *silc_client_chmode(SilcUInt32 mode, const char *cipher,
424 /****f* silcapputil/SilcAppUtil/silc_client_chumode
428 * char *silc_client_chumode(SilcUInt32 mode);
432 * Parses channel user mode mask and returns te mode as string.
435 char *silc_client_chumode(SilcUInt32 mode);
437 /****f* silcapputil/SilcAppUtil/silc_client_chumode_char
441 * char *silc_client_chumode_char(SilcUInt32 mode);
445 * Parses channel user mode and returns it as special mode character.
448 char *silc_client_chumode_char(SilcUInt32 mode);
450 /****f* silcutil/SilcUtilAPI/silc_id_render
454 * char *silc_id_render(void *id, SilcIdType id_type);
458 * Renders ID to suitable to print for example to log file.
461 char *silc_id_render(void *id, SilcIdType id_type);
463 #endif /* SILCAPPUTIL_H */