lib/silcutil/silcstrutil.h

   1 /*
   2
   3   silcstrutil.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 2002 - 2005 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 String Utilities
  21  *
  22  * DESCRIPTION
  23  *
  24  * String manipulation utility routines.  These routines provides
  25  * various helper functions for encoding, decoding and otherwise
  26  * managing strings.
  27  *
  28  ***/
  29
  30 #ifndef SILCSTRUTIL_H
  31 #define SILCSTRUTIL_H
  32
  33 /****d* silcutil/SilcStrUtilAPI/SilcStringEncoding
  34  *
  35  * NAME
  36  *
  37  *    typedef enum { ... } SilcStringEncoding;
  38  *
  39  * DESCRIPTION
  40  *
  41  *    String encoding definitions used with various string manipulation
  42  *    routines.  By default, applications are suggested to use
  43  *    SILC_STRING_LOCALE since it encodes and decodes correctly according
  44  *    to local system language and character set (locale).
  45  *
  46  * SOURCE
  47  */
  48 typedef enum {
  49   SILC_STRING_ASCII         = 0,  /* Any 8 bit ASCII encoding (default) */
  50   SILC_STRING_ASCII_ESC     = 1,  /* 7 bit ASCII (>0x7f escaped) */
  51   SILC_STRING_BMP           = 2,  /* 16 bit, UCS-2, BMP, ISO/IEC 10646 */
  52   SILC_STRING_BMP_LSB       = 3,  /* BMP, least significant byte first */
  53   SILC_STRING_UNIVERSAL     = 4,  /* 32 bit, UCS-4, Universal, ISO/IEC 10646 */
  54   SILC_STRING_UNIVERSAL_LSB = 5,  /* Universal, least significant byte first */
  55   SILC_STRING_LOCALE        = 6,  /* A locale specific conversion on
  56                                      those platforms that support iconv().
  57                                      Fallback is SILC_STRING_ASCII. */
  58   SILC_STRING_UTF8          = 7,  /* UTF-8 encoding */
  59   SILC_STRING_PRINTABLE     = 8,  /* Printable ASCII (no escaping) */
  60   SILC_STRING_VISIBLE       = 9,  /* Visible ASCII string */
  61   SILC_STRING_TELETEX       = 10, /* Teletex ASCII string */
  62   SILC_STRING_NUMERICAL     = 11, /* Numerical ASCII string (digits) */
  63   SILC_STRING_LDAP_DN       = 12, /* Strings for LDAP DNs, RFC 2253 */
  64   SILC_STRING_UTF8_ESCAPE   = 12, /* Escaped UTF-8 as defined in RFC 2253 */
  65
  66   SILC_STRING_LANGUAGE      = 6,  /* _Deprecated_, use SILC_STRING_LOCALE. */
  67 } SilcStringEncoding;
  68 /***/
  69
  70 /****f* silcutil/SilcStrUtilAPI/silc_pem_encode
  71  *
  72  * SYNOPSIS
  73  *
  74  *    char *silc_pem_encode(unsigned char *data, SilcUInt32 len);
  75  *
  76  * DESCRIPTION
  77  *
  78  *    Encodes data into PEM encoding. Returns NULL terminated PEM encoded
  79  *    data string. Note: This is originally public domain code and is
  80  *    still PD.
  81  *
  82  ***/
  83 char *silc_pem_encode(unsigned char *data, SilcUInt32 len);
  84
  85 /****f* silcutil/SilcStrUtilAPI/silc_pem_encode_file
  86  *
  87  * SYNOPSIS
  88  *
  89  *    char *silc_pem_encode_file(unsigned char *data, SilcUInt32 data_len);
  90  *
  91  * DESCRIPTION
  92  *
  93  *    Same as silc_pem_encode() but puts newline ('\n') every 72 characters.
  94  *
  95  ***/
  96 char *silc_pem_encode_file(unsigned char *data, SilcUInt32 data_len);
  97
  98 /****f* silcutil/SilcStrUtilAPI/silc_pem_decode
  99  *
 100  * SYNOPSIS
 101  *
 102  *    unsigned char *silc_pem_decode(unsigned char *pem, SilcUInt32 pem_len,
 103  *                                   SilcUInt32 *ret_len);
 104  *
 105  * DESCRIPTION
 106  *
 107  *    Decodes PEM into data. Returns the decoded data. Note: This is
 108  *    originally public domain code and is still PD.
 109  *
 110  ***/
 111 unsigned char *silc_pem_decode(unsigned char *pem, SilcUInt32 pem_len,
 112                                SilcUInt32 *ret_len);
 113
 114 /****f* silcutil/SilcStrUtilAPI/silc_mime_parse
 115  *
 116  * SYNOPSIS
 117  *
 118  *    bool
 119  *    silc_mime_parse(const unsigned char *mime, SilcUInt32 mime_len,
 120  *                    char *version, SilcUInt32 version_size,
 121  *                    char *content_type, SilcUInt32 content_type_size,
 122  *                    char *transfer_encoding,
 123  *                    SilcUInt32 transfer_encoding_size,
 124  *                    unsigned char **mime_data_ptr,
 125  *                    SilcUInt32 *mime_data_len);
 126  *
 127  * DESCRIPTION
 128  *
 129  *    Parses MIME header indicated by `mime' data block of length of
 130  *    `mime_len'.  Returns TRUE if the `mime' is valid MIME object.
 131  *    Parses from the MIME header the MIME Version (if present) and
 132  *    copies it to the `version' pointer if provided, content type
 133  *    indicating the data in the MIME object and copies it to the
 134  *    `content_type' if provided, and the tranfer encoding (if present)
 135  *    indicating the encoding of the data and copies it to the
 136  *    `content_transfer_encoding' if provided.
 137  *
 138  *    The pointer to the actual data in the MIME object is saved into
 139  *    `mime_data_ptr'.  The pointer is a location in the `mime' and it
 140  *    does not allocate or copy anything, ie. the `mime_data_ptr' is a
 141  *    pointer to the `mime'.  The `mime_data_len' indicates the length of
 142  *    the data without the MIME header.  The caller is responsible of
 143  *    NULL terminating the buffers it provides.
 144  *
 145  * NOTES
 146  *
 147  *    This function is deprecated.  Use the SilcMime API instead.
 148  *
 149  ***/
 150 bool
 151 silc_mime_parse(const unsigned char *mime, SilcUInt32 mime_len,
 152                 char *version, SilcUInt32 version_size,
 153                 char *content_type, SilcUInt32 content_type_size,
 154                 char *transfer_encoding, SilcUInt32 transfer_encoding_size,
 155                 unsigned char **mime_data_ptr, SilcUInt32 *mime_data_len);
 156
 157 /****f* silcutil/SilcStrUtilAPI/silc_strncat
 158  *
 159  * SYNOPSIS
 160  *
 161  *    char *silc_strncat(char *dest, SilcUInt32 dest_size,
 162  *                       const char *src, SilcUInt32 src_len);
 163  *
 164  * DESCRIPTION
 165  *
 166  *    Concatenates the `src' into `dest'.  If `src_len' is more than the
 167  *    size of the `dest' (minus NULL at the end) the `src' will be
 168  *    truncated to fit.
 169  *
 170  ***/
 171 char *silc_strncat(char *dest, SilcUInt32 dest_size,
 172                    const char *src, SilcUInt32 src_len);
 173
 174 /****f* silcutil/SilcStrUtilAPI/silc_identifier_check
 175  *
 176  * SYNOPSIS
 177  *
 178  *    unsigned char *
 179  *    silc_identifier_check(const unsigned char *identifier,
 180  *                          SilcUInt32 identifier_len,
 181  *                          SilcStringEncoding identifier_encoding,
 182  *                          SilcUInt32 max_allowed_length,
 183  *                          SilcUInt32 *out_len);
 184  *
 185  * DESCRIPTION
 186  *
 187  *    Checks that the 'identifier' string is valid identifier string
 188  *    and does not contain any unassigned or prohibited character.  This
 189  *    function is used to check for valid nicknames, server names,
 190  *    usernames, hostnames, service names, algorithm names, other security
 191  *    property names, and SILC Public Key name.
 192  *
 193  *    If the 'max_allowed_length' is non-zero the identifier cannot be
 194  *    longer than that, and NULL is returned if it is.  If zero (0), no
 195  *    length limit exist.  For nicknames the max length must be 128 bytes.
 196  *    Other identifiers has no default limit, but application may choose
 197 *     one anyway.
 198  *
 199  *    Returns the validated string, that the caller must free.  Returns
 200  *    NULL if the identifier string is not valid or contain unassigned or
 201  *    prohibited characters.  Such identifier strings must not be used
 202  *    SILC protocol.  The returned string is always in UTF-8 encoding.
 203  *    The length of the returned string is in 'out_len'.
 204  *
 205  * NOTES
 206  *
 207  *    In addition of validating the identifier string, this function
 208  *    may map characters to other characters or remove characters from the
 209  *    original string.  This is done as defined in the SILC protocol.  Error
 210  *    is returned only if the string contains unassigned or prohibited
 211  *    characters.  The original 'identifier' is not modified at any point.
 212  *
 213  ***/
 214 unsigned char *silc_identifier_check(const unsigned char *identifier,
 215                                      SilcUInt32 identifier_len,
 216                                      SilcStringEncoding identifier_encoding,
 217                                      SilcUInt32 max_allowed_length,
 218                                      SilcUInt32 *out_len);
 219
 220 /****f* silcutil/SilcStrUtilAPI/silc_identifier_verify
 221  *
 222  * SYNOPSIS
 223  *
 224  *    bool
 225  *    silc_identifier_check(const unsigned char *identifier,
 226  *                          SilcUInt32 identifier_len,
 227  *                          SilcStringEncoding identifier_encoding,
 228  *                          SilcUInt32 max_allowed_length);
 229  *
 230  * DESCRIPTION
 231  *
 232  *    Checks that the 'identifier' string is valid identifier string
 233  *    and does not contain any unassigned or prohibited character.  This
 234  *    function is used to check for valid nicknames, server names,
 235  *    usernames, hostnames, service names, algorithm names, other security
 236  *    property names, and SILC Public Key name.
 237  *
 238  *    If the 'max_allowed_length' is non-zero the identifier cannot be
 239  *    longer than that, and NULL is returned if it is.  If zero (0), no
 240  *    length limit exist.  For nicknames the max length must be 128 bytes.
 241  *    Other identifiers has no default limit, but application may choose
 242  *    one anyway.
 243  *
 244  *    Returns TRUE if the string is valid and FALSE if it is prohibited.
 245  *
 246  ***/
 247 bool silc_identifier_verify(const unsigned char *identifier,
 248                             SilcUInt32 identifier_len,
 249                             SilcStringEncoding identifier_encoding,
 250                             SilcUInt32 max_allowed_length);
 251
 252 /****f* silcutil/SilcStrUtilAPI/silc_channel_name_check
 253  *
 254  * SYNOPSIS
 255  *
 256  *    unsigned char *
 257  *    silc_channel_name_check(const unsigned char *identifier,
 258  *                            SilcUInt32 identifier_len,
 259  *                            SilcStringEncoding identifier_encoding,
 260  *                            SilcUInt32 max_allowed_length,
 261  *                            SilcUInt32 *out_len);
 262  *
 263  * DESCRIPTION
 264  *
 265  *    Checks that the 'identifier' string is valid channel name string
 266  *    and does not contain any unassigned or prohibited character.
 267  *
 268  *    If the 'max_allowed_length' is non-zero the identifier cannot be
 269  *    longer than that, and NULL is returned if it is.  If zero (0), no
 270  *    length limit exist.  For channel names the max length must be 256
 271  *    bytes.
 272  *
 273  *    Returns the validated string, that the caller must free.  Returns
 274  *    NULL if the identifier string is not valid or contain unassigned or
 275  *    prohibited characters.  Such identifier strings must not be used
 276  *    SILC protocol.  The returned string is always in UTF-8 encoding.
 277  *    The length of the returned string is in 'out_len'.
 278  *
 279  * NOTES
 280  *
 281  *    In addition of validating the channel name string, this function
 282  *    may map characters to other characters or remove characters from the
 283  *    original string.  This is done as defined in the SILC protocol.  Error
 284  *    is returned only if the string contains unassigned or prohibited
 285  *    characters.  The original 'identifier' is not modified at any point.
 286  *
 287  ***/
 288 unsigned char *silc_channel_name_check(const unsigned char *identifier,
 289                                        SilcUInt32 identifier_len,
 290                                        SilcStringEncoding identifier_encoding,
 291                                        SilcUInt32 max_allowed_length,
 292                                        SilcUInt32 *out_len);
 293
 294 /****f* silcutil/SilcStrUtilAPI/silc_channel_name_verify
 295  *
 296  * SYNOPSIS
 297  *
 298  *    bool
 299  *    silc_channel_name_check(const unsigned char *identifier,
 300  *                            SilcUInt32 identifier_len,
 301  *                            SilcStringEncoding identifier_encoding,
 302  *                            SilcUInt32 max_allowed_length);
 303  *
 304  * DESCRIPTION
 305  *
 306  *    Checks that the 'identifier' string is valid channel name string
 307  *    and does not contain any unassigned or prohibited character.
 308  *
 309  *    If the 'max_allowed_length' is non-zero the identifier cannot be
 310  *    longer than that, and NULL is returned if it is.  If zero (0), no
 311  *    length limit exist.  For channel names the max length must be 256
 312  *    bytes.
 313  *
 314  *    Returns TRUE if the string is valid and FALSE if it is prohibited.
 315  *
 316  ***/
 317 bool silc_channel_name_verify(const unsigned char *identifier,
 318                               SilcUInt32 identifier_len,
 319                               SilcStringEncoding identifier_encoding,
 320                               SilcUInt32 max_allowed_length);
 321
 322 #endif /* SILCSTRUTIL_H */