/*
- silcstrutil.h
+ silcstrutil.h
Author: Pekka Riikonen <priikone@silcnet.org>
- 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
#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
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 */
projects / silc.git / blobdiff