X-Git-Url: http://git.silcnet.org/gitweb/?p=silc.git;a=blobdiff_plain;f=lib%2Fsilcutil%2Fsilcstrutil.h;h=43ad42fbd498ee5502fbdfc91e97365fc3c3fad3;hp=35e9781227bbbf520bceafcf5318ba32ab9d476e;hb=c257b555225193e54d85daf541d29578b3c93882;hpb=f658940d02cf2fd893296b6a7825b42502573668 diff --git a/lib/silcutil/silcstrutil.h b/lib/silcutil/silcstrutil.h index 35e97812..43ad42fb 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 - 2003 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 @@ -30,6 +30,43 @@ #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,180 +111,208 @@ 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 - * - * NAME - * - * typedef enum { ... } SilcStringEncoding; - * - * DESCRIPTION - * - * String encoding definitions used with the UTF-8 encoding and - * decoding functions. By default, systems should use SILC_STRING_LANGUAGE - * since it encodes and decodes correctly according to local system - * language and character set. - * - * 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_LANGUAGE = 6, /* Language and charset specific conversion - on those platforms that support iconv(). - Fallback is SILC_STRING_ASCII. */ -} SilcStringEncoding; -/***/ - -/****f* silcutil/SilcStrUtilAPI/silc_utf8_encode +/****f* silcutil/SilcStrUtilAPI/silc_mime_parse * * SYNOPSIS * - * SilcUInt32 silc_utf8_encode(const unsigned char *bin, SilcUInt32 bin_len, - * SilcStringEncoding bin_encoding, - * unsigned char *utf8, SilcUInt32 utf8_size); + * 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); * * 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. + * 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. * ***/ -SilcUInt32 silc_utf8_encode(const unsigned char *bin, SilcUInt32 bin_len, - SilcStringEncoding bin_encoding, - unsigned char *utf8, SilcUInt32 utf8_size); +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); -/****f* silcutil/SilcStrUtilAPI/silc_utf8_decode +/****f* silcutil/SilcStrUtilAPI/silc_strncat * * SYNOPSIS * - * SilcUInt32 silc_utf8_decode(const unsigned char *utf8, - * SilcUInt32 utf8_len, - * SilcStringEncoding bin_encoding, - * unsigned char *bin, SilcUInt32 bin_size); + * char *silc_strncat(char *dest, SilcUInt32 dest_size, + * const char *src, SilcUInt32 src_len); * * 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. + * 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. * ***/ -SilcUInt32 silc_utf8_decode(const unsigned char *utf8, SilcUInt32 utf8_len, - SilcStringEncoding bin_encoding, - unsigned char *bin, SilcUInt32 bin_size); +char *silc_strncat(char *dest, SilcUInt32 dest_size, + const char *src, SilcUInt32 src_len); -/****f* silcutil/SilcStrUtilAPI/silc_utf8_encoded_len +/****f* silcutil/SilcStrUtilAPI/silc_identifier_check * * SYNOPSIS * - * SilcUInt32 silc_utf8_encoded_len(const unsigned char *bin, - * SilcUInt32 bin_len, - * SilcStringEncoding bin_encoding); + * unsigned char * + * silc_identifier_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 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. * - ***/ -SilcUInt32 silc_utf8_encoded_len(const unsigned char *bin, SilcUInt32 bin_len, - SilcStringEncoding bin_encoding); - -/****f* silcutil/SilcStrUtilAPI/silc_utf8_decoded_len - * - * 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_decoded_len(const unsigned char *bin, - * SilcUInt32 bin_len, - * SilcStringEncoding bin_encoding); + * 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 * - * Returns the length of decoded string if the `bin' of encoding of - * `bin_encoding' is decoded with silc_utf8_decode. + * 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_decoded_len(const unsigned char *bin, SilcUInt32 bin_len, - SilcStringEncoding bin_encoding); +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_valid +/****f* silcutil/SilcStrUtilAPI/silc_identifier_verify * * SYNOPSIS * - * bool silc_utf8_valid(const unsigned char *utf8, SilcUInt32 utf8_len); + * bool + * silc_identifier_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 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. * ***/ -bool silc_utf8_valid(const unsigned char *utf8, SilcUInt32 utf8_len); +bool silc_identifier_verify(const unsigned char *identifier, + SilcUInt32 identifier_len, + SilcStringEncoding identifier_encoding, + SilcUInt32 max_allowed_length); -/****f* silcutil/SilcStrUtilAPI/silc_mime_parse +/****f* silcutil/SilcStrUtilAPI/silc_channel_name_check * * 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); + * unsigned char * + * silc_channel_name_check(const unsigned char *identifier, + * SilcUInt32 identifier_len, + * SilcStringEncoding identifier_encoding, + * SilcUInt32 max_allowed_length, + * SilcUInt32 *out_len); * * 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. + * Checks that the 'identifier' string is valid channel name string + * and does not contain any unassigned or prohibited character. * - * 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. + * 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_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); +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_strncat +/****f* silcutil/SilcStrUtilAPI/silc_channel_name_verify * * SYNOPSIS * - * char *silc_strncat(char *dest, SilcUInt32 dest_size, - * const char *src, SilcUInt32 src_len); + * bool + * silc_channel_name_check(const unsigned char *identifier, + * SilcUInt32 identifier_len, + * SilcStringEncoding identifier_encoding, + * SilcUInt32 max_allowed_length); * * DESCRIPTION * - * 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. + * 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. * ***/ -char *silc_strncat(char *dest, SilcUInt32 dest_size, - const char *src, SilcUInt32 src_len); +bool silc_channel_name_verify(const unsigned char *identifier, + SilcUInt32 identifier_len, + SilcStringEncoding identifier_encoding, + SilcUInt32 max_allowed_length); #endif /* SILCSTRUTIL_H */