1 /* $NetBSD: res.h,v 1.4 2014/12/10 04:37:55 christos Exp $ */ 2 3 /* Id: res.h,v 1.1 2003/06/04 00:25:41 marka Exp */ 4 /* 5 * Copyright (c) 2001,2002 Japan Network Information Center. 6 * All rights reserved. 7 * 8 * By using this file, you agree to the terms and conditions set forth bellow. 9 * 10 * LICENSE TERMS AND CONDITIONS 11 * 12 * The following License Terms and Conditions apply, unless a different 13 * license is obtained from Japan Network Information Center ("JPNIC"), 14 * a Japanese association, Kokusai-Kougyou-Kanda Bldg 6F, 2-3-4 Uchi-Kanda, 15 * Chiyoda-ku, Tokyo 101-0047, Japan. 16 * 17 * 1. Use, Modification and Redistribution (including distribution of any 18 * modified or derived work) in source and/or binary forms is permitted 19 * under this License Terms and Conditions. 20 * 21 * 2. Redistribution of source code must retain the copyright notices as they 22 * appear in each source code file, this License Terms and Conditions. 23 * 24 * 3. Redistribution in binary form must reproduce the Copyright Notice, 25 * this License Terms and Conditions, in the documentation and/or other 26 * materials provided with the distribution. For the purposes of binary 27 * distribution the "Copyright Notice" refers to the following language: 28 * "Copyright (c) 2000-2002 Japan Network Information Center. All rights reserved." 29 * 30 * 4. The name of JPNIC may not be used to endorse or promote products 31 * derived from this Software without specific prior written approval of 32 * JPNIC. 33 * 34 * 5. Disclaimer/Limitation of Liability: THIS SOFTWARE IS PROVIDED BY JPNIC 35 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 36 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A 37 * PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL JPNIC BE LIABLE 38 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 39 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 40 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR 41 * BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 42 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 43 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF 44 * ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. 45 */ 46 47 #ifndef IDN_RES_H 48 #define IDN_RES_H 1 49 50 #ifdef __cplusplus 51 extern "C" { 52 #endif 53 54 /* 55 * Resolver library support. 56 * 57 * All the functions provided by this module requires IDN resolver 58 * configuration context of type 'idn_resconf_t' as an argument. 59 * This context holds information described in the configuration file 60 * (idn.conf). See idn_resconf module for details. 61 * 62 * All functions also accept NULL as the context, but since 63 * no conversion/normalization will be done in this case, it is 64 * pretty useless. 65 */ 66 67 #include <idn/export.h> 68 #include <idn/resconf.h> 69 #include <idn/result.h> 70 71 typedef unsigned long idn_action_t; 72 73 /* 74 * Actions 75 */ 76 #define IDN_LOCALCONV 0x00000001 /* Local encoding <-> UTF-8 conversion */ 77 #define IDN_DELIMMAP 0x00000002 /* Delimiter mapping */ 78 #define IDN_LOCALMAP 0x00000004 /* Local mapping */ 79 #define IDN_MAP 0x00000008 /* NAMEPREP map */ 80 #define IDN_NORMALIZE 0x00000010 /* NAMEPREP normalize */ 81 #define IDN_PROHCHECK 0x00000020 /* NAMEPREP prohibited character check */ 82 #define IDN_UNASCHECK 0x00000040 /* Unassigned code point check */ 83 #define IDN_BIDICHECK 0x00000080 /* bidirectional string check */ 84 #define IDN_ASCCHECK 0x00000100 /* Non-LDH ASCII check */ 85 #define IDN_IDNCONV 0x00000200 /* UTF-8 <-> IDN encoding conversion */ 86 #define IDN_LENCHECK 0x00000400 /* Label length check */ 87 #define IDN_RTCHECK 0x00000800 /* Round trip check */ 88 #define IDN_UNDOIFERR 0x00001000 /* Option: undo if error occurs */ 89 90 #define IDN_ENCODE_QUERY 0x00002000 /* Encode query string */ 91 #define IDN_DECODE_QUERY 0x00004000 /* Decode query string */ 92 93 #define IDN_ENCODE_APP \ 94 (IDN_ENCODE_QUERY | IDN_ASCCHECK) /* Standard encode */ 95 #define IDN_DECODE_APP \ 96 (IDN_DECODE_QUERY | IDN_ASCCHECK) /* Standard decode */ 97 98 #define IDN_ENCODE_STORED \ 99 (IDN_ENCODE_QUERY | IDN_ASCCHECK | IDN_UNASCHECK) /* Encode query string */ 100 #define IDN_DECODE_STORED \ 101 (IDN_DECODE_QUERY | IDN_ASCCHECK | IDN_UNASCHECK) /* Decode query string */ 102 103 104 #define IDN_NAMEPREP \ 105 (IDN_MAP | IDN_NORMALIZE | IDN_PROHCHECK | IDN_BIDICHECK) 106 107 /* 108 * Enable or disable IDN conversion scheme. 109 * 110 * If on_off is 0, IDN conversion scheme is disabled. Otherwise, IDN 111 * conversion is enabled even when IDN_DISABLE is defined. 112 */ 113 IDN_EXPORT void 114 idn_res_enable(int on_off); 115 116 /* 117 * Encode internationalized domain name. 118 * 119 * The encoding process consists of the following 7 steps. 120 * 121 * 1. Local encoding to UTF-8 conversion 122 * Converts a domain name written with local encoding (e.g. ISO- 123 * 8859-1) to UTF-8. 124 * 2. Delimiter mapping, 125 * Maps certain characters to period (U+002E, FULL STOP). 126 * 3. Local mapping 127 * Apply character mappings according with the TLD of the domain 128 * name. 129 * 4. NAMEPREP 130 * Perform NAME preparation described in RFC3491. 131 * This step consists of the following 4 steps: 132 * 4.1. Mapping 133 * 4.2. Normalization 134 * 4.3. Prohibited character check 135 * 4.4. Unassigned check 136 * 5. ASCII range character check 137 * Checks if the domain name contains non-LDH ASCII character (not 138 * alpha-numeric or hypen), or it begins or end with hypen. 139 * 6. UTF-8 to IDN encoding conversion. 140 * Converts the domain name from UTF-8 to ACE (e.g. Punycode). 141 * 7. Length check 142 * Checks the length of each label. 143 * 144 * 'actions' specifies actions and options of the encoding procedure. 145 * Its value is a bitwise-or of the following flags: 146 * 147 * IDN_LOCALCONV -- perform local encoding to UTF-8 conversion (step 1) 148 * IDN_DELIMMAP -- perform delimiter mapping (step 2) 149 * IDN_LOCALMAP -- perform local mapping (step 3) 150 * IDN_MAP -- perform mapping (step 4.1) 151 * IDN_NORMALIZE -- perform normalization (step 4.2) 152 * IDN_PROHCHECK -- perform prohibited character check (step 4.3) 153 * IDN_UNASCHECK -- perform unassigned codepoint check (step 4.4) 154 * IDN_ASCCHECK -- perform ASCII range character check (step 5) 155 * IDN_IDNCONV -- perform UTF-8 to IDN encoding conversion (step 6) 156 * IDN_LENCHECK -- perform length check (step 7) 157 * 158 * Also the following flags are provided for convinience: 159 * 160 * IDN_ENCODE_QUERY -- On libidnkit, perform step 1..7, except for step 161 * 4.4 and 5. 162 * On libidnkitlite, perform step 2..7, except for 163 * step 4.4 and 5. 164 * IDN_ENCODE_STORED -- On libidnkit, perform step 1..7, except for step 165 * 5. 166 * On libidnkitlite, perform step 2..7, except for 167 * step 5. 168 * IDN_ENCODE_APP -- Same as IDN_ENCODE_QUERY. 169 * IDN_NAMEPREP -- perform NAMEPREP (step 4) without unassigned 170 * codepoint check (step 4.4). 171 * 172 * The following flag does not corresponding to a particular action, 173 * but an option of conversion process: 174 * 175 * IDN_UNDOIFERR -- If any step fails, the original input name is 176 * returned. 177 * 178 * Note that if no flags are specified, 'idn_encodename' does nothing 179 * fancy, just copies the given name verbatim. 180 * 181 * Returns: 182 * idn_success -- ok. 183 * idn_invalid_action -- invalid action flag specified. 184 * idn_invalid_encoding -- the given string has invalid/illegal 185 * byte sequence. 186 * idn_invalid_length -- invalid length of a label. 187 * idn_prohibited -- prohibited/unassigned code point found. 188 * idn_buffer_overflow -- 'tolen' is too small. 189 * idn_nomemory -- malloc failed. 190 * 191 * Also, if this function is called without calling 'idn_nameinit', 192 * the following error codes might be returned. 193 * idn_nofile -- cannot open the configuration file. 194 * idn_invalid_syntax -- syntax error found in the file. 195 * idn_invalid_name -- there are invalid names (encoding, 196 * normalization etc.). 197 */ 198 IDN_EXPORT idn_result_t 199 idn_res_encodename(idn_resconf_t ctx, idn_action_t actions, const char *from, 200 char *to, size_t tolen); 201 202 /* 203 * Decode internationalized domain name. 204 * 205 * The decoding process consists of the following 5 steps. 206 * 207 * 1. delimiter mapping 208 * Maps certain characters to period (U+002E, FULL STOP). 209 * 2. NAMEPREP 210 * Perform NAME preparation described in RFC3491. 211 * This step consists of the following 4 steps: 212 * 2.1. Mapping 213 * 2.2. Normalization 214 * 2.3. Prohibited character check 215 * 2.4. Unassigned check 216 * 3. IDN encoding to UTF-8 conversion. 217 * Converts the domain name from ACE (e.g. Punycode) to UCS4. 218 * 4. Perform round-trip check. 219 * Encode the result of step 3, and then compare it with the result 220 * of the step 2. If they are different, the check is failed. 221 * 5. Convert UTF-8 to local encoding. 222 * If a character in the domain name cannot be converted to local 223 * encoding, the conversion is failed. 224 * 225 * 'actions' specifies actions of the decoding procedure. 226 * Its value is a bitwise-or of the following flags: 227 * 228 * IDN_DELIMMAP -- perform delimiter mapping (step 1) 229 * IDN_MAP -- perform mapping (step 2.1) 230 * IDN_NORMALIZE -- perform normalization (step 2.2) 231 * IDN_PROHCHECK -- perform prohibited character check (step 2.3) 232 * IDN_UNASCHECK -- perform unassigned codepoint check (step 2.4) 233 * IDN_IDNCONV -- perform IDN encoding to UTF-8 conversion (step 3) 234 * IDN_RTCHECK -- perform round-trip check (step 4) 235 * IDN_ASCCHECK -- perform ASCII range character check while 236 * round-trip check (step 4.1) 237 * IDN_LOCALCONV -- perform UTF-8 to local encoding conversion (step 5) 238 * 239 * Also the following flags are provided for the convenience: 240 * 241 * IDN_DECODE_QUERY -- On libidnkit, perform step 1..5, except for step 242 * 2.4 and 4.1. 243 * On libidnkitlite, perform step 1..3, except for 244 * step 2.4 and 4.1. 245 * IDN_DECODE_STORED -- On libidnkit, perform step 1..5, except for step 246 * 4.1. 247 * On libidnkitlite, perform step 1..3, except for 248 * step 4.1. 249 * IDN_DECODE_APP -- Same as IDN_DECODE_QUERY. 250 * IDN_NAMEPREP -- perform NAMEPREP (step 2) without unassigned 251 * codepoint check (step 2.4). 252 * 253 * If any step fails, the original input name is returned. 254 * 'actions' specifies what actions to take when decoding, and is 255 * a bitwise-or of the following flags: 256 * 257 * Note that if no flags are specified, 'idn_decodename' does nothing 258 * but copying the given name verbatim. 259 * 260 * Returns: 261 * idn_success -- ok. 262 * idn_invalid_action -- invalid action flag specified. 263 * idn_invalid_encoding -- the given string has invalid/illegal 264 * byte sequence. 265 * idn_buffer_overflow -- 'tolen' is too small. 266 * idn_invalid_action -- length of a label is not 1..63 characters. 267 * idn_nomemory -- malloc failed. 268 * 269 * Also, if this function is called without calling 'idn_nameinit', 270 * the following error codes might be returned. 271 * idn_nofile -- cannot open the configuration file. 272 * idn_invalid_syntax -- syntax error found in the file. 273 * idn_invalid_name -- there are invalid names (encoding, 274 * normalization etc.). 275 */ 276 IDN_EXPORT idn_result_t 277 idn_res_decodename(idn_resconf_t ctx, idn_action_t actions, const char *from, 278 char *to, size_t tolen); 279 280 /* 281 * Decode internationalized domain name with auxiliary encoding 282 * support. 283 * 284 * This is another API for IDN string decode. The difference between 285 * two is whether the encoding conversion from auxiliary encoding to 286 * UTF-8 occurs prior to the actual decode process (read description 287 * of idn_res_decodename() above) or not. 288 * 289 * If auxencoding is NULL, from is treated as UTF-8 encoded string. 290 * 291 * Other arguments serve exactly same role as those of 292 * idn_res_decodename(). 293 */ 294 idn_result_t 295 idn_res_decodename2(idn_resconf_t ctx, idn_action_t actions, const char *from, 296 char *to, size_t tolen, const char *auxencoding); 297 298 /* 299 * Convert `actions' to a string, and then return the string. 300 * This function is for internal use only. 301 * 302 * Note that this function returns a pointer to static buffer. 303 */ 304 extern const char * 305 idn__res_actionstostring(idn_action_t actions); 306 307 #ifdef __cplusplus 308 } 309 #endif 310 311 #endif /* IDN_RES_H */ 312