X-Git-Url: http://git.silcnet.org/gitweb/?p=silc.git;a=blobdiff_plain;f=lib%2Fsilcutil%2Fsilcstrutil.h;h=3d96492f9169ca2231a420c79068fcefe48140d7;hp=746d0ad9cafd51a56a0961e60744b94c3a4eaa02;hb=40f8443d8d3a6577336ee66d18e04d9ac4d956bb;hpb=b3e67d3dfa6409755be33f352b5a86fbb094a570 diff --git a/lib/silcutil/silcstrutil.h b/lib/silcutil/silcstrutil.h index 746d0ad9..3d96492f 100644 --- a/lib/silcutil/silcstrutil.h +++ b/lib/silcutil/silcstrutil.h @@ -1,10 +1,10 @@ /* - silcstrutil.h + silcstrutil.h Author: Pekka Riikonen - Copyright (C) 2002 Pekka Riikonen + Copyright (C) 2002 - 2005 Pekka Riikonen This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by @@ -21,15 +21,52 @@ * * DESCRIPTION * - * String manipulation utility routines. These routines provides - * various helper functions for encoding, decoding and otherwise - * managing strings. + * String manipulation utility routines. These routines provides + * various helper functions for encoding, decoding and otherwise + * managing strings. * ***/ #ifndef SILCSTRUTIL_H #define SILCSTRUTIL_H +/****d* silcutil/SilcStrUtilAPI/SilcStringEncoding + * + * NAME + * + * typedef enum { ... } SilcStringEncoding; + * + * DESCRIPTION + * + * String encoding definitions used with various string manipulation + * routines. By default, applications are suggested to use + * SILC_STRING_LOCALE since it encodes and decodes correctly according + * to local system language and character set (locale). + * + * SOURCE + */ +typedef enum { + SILC_STRING_ASCII = 0, /* Any 8 bit ASCII encoding (default) */ + SILC_STRING_ASCII_ESC = 1, /* 7 bit ASCII (>0x7f escaped) */ + SILC_STRING_BMP = 2, /* 16 bit, UCS-2, BMP, ISO/IEC 10646 */ + SILC_STRING_BMP_LSB = 3, /* BMP, least significant byte first */ + SILC_STRING_UNIVERSAL = 4, /* 32 bit, UCS-4, Universal, ISO/IEC 10646 */ + SILC_STRING_UNIVERSAL_LSB = 5, /* Universal, least significant byte first */ + SILC_STRING_LOCALE = 6, /* A locale specific conversion on + those platforms that support iconv(). + Fallback is SILC_STRING_ASCII. */ + SILC_STRING_UTF8 = 7, /* UTF-8 encoding */ + SILC_STRING_PRINTABLE = 8, /* Printable ASCII (no escaping) */ + SILC_STRING_VISIBLE = 9, /* Visible ASCII string */ + SILC_STRING_TELETEX = 10, /* Teletex ASCII string */ + SILC_STRING_NUMERICAL = 11, /* Numerical ASCII string (digits) */ + SILC_STRING_LDAP_DN = 12, /* Strings for LDAP DNs, RFC 2253 */ + SILC_STRING_UTF8_ESCAPE = 12, /* Escaped UTF-8 as defined in RFC 2253 */ + + SILC_STRING_LANGUAGE = 6, /* _Deprecated_, use SILC_STRING_LOCALE. */ +} SilcStringEncoding; +/***/ + /****f* silcutil/SilcStrUtilAPI/silc_pem_encode * * SYNOPSIS @@ -74,103 +111,169 @@ char *silc_pem_encode_file(unsigned char *data, SilcUInt32 data_len); unsigned char *silc_pem_decode(unsigned char *pem, SilcUInt32 pem_len, SilcUInt32 *ret_len); -/****d* silcutil/SilcStrUtilAPI/SilcStringEncoding +/****f* silcutil/SilcStrUtilAPI/silc_strncat * - * NAME - * - * typedef enum { ... } SilcStringEncoding; + * SYNOPSIS + * + * char *silc_strncat(char *dest, SilcUInt32 dest_size, + * const char *src, SilcUInt32 src_len); * * DESCRIPTION * - * String encoding definitions used with the UTF-8 encoding and the - * decoding functions. + * Concatenates the `src' into `dest'. If `src_len' is more than the + * size of the `dest' (minus NULL at the end) the `src' will be + * truncated to fit. * - * SOURCE - */ -typedef enum { - SILC_STRING_ASCII = 0, /* Any 8 bit ASCII encoding (default) */ - - /* Rest are not implemented yet */ - SILC_STRING_ASCII_ESC = 1, /* 7 bit ASCII (>0x7f escaped) */ - SILC_STRING_BMP = 2, /* 16 bit, UCS-2, BMP, ISO/IEC 10646 */ - SILC_STRING_UNIVERSAL = 3, /* 32 bit, UCS-4, Universal, ISO/IEC 10646 */ -} SilcStringEncoding; -/***/ + ***/ +char *silc_strncat(char *dest, SilcUInt32 dest_size, + const char *src, SilcUInt32 src_len); -/****f* silcutil/SilcStrUtilAPI/silc_utf8_encode +/****f* silcutil/SilcStrUtilAPI/silc_identifier_check * * SYNOPSIS * - * SilcUInt32 silc_utf8_encode(const unsigned char *bin, SilcUInt32 bin_len, - * SilcStringEncoding bin_encoding, - * unsigned char *utf8, SilcUInt32 utf8_size); + * unsigned char * + * silc_identifier_check(const unsigned char *identifier, + * SilcUInt32 identifier_len, + * SilcStringEncoding identifier_encoding, + * SilcUInt32 max_allowed_length, + * SilcUInt32 *out_len); * * DESCRIPTION * - * Encodes the string `bin' of which encoding is `bin_encoding' to the - * UTF-8 encoding into the buffer `utf8' which is of size of `utf8_size'. - * Returns the length of the UTF-8 encoded string, or zero (0) on error. - * By default `bin_encoding' is ASCII, and the caller needs to know the - * encoding of the input string if it is anything else. + * Checks that the 'identifier' string is valid identifier string + * and does not contain any unassigned or prohibited character. This + * function is used to check for valid nicknames, server names, + * usernames, hostnames, service names, algorithm names, other security + * property names, and SILC Public Key name. + * + * If the 'max_allowed_length' is non-zero the identifier cannot be + * longer than that, and NULL is returned if it is. If zero (0), no + * length limit exist. For nicknames the max length must be 128 bytes. + * Other identifiers has no default limit, but application may choose +* one anyway. + * + * Returns the validated string, that the caller must free. Returns + * NULL if the identifier string is not valid or contain unassigned or + * prohibited characters. Such identifier strings must not be used + * SILC protocol. The returned string is always in UTF-8 encoding. + * The length of the returned string is in 'out_len'. + * + * NOTES + * + * In addition of validating the identifier string, this function + * may map characters to other characters or remove characters from the + * original string. This is done as defined in the SILC protocol. Error + * is returned only if the string contains unassigned or prohibited + * characters. The original 'identifier' is not modified at any point. * ***/ -SilcUInt32 silc_utf8_encode(const unsigned char *bin, SilcUInt32 bin_len, - SilcStringEncoding bin_encoding, - unsigned char *utf8, SilcUInt32 utf8_size); +unsigned char *silc_identifier_check(const unsigned char *identifier, + SilcUInt32 identifier_len, + SilcStringEncoding identifier_encoding, + SilcUInt32 max_allowed_length, + SilcUInt32 *out_len); -/****f* silcutil/SilcStrUtilAPI/silc_utf8_decode +/****f* silcutil/SilcStrUtilAPI/silc_identifier_verify * * SYNOPSIS * - * SilcUInt32 silc_utf8_decode(const unsigned char *utf8, - * SilcUInt32 utf8_len, - * SilcStringEncoding bin_encoding, - * unsigned char *bin, SilcUInt32 bin_size); + * SilcBool + * silc_identifier_check(const unsigned char *identifier, + * SilcUInt32 identifier_len, + * SilcStringEncoding identifier_encoding, + * SilcUInt32 max_allowed_length); * * DESCRIPTION * - * Decodes UTF-8 encoded string `utf8' to string of which encoding is - * to be `bin_encoding', into the `bin' buffer of size of `bin_size'. - * Returns the length of the decoded buffer, or zero (0) on error. - * By default `bin_encoding' is ASCII, and the caller needs to know to - * which encoding the output string is to be encoded if ASCII is not - * desired. + * Checks that the 'identifier' string is valid identifier string + * and does not contain any unassigned or prohibited character. This + * function is used to check for valid nicknames, server names, + * usernames, hostnames, service names, algorithm names, other security + * property names, and SILC Public Key name. + * + * If the 'max_allowed_length' is non-zero the identifier cannot be + * longer than that, and NULL is returned if it is. If zero (0), no + * length limit exist. For nicknames the max length must be 128 bytes. + * Other identifiers has no default limit, but application may choose + * one anyway. + * + * Returns TRUE if the string is valid and FALSE if it is prohibited. * ***/ -SilcUInt32 silc_utf8_decode(const unsigned char *utf8, SilcUInt32 utf8_len, - SilcStringEncoding bin_encoding, - unsigned char *bin, SilcUInt32 bin_size); +SilcBool silc_identifier_verify(const unsigned char *identifier, + SilcUInt32 identifier_len, + SilcStringEncoding identifier_encoding, + SilcUInt32 max_allowed_length); -/****f* silcutil/SilcStrUtilAPI/silc_utf8_encoded_len +/****f* silcutil/SilcStrUtilAPI/silc_channel_name_check * * SYNOPSIS * - * SilcUInt32 silc_utf8_encoded_len(const unsigned char *bin, - * SilcUInt32 bin_len, - * SilcStringEncoding bin_encoding); + * unsigned char * + * silc_channel_name_check(const unsigned char *identifier, + * SilcUInt32 identifier_len, + * SilcStringEncoding identifier_encoding, + * SilcUInt32 max_allowed_length, + * SilcUInt32 *out_len); * * DESCRIPTION * - * Returns the length of UTF-8 encoded string if the `bin' of - * encoding of `bin_encoding' is encoded with silc_utf8_encode. + * Checks that the 'identifier' string is valid channel name string + * and does not contain any unassigned or prohibited character. + * + * If the 'max_allowed_length' is non-zero the identifier cannot be + * longer than that, and NULL is returned if it is. If zero (0), no + * length limit exist. For channel names the max length must be 256 + * bytes. + * + * Returns the validated string, that the caller must free. Returns + * NULL if the identifier string is not valid or contain unassigned or + * prohibited characters. Such identifier strings must not be used + * SILC protocol. The returned string is always in UTF-8 encoding. + * The length of the returned string is in 'out_len'. + * + * NOTES + * + * In addition of validating the channel name string, this function + * may map characters to other characters or remove characters from the + * original string. This is done as defined in the SILC protocol. Error + * is returned only if the string contains unassigned or prohibited + * characters. The original 'identifier' is not modified at any point. * ***/ -SilcUInt32 silc_utf8_encoded_len(const unsigned char *bin, SilcUInt32 bin_len, - SilcStringEncoding bin_encoding); +unsigned char *silc_channel_name_check(const unsigned char *identifier, + SilcUInt32 identifier_len, + SilcStringEncoding identifier_encoding, + SilcUInt32 max_allowed_length, + SilcUInt32 *out_len); -/****f* silcutil/SilcStrUtilAPI/silc_utf8_valid +/****f* silcutil/SilcStrUtilAPI/silc_channel_name_verify * * SYNOPSIS * - * bool silc_utf8_valid(const unsigned char *utf8, SilcUInt32 utf8_len); + * SilcBool + * silc_channel_name_check(const unsigned char *identifier, + * SilcUInt32 identifier_len, + * SilcStringEncoding identifier_encoding, + * SilcUInt32 max_allowed_length); * * DESCRIPTION * - * Returns TRUE if the `utf8' string of length of `utf8_len' is valid - * UTF-8 encoded string, FALSE if it is not UTF-8 encoded string. + * Checks that the 'identifier' string is valid channel name string + * and does not contain any unassigned or prohibited character. + * + * If the 'max_allowed_length' is non-zero the identifier cannot be + * longer than that, and NULL is returned if it is. If zero (0), no + * length limit exist. For channel names the max length must be 256 + * bytes. + * + * Returns TRUE if the string is valid and FALSE if it is prohibited. * ***/ -bool silc_utf8_valid(const unsigned char *utf8, SilcUInt32 utf8_len); - +SilcBool silc_channel_name_verify(const unsigned char *identifier, + SilcUInt32 identifier_len, + SilcStringEncoding identifier_encoding, + SilcUInt32 max_allowed_length); #endif /* SILCSTRUTIL_H */