lib/silcapputil/silcapputil.h

   1 /*
   2
   3   silcapputil.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 2002 - 2006 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* silcapputil/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* silcapputil/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  *                                  SilcPublicKey *return_public_key,
  49  *                                  SilcPrivateKey *return_private_key,
  50  *                                  SilcBool interactive);
  51  *
  52  * DESCRIPTION
  53  *
  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.
  62  *
  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.
  66  *
  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'
  71  *    has no effect.
  72  *
  73  * NOTES
  74  *
  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.
  78  *
  79  ***/
  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);
  89
  90 /****f* silcapputil/SilcAppUtil/silc_load_key_pair
  91  *
  92  * SYNOPSIS
  93  *
  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);
  99  *
 100  * DESCRIPTION
 101  *
 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.
 108  *
 109  ***/
 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);
 115
 116 /****f* silcapputil/SilcAppUtil/silc_show_public_key
 117  *
 118  * SYNOPSIS
 119  *
 120  *    SilcBool silc_show_public_key(SilcPublicKey public_key);
 121  *
 122  * DESCRIPTION
 123  *
 124  *    This routine can be used to dump the SILC public key into human
 125  *    readable form into stdout.  Returns FALSE on error.
 126  *
 127  ***/
 128 SilcBool silc_show_public_key(SilcPublicKey public_key);
 129
 130 /****f* silcapputil/SilcAppUtil/silc_show_public_key_file
 131  *
 132  * SYNOPSIS
 133  *
 134  *    SilcBool silc_show_public_key_file(const char *pub_filename);
 135  *
 136  * DESCRIPTION
 137  *
 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.
 141  *
 142  ***/
 143 SilcBool silc_show_public_key_file(const char *pub_filename);
 144
 145 /****f* silcapputil/SilcAppUtil/silc_change_private_key_passphrase
 146  *
 147  * SYNOPSIS
 148  *
 149  *    SilcBool silc_change_private_key_passphrase(const char *prv_filename,
 150  *                                                const char *old_passphrase,
 151  *                                                const char *new_passphrase);
 152  *
 153  * DESCRIPTION
 154  *
 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
 158  *    prompt for them.
 159  *
 160  ***/
 161 SilcBool silc_change_private_key_passphrase(const char *prv_filename,
 162                                             const char *old_passphrase,
 163                                             const char *new_passphrase);
 164
 165
 166 /****f* silcapputil/SilcAppUtil/silc_identifier_check
 167  *
 168  * SYNOPSIS
 169  *
 170  *    unsigned char *
 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);
 176  *
 177  * DESCRIPTION
 178  *
 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.
 184  *
 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
 189  *    one anyway.
 190  *
 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'.
 196  *
 197  * NOTES
 198  *
 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.
 204  *
 205  ***/
 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);
 211
 212 /****f* silcapputil/SilcAppUtil/silc_identifier_verify
 213  *
 214  * SYNOPSIS
 215  *
 216  *    SilcBool
 217  *    silc_identifier_check(const unsigned char *identifier,
 218  *                          SilcUInt32 identifier_len,
 219  *                          SilcStringEncoding identifier_encoding,
 220  *                          SilcUInt32 max_allowed_length);
 221  *
 222  * DESCRIPTION
 223  *
 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.
 229  *
 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
 234  *    one anyway.
 235  *
 236  *    Returns TRUE if the string is valid and FALSE if it is prohibited.
 237  *
 238  ***/
 239 SilcBool silc_identifier_verify(const unsigned char *identifier,
 240                                 SilcUInt32 identifier_len,
 241                                 SilcStringEncoding identifier_encoding,
 242                                 SilcUInt32 max_allowed_length);
 243
 244 /****f* silcapputil/SilcAppUtil/silc_channel_name_check
 245  *
 246  * SYNOPSIS
 247  *
 248  *    unsigned char *
 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);
 254  *
 255  * DESCRIPTION
 256  *
 257  *    Checks that the 'identifier' string is valid channel name string
 258  *    and does not contain any unassigned or prohibited character.
 259  *
 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
 263  *    bytes.
 264  *
 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'.
 270  *
 271  * NOTES
 272  *
 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.
 278  *
 279  ***/
 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);
 285
 286 /****f* silcapputil/SilcAppUtil/silc_channel_name_verify
 287  *
 288  * SYNOPSIS
 289  *
 290  *    SilcBool
 291  *    silc_channel_name_check(const unsigned char *identifier,
 292  *                            SilcUInt32 identifier_len,
 293  *                            SilcStringEncoding identifier_encoding,
 294  *                            SilcUInt32 max_allowed_length);
 295  *
 296  * DESCRIPTION
 297  *
 298  *    Checks that the 'identifier' string is valid channel name string
 299  *    and does not contain any unassigned or prohibited character.
 300  *
 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
 304  *    bytes.
 305  *
 306  *    Returns TRUE if the string is valid and FALSE if it is prohibited.
 307  *
 308  ***/
 309 SilcBool silc_channel_name_verify(const unsigned char *identifier,
 310                                   SilcUInt32 identifier_len,
 311                                   SilcStringEncoding identifier_encoding,
 312                                   SilcUInt32 max_allowed_length);
 313
 314 /****f* silcapputil/SilcAppUtil/silc_get_mode_list
 315  *
 316  * SYNOPSIS
 317  *
 318  *    SilcBool silc_get_mode_list(SilcBuffer mode_list,
 319  *                                SilcUInt32 mode_list_count,
 320  *                                SilcUInt32 **list);
 321  *
 322  * DESCRIPTION
 323  *
 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.
 328  *
 329  ***/
 330 SilcBool silc_get_mode_list(SilcBuffer mode_list, SilcUInt32 mode_list_count,
 331                             SilcUInt32 **list);
 332
 333 /****f* silcapputil/SilcAppUtil/silc_get_status_message
 334  *
 335  * SYNOPSIS
 336  *
 337  *    char *silc_get_status_message(SilcStatus status)
 338  *
 339  * DESCRIPTION
 340  *
 341  *    Returns status message string
 342  *
 343  ***/
 344 const char *silc_get_status_message(unsigned char status);
 345
 346 /****f* silcapputil/SilcAppUtil/silc_get_packet_name
 347  *
 348  * SYNOPSIS
 349  *
 350  *    char *silc_get_packet_name(SilcPacketType type);
 351  *
 352  * DESCRIPTION
 353  *
 354  *    Returns the name corresponding packet type `type'.
 355  *
 356  ***/
 357 const char *silc_get_packet_name(unsigned char type);
 358
 359 /****f* silcapputil/SilcAppUtil/silc_get_command_name
 360  *
 361  * SYNOPSIS
 362  *
 363  *    char *silc_get_command_name(SilcCommand command);
 364  *
 365  * DESCRIPTION
 366  *
 367  *    Returns the name corresponding SILC command `command'.
 368  *
 369  ***/
 370 const char *silc_get_command_name(unsigned char command);
 371
 372 /****f* silcapputil/SilcAppUtil/silc_parse_version_string
 373  *
 374  * SYNOPSIS
 375  *
 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);
 382  *
 383  * DESCRIPTION
 384  *
 385  *    Parses SILC protocol style version string.
 386  *
 387  ***/
 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);
 394
 395 /****f* silcapputil/SilcAppUtil/silc_version_to_num
 396  *
 397  * SYNOPSIS
 398  *
 399  *    SilcUInt32 silc_version_to_num(const char *version);
 400  *
 401  * DESCRIPTION
 402  *
 403  *    Converts version string x.x into number representation.
 404  *
 405  ***/
 406 SilcUInt32 silc_version_to_num(const char *version);
 407
 408 /****f* silcapputil/SilcAppUtil/silc_client_chmode
 409  *
 410  * SYNOPSIS
 411  *
 412  *    char *silc_client_chmode(SilcUInt32 mode, const char *cipher,
 413  *                             const char *hmac);
 414  *
 415  * DESCRIPTION
 416  *
 417  *    Parses mode mask and returns the mode as string.
 418  *
 419  ***/
 420 char *silc_client_chmode(SilcUInt32 mode, const char *cipher,
 421                          const char *hmac);
 422
 423 /****f* silcapputil/SilcAppUtil/silc_client_chumode
 424  *
 425  * SYNOPSIS
 426  *
 427  *    char *silc_client_chumode(SilcUInt32 mode);
 428  *
 429  * DESCRIPTION
 430  *
 431  *    Parses channel user mode mask and returns te mode as string.
 432  *
 433  ***/
 434 char *silc_client_chumode(SilcUInt32 mode);
 435
 436 /****f* silcapputil/SilcAppUtil/silc_client_chumode_char
 437  *
 438  * SYNOPSIS
 439  *
 440  *    char *silc_client_chumode_char(SilcUInt32 mode);
 441  *
 442  * DESCRIPTION
 443  *
 444  *    Parses channel user mode and returns it as special mode character.
 445  *
 446  ***/
 447 char *silc_client_chumode_char(SilcUInt32 mode);
 448
 449 /****f* silcutil/SilcUtilAPI/silc_id_render
 450  *
 451  * SYNOPSIS
 452  *
 453  *    char *silc_id_render(void *id, SilcIdType id_type);
 454  *
 455  * DESCRIPTION
 456  *
 457  *    Renders ID to suitable to print for example to log file.
 458  *
 459  ***/
 460 char *silc_id_render(void *id, SilcIdType id_type);
 461
 462 #endif /* SILCAPPUTIL_H */