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
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(SilcPublicKey public_key);
124 * This routine can be used to dump the SILC public key into human
125 * readable form into stdout. Returns FALSE on error.
128 SilcBool silc_show_public_key(SilcPublicKey public_key);
130 /****f* silcapputil/SilcAppUtil/silc_show_public_key_file
134 * SilcBool silc_show_public_key_file(const char *pub_filename);
138 * This routine can be used to dump the contents of the public key
139 * in the public key file `pub_filename'. This dumps the public key
140 * into human readable form into stdout. Returns FALSE on error.
143 SilcBool silc_show_public_key_file(const char *pub_filename);
145 /****f* silcapputil/SilcAppUtil/silc_change_private_key_passphrase
149 * SilcBool silc_change_private_key_passphrase(const char *prv_filename,
150 * const char *old_passphrase,
151 * const char *new_passphrase);
155 * This routine can be used to change the passphrase of the private
156 * key file, which is used to encrypt the private key. If the old
157 * and new passphrase is not provided for this function this will
161 SilcBool silc_change_private_key_passphrase(const char *prv_filename,
162 const char *old_passphrase,
163 const char *new_passphrase);
166 /****f* silcapputil/SilcAppUtil/silc_identifier_check
171 * silc_identifier_check(const unsigned char *identifier,
172 * SilcUInt32 identifier_len,
173 * SilcStringEncoding identifier_encoding,
174 * SilcUInt32 max_allowed_length,
175 * SilcUInt32 *out_len);
179 * Checks that the 'identifier' string is valid identifier string
180 * and does not contain any unassigned or prohibited character. This
181 * function is used to check for valid nicknames, server names,
182 * usernames, hostnames, service names, algorithm names, other security
183 * property names, and SILC Public Key name.
185 * If the 'max_allowed_length' is non-zero the identifier cannot be
186 * longer than that, and NULL is returned if it is. If zero (0), no
187 * length limit exist. For nicknames the max length must be 128 bytes.
188 * Other identifiers has no default limit, but application may choose
191 * Returns the validated string, that the caller must free. Returns
192 * NULL if the identifier string is not valid or contain unassigned or
193 * prohibited characters. Such identifier strings must not be used
194 * SILC protocol. The returned string is always in UTF-8 encoding.
195 * The length of the returned string is in 'out_len'.
199 * In addition of validating the identifier string, this function
200 * may map characters to other characters or remove characters from the
201 * original string. This is done as defined in the SILC protocol. Error
202 * is returned only if the string contains unassigned or prohibited
203 * characters. The original 'identifier' is not modified at any point.
206 unsigned char *silc_identifier_check(const unsigned char *identifier,
207 SilcUInt32 identifier_len,
208 SilcStringEncoding identifier_encoding,
209 SilcUInt32 max_allowed_length,
210 SilcUInt32 *out_len);
212 /****f* silcapputil/SilcAppUtil/silc_identifier_verify
217 * silc_identifier_check(const unsigned char *identifier,
218 * SilcUInt32 identifier_len,
219 * SilcStringEncoding identifier_encoding,
220 * SilcUInt32 max_allowed_length);
224 * Checks that the 'identifier' string is valid identifier string
225 * and does not contain any unassigned or prohibited character. This
226 * function is used to check for valid nicknames, server names,
227 * usernames, hostnames, service names, algorithm names, other security
228 * property names, and SILC Public Key name.
230 * If the 'max_allowed_length' is non-zero the identifier cannot be
231 * longer than that, and NULL is returned if it is. If zero (0), no
232 * length limit exist. For nicknames the max length must be 128 bytes.
233 * Other identifiers has no default limit, but application may choose
236 * Returns TRUE if the string is valid and FALSE if it is prohibited.
239 SilcBool silc_identifier_verify(const unsigned char *identifier,
240 SilcUInt32 identifier_len,
241 SilcStringEncoding identifier_encoding,
242 SilcUInt32 max_allowed_length);
244 /****f* silcapputil/SilcAppUtil/silc_channel_name_check
249 * silc_channel_name_check(const unsigned char *identifier,
250 * SilcUInt32 identifier_len,
251 * SilcStringEncoding identifier_encoding,
252 * SilcUInt32 max_allowed_length,
253 * SilcUInt32 *out_len);
257 * Checks that the 'identifier' string is valid channel name string
258 * and does not contain any unassigned or prohibited character.
260 * If the 'max_allowed_length' is non-zero the identifier cannot be
261 * longer than that, and NULL is returned if it is. If zero (0), no
262 * length limit exist. For channel names the max length must be 256
265 * Returns the validated string, that the caller must free. Returns
266 * NULL if the identifier string is not valid or contain unassigned or
267 * prohibited characters. Such identifier strings must not be used
268 * SILC protocol. The returned string is always in UTF-8 encoding.
269 * The length of the returned string is in 'out_len'.
273 * In addition of validating the channel name string, this function
274 * may map characters to other characters or remove characters from the
275 * original string. This is done as defined in the SILC protocol. Error
276 * is returned only if the string contains unassigned or prohibited
277 * characters. The original 'identifier' is not modified at any point.
280 unsigned char *silc_channel_name_check(const unsigned char *identifier,
281 SilcUInt32 identifier_len,
282 SilcStringEncoding identifier_encoding,
283 SilcUInt32 max_allowed_length,
284 SilcUInt32 *out_len);
286 /****f* silcapputil/SilcAppUtil/silc_channel_name_verify
291 * silc_channel_name_check(const unsigned char *identifier,
292 * SilcUInt32 identifier_len,
293 * SilcStringEncoding identifier_encoding,
294 * SilcUInt32 max_allowed_length);
298 * Checks that the 'identifier' string is valid channel name string
299 * and does not contain any unassigned or prohibited character.
301 * If the 'max_allowed_length' is non-zero the identifier cannot be
302 * longer than that, and NULL is returned if it is. If zero (0), no
303 * length limit exist. For channel names the max length must be 256
306 * Returns TRUE if the string is valid and FALSE if it is prohibited.
309 SilcBool silc_channel_name_verify(const unsigned char *identifier,
310 SilcUInt32 identifier_len,
311 SilcStringEncoding identifier_encoding,
312 SilcUInt32 max_allowed_length);
314 /****f* silcapputil/SilcAppUtil/silc_get_mode_list
318 * SilcBool silc_get_mode_list(SilcBuffer mode_list,
319 * SilcUInt32 mode_list_count,
320 * SilcUInt32 **list);
324 * Returns modes from list of 32 bit MSB first order values that are
325 * encoded one after the other in the `mode_list' into the `list'
326 * array. The caller must free the returned list. Return FALSE if
327 * there is error parsing the list.
330 SilcBool silc_get_mode_list(SilcBuffer mode_list, SilcUInt32 mode_list_count,
333 /****f* silcapputil/SilcAppUtil/silc_get_status_message
337 * char *silc_get_status_message(SilcStatus status)
341 * Returns status message string
344 const char *silc_get_status_message(unsigned char status);
346 /****f* silcapputil/SilcAppUtil/silc_get_packet_name
350 * char *silc_get_packet_name(SilcPacketType type);
354 * Returns the name corresponding packet type `type'.
357 const char *silc_get_packet_name(unsigned char type);
359 /****f* silcapputil/SilcAppUtil/silc_get_command_name
363 * char *silc_get_command_name(SilcCommand command);
367 * Returns the name corresponding SILC command `command'.
370 const char *silc_get_command_name(unsigned char command);
372 /****f* silcapputil/SilcAppUtil/silc_parse_version_string
376 * SilcBool silc_parse_version_string(const char *version,
377 * SilcUInt32 *protocol_version,
378 * char **protocol_version_string,
379 * SilcUInt32 *software_version,
380 * char **software_version_string,
381 * char **vendor_version);
385 * Parses SILC protocol style version string.
388 SilcBool silc_parse_version_string(const char *version,
389 SilcUInt32 *protocol_version,
390 char **protocol_version_string,
391 SilcUInt32 *software_version,
392 char **software_version_string,
393 char **vendor_version);
395 /****f* silcapputil/SilcAppUtil/silc_version_to_num
399 * SilcUInt32 silc_version_to_num(const char *version);
403 * Converts version string x.x into number representation.
406 SilcUInt32 silc_version_to_num(const char *version);
408 /****f* silcapputil/SilcAppUtil/silc_client_chmode
412 * char *silc_client_chmode(SilcUInt32 mode, const char *cipher,
417 * Parses mode mask and returns the mode as string.
420 char *silc_client_chmode(SilcUInt32 mode, const char *cipher,
423 /****f* silcapputil/SilcAppUtil/silc_client_chumode
427 * char *silc_client_chumode(SilcUInt32 mode);
431 * Parses channel user mode mask and returns te mode as string.
434 char *silc_client_chumode(SilcUInt32 mode);
436 /****f* silcapputil/SilcAppUtil/silc_client_chumode_char
440 * char *silc_client_chumode_char(SilcUInt32 mode);
444 * Parses channel user mode and returns it as special mode character.
447 char *silc_client_chumode_char(SilcUInt32 mode);
449 /****f* silcutil/SilcUtilAPI/silc_id_render
453 * char *silc_id_render(void *id, SilcIdType id_type);
457 * Renders ID to suitable to print for example to log file.
460 char *silc_id_render(void *id, SilcIdType id_type);
462 #endif /* SILCAPPUTIL_H */