X-Git-Url: http://git.silcnet.org/gitweb/?a=blobdiff_plain;f=lib%2Fsilcutil%2Fsilcstrutil.h;h=3d96492f9169ca2231a420c79068fcefe48140d7;hb=40f8443d8d3a6577336ee66d18e04d9ac4d956bb;hp=e72b4d446c5168f0be7a19c3efdfcbbde8be6c5d;hpb=0b55012d620ee13dce587df51b11139dca26ec09;p=silc.git diff --git a/lib/silcutil/silcstrutil.h b/lib/silcutil/silcstrutil.h index e72b4d44..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,141 +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 - * 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. - * - ***/ -SilcUInt32 silc_utf8_encode(const unsigned char *bin, SilcUInt32 bin_len, - SilcStringEncoding bin_encoding, - unsigned char *utf8, SilcUInt32 utf8_size); - -/****f* silcutil/SilcStrUtilAPI/silc_utf8_decode + * 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. * - * SYNOPSIS + * 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. * - * SilcUInt32 silc_utf8_decode(const unsigned char *utf8, - * SilcUInt32 utf8_len, - * SilcStringEncoding bin_encoding, - * unsigned char *bin, SilcUInt32 bin_size); + * 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'. * - * DESCRIPTION + * NOTES * - * 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. + * 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_decode(const unsigned char *utf8, SilcUInt32 utf8_len, - SilcStringEncoding bin_encoding, - unsigned char *bin, SilcUInt32 bin_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_encoded_len +/****f* silcutil/SilcStrUtilAPI/silc_identifier_verify * * SYNOPSIS * - * SilcUInt32 silc_utf8_encoded_len(const unsigned char *bin, - * SilcUInt32 bin_len, - * SilcStringEncoding bin_encoding); + * SilcBool + * silc_identifier_check(const unsigned char *identifier, + * SilcUInt32 identifier_len, + * SilcStringEncoding identifier_encoding, + * SilcUInt32 max_allowed_length); * * 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 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_encoded_len(const unsigned char *bin, SilcUInt32 bin_len, - SilcStringEncoding bin_encoding); +SilcBool silc_identifier_verify(const unsigned char *identifier, + SilcUInt32 identifier_len, + SilcStringEncoding identifier_encoding, + SilcUInt32 max_allowed_length); -/****f* silcutil/SilcStrUtilAPI/silc_utf8_valid +/****f* silcutil/SilcStrUtilAPI/silc_channel_name_check * * SYNOPSIS * - * bool silc_utf8_valid(const unsigned char *utf8, SilcUInt32 utf8_len); + * 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 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 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. * ***/ -bool silc_utf8_valid(const unsigned char *utf8, SilcUInt32 utf8_len); +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_mime_parse +/****f* silcutil/SilcStrUtilAPI/silc_channel_name_verify * * SYNOPSIS * - * bool - * silc_mime_parse(const unsigned char *mime, SilcUInt32 mime_len, - * char *version, SilcUInt32 version_size, - * char *content_type, SilcUInt32 content_type_size, - * char *transfer_encoding, - * SilcUInt32 transfer_encoding_size, - * unsigned char **mime_data_ptr, - * SilcUInt32 *mime_data_len); + * SilcBool + * silc_channel_name_check(const unsigned char *identifier, + * SilcUInt32 identifier_len, + * SilcStringEncoding identifier_encoding, + * SilcUInt32 max_allowed_length); * * DESCRIPTION * - * Parses MIME header indicated by `mime' data block of length of - * `mime_len'. Returns TRUE if the `mime' is valid MIME object. - * Parses from the MIME header the MIME Version (if present) and - * copies it to the `version' pointer if provided, content type - * indicating the data in the MIME object and copies it to the - * `content_type' if provided, and the tranfer encoding (if present) - * indicating the encoding of the data and copies it to the - * `content_transfer_encoding' if provided. - * - * The pointer to the actual data in the MIME object is saved into - * `mime_data_ptr'. The pointer is a location in the `mime' and it - * does not allocate or copy anything, ie. the `mime_data_ptr' is a - * pointer to the `mime'. The `mime_data_len' indicates the length of - * the data without the MIME header. The caller is responsible of - * NULL terminating the buffers it provides. + * 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_mime_parse(const unsigned char *mime, SilcUInt32 mime_len, - char *version, SilcUInt32 version_size, - char *content_type, SilcUInt32 content_type_size, - char *transfer_encoding, SilcUInt32 transfer_encoding_size, - unsigned char **mime_data_ptr, SilcUInt32 *mime_data_len); +SilcBool silc_channel_name_verify(const unsigned char *identifier, + SilcUInt32 identifier_len, + SilcStringEncoding identifier_encoding, + SilcUInt32 max_allowed_length); #endif /* SILCSTRUTIL_H */