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* silcutil/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(const char *pub_filename);
 121  *
 122  * DESCRIPTION
 123  *
 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.
 127  *
 128  ***/
 129 SilcBool silc_show_public_key(const char *pub_filename);
 130
 131 /****f* silcapputil/SilcAppUtil/silc_change_private_key_passphrase
 132  *
 133  * SYNOPSIS
 134  *
 135  *    SilcBool silc_change_private_key_passphrase(const char *prv_filename,
 136  *                                                const char *old_passphrase,
 137  *                                                const char *new_passphrase);
 138  *
 139  * DESCRIPTION
 140  *
 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
 144  *    prompt for them.
 145  *
 146  ***/
 147 SilcBool silc_change_private_key_passphrase(const char *prv_filename,
 148                                             const char *old_passphrase,
 149                                             const char *new_passphrase);
 150
 151
 152 /****f* silcapputil/SilcAppUtil/silc_identifier_check
 153  *
 154  * SYNOPSIS
 155  *
 156  *    unsigned char *
 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);
 162  *
 163  * DESCRIPTION
 164  *
 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.
 170  *
 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
 175  *    one anyway.
 176  *
 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'.
 182  *
 183  * NOTES
 184  *
 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.
 190  *
 191  ***/
 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);
 197
 198 /****f* silcapputil/SilcAppUtil/silc_identifier_verify
 199  *
 200  * SYNOPSIS
 201  *
 202  *    SilcBool
 203  *    silc_identifier_check(const unsigned char *identifier,
 204  *                          SilcUInt32 identifier_len,
 205  *                          SilcStringEncoding identifier_encoding,
 206  *                          SilcUInt32 max_allowed_length);
 207  *
 208  * DESCRIPTION
 209  *
 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.
 215  *
 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
 220  *    one anyway.
 221  *
 222  *    Returns TRUE if the string is valid and FALSE if it is prohibited.
 223  *
 224  ***/
 225 SilcBool silc_identifier_verify(const unsigned char *identifier,
 226                                 SilcUInt32 identifier_len,
 227                                 SilcStringEncoding identifier_encoding,
 228                                 SilcUInt32 max_allowed_length);
 229
 230 /****f* silcapputil/SilcAppUtil/silc_channel_name_check
 231  *
 232  * SYNOPSIS
 233  *
 234  *    unsigned char *
 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);
 240  *
 241  * DESCRIPTION
 242  *
 243  *    Checks that the 'identifier' string is valid channel name string
 244  *    and does not contain any unassigned or prohibited character.
 245  *
 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
 249  *    bytes.
 250  *
 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'.
 256  *
 257  * NOTES
 258  *
 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.
 264  *
 265  ***/
 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);
 271
 272 /****f* silcapputil/SilcAppUtil/silc_channel_name_verify
 273  *
 274  * SYNOPSIS
 275  *
 276  *    SilcBool
 277  *    silc_channel_name_check(const unsigned char *identifier,
 278  *                            SilcUInt32 identifier_len,
 279  *                            SilcStringEncoding identifier_encoding,
 280  *                            SilcUInt32 max_allowed_length);
 281  *
 282  * DESCRIPTION
 283  *
 284  *    Checks that the 'identifier' string is valid channel name string
 285  *    and does not contain any unassigned or prohibited character.
 286  *
 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
 290  *    bytes.
 291  *
 292  *    Returns TRUE if the string is valid and FALSE if it is prohibited.
 293  *
 294  ***/
 295 SilcBool silc_channel_name_verify(const unsigned char *identifier,
 296                                   SilcUInt32 identifier_len,
 297                                   SilcStringEncoding identifier_encoding,
 298                                   SilcUInt32 max_allowed_length);
 299
 300 #endif /* SILCAPPUTIL_H */