lib/silcapputil/silcapputil.h

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