1 // © 2016 and later: Unicode, Inc. and others. 2 // License & terms of use: http://www.unicode.org/copyright.html 3 /* 4 *************************************************************************** 5 * Copyright (C) 2008-2016, International Business Machines Corporation 6 * and others. All Rights Reserved. 7 *************************************************************************** 8 * file name: uspoof.h 9 * encoding: UTF-8 10 * tab size: 8 (not used) 11 * indentation:4 12 * 13 * created on: 2008Feb13 14 * created by: Andy Heninger 15 * 16 * Unicode Spoof Detection 17 */ 18 19 #ifndef USPOOF_H 20 #define USPOOF_H 21 22 #include "unicode/utypes.h" 23 #include "unicode/uset.h" 24 #include "unicode/parseerr.h" 25 26 #if !UCONFIG_NO_NORMALIZATION 27 28 29 #if U_SHOW_CPLUSPLUS_API 30 #include "unicode/localpointer.h" 31 #include "unicode/unistr.h" 32 #include "unicode/uniset.h" 33 #endif 34 35 36 /** 37 * \file 38 * \brief Unicode Security and Spoofing Detection, C API. 39 * 40 * <p> 41 * This class, based on <a href="http://unicode.org/reports/tr36">Unicode Technical Report #36</a> and 42 * <a href="http://unicode.org/reports/tr39">Unicode Technical Standard #39</a>, has two main functions: 43 * 44 * <ol> 45 * <li>Checking whether two strings are visually <em>confusable</em> with each other, such as "Harvest" and 46 * "Ηarvest", where the second string starts with the Greek capital letter Eta.</li> 47 * <li>Checking whether an individual string is likely to be an attempt at confusing the reader (<em>spoof 48 * detection</em>), such as "paypal" with some Latin characters substituted with Cyrillic look-alikes.</li> 49 * </ol> 50 * 51 * <p> 52 * Although originally designed as a method for flagging suspicious identifier strings such as URLs, 53 * <code>USpoofChecker</code> has a number of other practical use cases, such as preventing attempts to evade bad-word 54 * content filters. 55 * 56 * <p> 57 * The functions of this class are exposed as C API, with a handful of syntactical conveniences for C++. 58 * 59 * <h2>Confusables</h2> 60 * 61 * <p> 62 * The following example shows how to use <code>USpoofChecker</code> to check for confusability between two strings: 63 * 64 * \code{.c} 65 * UErrorCode status = U_ZERO_ERROR; 66 * UChar* str1 = (UChar*) u"Harvest"; 67 * UChar* str2 = (UChar*) u"\u0397arvest"; // with U+0397 GREEK CAPITAL LETTER ETA 68 * 69 * USpoofChecker* sc = uspoof_open(&status); 70 * uspoof_setChecks(sc, USPOOF_CONFUSABLE, &status); 71 * 72 * int32_t bitmask = uspoof_areConfusable(sc, str1, -1, str2, -1, &status); 73 * UBool result = bitmask != 0; 74 * // areConfusable: 1 (status: U_ZERO_ERROR) 75 * printf("areConfusable: %d (status: %s)\n", result, u_errorName(status)); 76 * uspoof_close(sc); 77 * \endcode 78 * 79 * <p> 80 * The call to {@link uspoof_open} creates a <code>USpoofChecker</code> object; the call to {@link uspoof_setChecks} 81 * enables confusable checking and disables all other checks; the call to {@link uspoof_areConfusable} performs the 82 * confusability test; and the following line extracts the result out of the return value. For best performance, 83 * the instance should be created once (e.g., upon application startup), and the efficient 84 * {@link uspoof_areConfusable} method can be used at runtime. 85 * 86 * <p> 87 * The type {@link LocalUSpoofCheckerPointer} is exposed for C++ programmers. It will automatically call 88 * {@link uspoof_close} when the object goes out of scope: 89 * 90 * \code{.cpp} 91 * UErrorCode status = U_ZERO_ERROR; 92 * LocalUSpoofCheckerPointer sc(uspoof_open(&status)); 93 * uspoof_setChecks(sc.getAlias(), USPOOF_CONFUSABLE, &status); 94 * // ... 95 * \endcode 96 * 97 * UTS 39 defines two strings to be <em>confusable</em> if they map to the same <em>skeleton string</em>. A skeleton can 98 * be thought of as a "hash code". {@link uspoof_getSkeleton} computes the skeleton for a particular string, so 99 * the following snippet is equivalent to the example above: 100 * 101 * \code{.c} 102 * UErrorCode status = U_ZERO_ERROR; 103 * UChar* str1 = (UChar*) u"Harvest"; 104 * UChar* str2 = (UChar*) u"\u0397arvest"; // with U+0397 GREEK CAPITAL LETTER ETA 105 * 106 * USpoofChecker* sc = uspoof_open(&status); 107 * uspoof_setChecks(sc, USPOOF_CONFUSABLE, &status); 108 * 109 * // Get skeleton 1 110 * int32_t skel1Len = uspoof_getSkeleton(sc, 0, str1, -1, NULL, 0, &status); 111 * UChar* skel1 = (UChar*) malloc(++skel1Len * sizeof(UChar)); 112 * status = U_ZERO_ERROR; 113 * uspoof_getSkeleton(sc, 0, str1, -1, skel1, skel1Len, &status); 114 * 115 * // Get skeleton 2 116 * int32_t skel2Len = uspoof_getSkeleton(sc, 0, str2, -1, NULL, 0, &status); 117 * UChar* skel2 = (UChar*) malloc(++skel2Len * sizeof(UChar)); 118 * status = U_ZERO_ERROR; 119 * uspoof_getSkeleton(sc, 0, str2, -1, skel2, skel2Len, &status); 120 * 121 * // Are the skeletons the same? 122 * UBool result = u_strcmp(skel1, skel2) == 0; 123 * // areConfusable: 1 (status: U_ZERO_ERROR) 124 * printf("areConfusable: %d (status: %s)\n", result, u_errorName(status)); 125 * uspoof_close(sc); 126 * free(skel1); 127 * free(skel2); 128 * \endcode 129 * 130 * If you need to check if a string is confusable with any string in a dictionary of many strings, rather than calling 131 * {@link uspoof_areConfusable} many times in a loop, {@link uspoof_getSkeleton} can be used instead, as shown below: 132 * 133 * \code{.c} 134 * UErrorCode status = U_ZERO_ERROR; 135 * #define DICTIONARY_LENGTH 2 136 * UChar* dictionary[DICTIONARY_LENGTH] = { (UChar*) u"lorem", (UChar*) u"ipsum" }; 137 * UChar* skeletons[DICTIONARY_LENGTH]; 138 * UChar* str = (UChar*) u"1orern"; 139 * 140 * // Setup: 141 * USpoofChecker* sc = uspoof_open(&status); 142 * uspoof_setChecks(sc, USPOOF_CONFUSABLE, &status); 143 * for (size_t i=0; i<DICTIONARY_LENGTH; i++) { 144 * UChar* word = dictionary[i]; 145 * int32_t len = uspoof_getSkeleton(sc, 0, word, -1, NULL, 0, &status); 146 * skeletons[i] = (UChar*) malloc(++len * sizeof(UChar)); 147 * status = U_ZERO_ERROR; 148 * uspoof_getSkeleton(sc, 0, word, -1, skeletons[i], len, &status); 149 * } 150 * 151 * // Live Check: 152 * { 153 * int32_t len = uspoof_getSkeleton(sc, 0, str, -1, NULL, 0, &status); 154 * UChar* skel = (UChar*) malloc(++len * sizeof(UChar)); 155 * status = U_ZERO_ERROR; 156 * uspoof_getSkeleton(sc, 0, str, -1, skel, len, &status); 157 * UBool result = false; 158 * for (size_t i=0; i<DICTIONARY_LENGTH; i++) { 159 * result = u_strcmp(skel, skeletons[i]) == 0; 160 * if (result == true) { break; } 161 * } 162 * // Has confusable in dictionary: 1 (status: U_ZERO_ERROR) 163 * printf("Has confusable in dictionary: %d (status: %s)\n", result, u_errorName(status)); 164 * free(skel); 165 * } 166 * 167 * for (size_t i=0; i<DICTIONARY_LENGTH; i++) { 168 * free(skeletons[i]); 169 * } 170 * uspoof_close(sc); 171 * \endcode 172 * 173 * <b>Note:</b> Since the Unicode confusables mapping table is frequently updated, confusable skeletons are <em>not</em> 174 * guaranteed to be the same between ICU releases. We therefore recommend that you always compute confusable skeletons 175 * at runtime and do not rely on creating a permanent, or difficult to update, database of skeletons. 176 * 177 * <h2>Spoof Detection</h2> 178 * 179 * The following snippet shows a minimal example of using <code>USpoofChecker</code> to perform spoof detection on a 180 * string: 181 * 182 * \code{.c} 183 * UErrorCode status = U_ZERO_ERROR; 184 * UChar* str = (UChar*) u"p\u0430ypal"; // with U+0430 CYRILLIC SMALL LETTER A 185 * 186 * // Get the default set of allowable characters: 187 * USet* allowed = uset_openEmpty(); 188 * uset_addAll(allowed, uspoof_getRecommendedSet(&status)); 189 * uset_addAll(allowed, uspoof_getInclusionSet(&status)); 190 * 191 * USpoofChecker* sc = uspoof_open(&status); 192 * uspoof_setAllowedChars(sc, allowed, &status); 193 * uspoof_setRestrictionLevel(sc, USPOOF_MODERATELY_RESTRICTIVE); 194 * 195 * int32_t bitmask = uspoof_check(sc, str, -1, NULL, &status); 196 * UBool result = bitmask != 0; 197 * // fails checks: 1 (status: U_ZERO_ERROR) 198 * printf("fails checks: %d (status: %s)\n", result, u_errorName(status)); 199 * uspoof_close(sc); 200 * uset_close(allowed); 201 * \endcode 202 * 203 * As in the case for confusability checking, it is good practice to create one <code>USpoofChecker</code> instance at 204 * startup, and call the cheaper {@link uspoof_check} online. We specify the set of 205 * allowed characters to be those with type RECOMMENDED or INCLUSION, according to the recommendation in UTS 39. 206 * 207 * In addition to {@link uspoof_check}, the function {@link uspoof_checkUTF8} is exposed for UTF8-encoded char* strings, 208 * and {@link uspoof_checkUnicodeString} is exposed for C++ programmers. 209 * 210 * If the {@link USPOOF_AUX_INFO} check is enabled, a limited amount of information on why a string failed the checks 211 * is available in the returned bitmask. For complete information, use the {@link uspoof_check2} class of functions 212 * with a {@link USpoofCheckResult} parameter: 213 * 214 * \code{.c} 215 * UErrorCode status = U_ZERO_ERROR; 216 * UChar* str = (UChar*) u"p\u0430ypal"; // with U+0430 CYRILLIC SMALL LETTER A 217 * 218 * // Get the default set of allowable characters: 219 * USet* allowed = uset_openEmpty(); 220 * uset_addAll(allowed, uspoof_getRecommendedSet(&status)); 221 * uset_addAll(allowed, uspoof_getInclusionSet(&status)); 222 * 223 * USpoofChecker* sc = uspoof_open(&status); 224 * uspoof_setAllowedChars(sc, allowed, &status); 225 * uspoof_setRestrictionLevel(sc, USPOOF_MODERATELY_RESTRICTIVE); 226 * 227 * USpoofCheckResult* checkResult = uspoof_openCheckResult(&status); 228 * int32_t bitmask = uspoof_check2(sc, str, -1, checkResult, &status); 229 * 230 * int32_t failures1 = bitmask; 231 * int32_t failures2 = uspoof_getCheckResultChecks(checkResult, &status); 232 * assert(failures1 == failures2); 233 * // checks that failed: 0x00000010 (status: U_ZERO_ERROR) 234 * printf("checks that failed: %#010x (status: %s)\n", failures1, u_errorName(status)); 235 * 236 * // Cleanup: 237 * uspoof_close(sc); 238 * uset_close(allowed); 239 * uspoof_closeCheckResult(checkResult); 240 * \endcode 241 * 242 * C++ users can take advantage of a few syntactical conveniences. The following snippet is functionally 243 * equivalent to the one above: 244 * 245 * \code{.cpp} 246 * UErrorCode status = U_ZERO_ERROR; 247 * UnicodeString str((UChar*) u"p\u0430ypal"); // with U+0430 CYRILLIC SMALL LETTER A 248 * 249 * // Get the default set of allowable characters: 250 * UnicodeSet allowed; 251 * allowed.addAll(*uspoof_getRecommendedUnicodeSet(&status)); 252 * allowed.addAll(*uspoof_getInclusionUnicodeSet(&status)); 253 * 254 * LocalUSpoofCheckerPointer sc(uspoof_open(&status)); 255 * uspoof_setAllowedChars(sc.getAlias(), allowed.toUSet(), &status); 256 * uspoof_setRestrictionLevel(sc.getAlias(), USPOOF_MODERATELY_RESTRICTIVE); 257 * 258 * LocalUSpoofCheckResultPointer checkResult(uspoof_openCheckResult(&status)); 259 * int32_t bitmask = uspoof_check2UnicodeString(sc.getAlias(), str, checkResult.getAlias(), &status); 260 * 261 * int32_t failures1 = bitmask; 262 * int32_t failures2 = uspoof_getCheckResultChecks(checkResult.getAlias(), &status); 263 * assert(failures1 == failures2); 264 * // checks that failed: 0x00000010 (status: U_ZERO_ERROR) 265 * printf("checks that failed: %#010x (status: %s)\n", failures1, u_errorName(status)); 266 * 267 * // Explicit cleanup not necessary. 268 * \endcode 269 * 270 * The return value is a bitmask of the checks that failed. In this case, there was one check that failed: 271 * {@link USPOOF_RESTRICTION_LEVEL}, corresponding to the fifth bit (16). The possible checks are: 272 * 273 * <ul> 274 * <li><code>RESTRICTION_LEVEL</code>: flags strings that violate the 275 * <a href="http://unicode.org/reports/tr39/#Restriction_Level_Detection">Restriction Level</a> test as specified in UTS 276 * 39; in most cases, this means flagging strings that contain characters from multiple different scripts.</li> 277 * <li><code>INVISIBLE</code>: flags strings that contain invisible characters, such as zero-width spaces, or character 278 * sequences that are likely not to display, such as multiple occurrences of the same non-spacing mark.</li> 279 * <li><code>CHAR_LIMIT</code>: flags strings that contain characters outside of a specified set of acceptable 280 * characters. See {@link uspoof_setAllowedChars} and {@link uspoof_setAllowedLocales}.</li> 281 * <li><code>MIXED_NUMBERS</code>: flags strings that contain digits from multiple different numbering systems.</li> 282 * </ul> 283 * 284 * <p> 285 * These checks can be enabled independently of each other. For example, if you were interested in checking for only the 286 * INVISIBLE and MIXED_NUMBERS conditions, you could do: 287 * 288 * \code{.c} 289 * UErrorCode status = U_ZERO_ERROR; 290 * UChar* str = (UChar*) u"8\u09EA"; // 8 mixed with U+09EA BENGALI DIGIT FOUR 291 * 292 * USpoofChecker* sc = uspoof_open(&status); 293 * uspoof_setChecks(sc, USPOOF_INVISIBLE | USPOOF_MIXED_NUMBERS, &status); 294 * 295 * int32_t bitmask = uspoof_check2(sc, str, -1, NULL, &status); 296 * UBool result = bitmask != 0; 297 * // fails checks: 1 (status: U_ZERO_ERROR) 298 * printf("fails checks: %d (status: %s)\n", result, u_errorName(status)); 299 * uspoof_close(sc); 300 * \endcode 301 * 302 * Here is an example in C++ showing how to compute the restriction level of a string: 303 * 304 * \code{.cpp} 305 * UErrorCode status = U_ZERO_ERROR; 306 * UnicodeString str((UChar*) u"p\u0430ypal"); // with U+0430 CYRILLIC SMALL LETTER A 307 * 308 * // Get the default set of allowable characters: 309 * UnicodeSet allowed; 310 * allowed.addAll(*uspoof_getRecommendedUnicodeSet(&status)); 311 * allowed.addAll(*uspoof_getInclusionUnicodeSet(&status)); 312 * 313 * LocalUSpoofCheckerPointer sc(uspoof_open(&status)); 314 * uspoof_setAllowedChars(sc.getAlias(), allowed.toUSet(), &status); 315 * uspoof_setRestrictionLevel(sc.getAlias(), USPOOF_MODERATELY_RESTRICTIVE); 316 * uspoof_setChecks(sc.getAlias(), USPOOF_RESTRICTION_LEVEL | USPOOF_AUX_INFO, &status); 317 * 318 * LocalUSpoofCheckResultPointer checkResult(uspoof_openCheckResult(&status)); 319 * int32_t bitmask = uspoof_check2UnicodeString(sc.getAlias(), str, checkResult.getAlias(), &status); 320 * 321 * URestrictionLevel restrictionLevel = uspoof_getCheckResultRestrictionLevel(checkResult.getAlias(), &status); 322 * // Since USPOOF_AUX_INFO was enabled, the restriction level is also available in the upper bits of the bitmask: 323 * assert((restrictionLevel & bitmask) == restrictionLevel); 324 * // Restriction level: 0x50000000 (status: U_ZERO_ERROR) 325 * printf("Restriction level: %#010x (status: %s)\n", restrictionLevel, u_errorName(status)); 326 * \endcode 327 * 328 * The code '0x50000000' corresponds to the restriction level USPOOF_MINIMALLY_RESTRICTIVE. Since 329 * USPOOF_MINIMALLY_RESTRICTIVE is weaker than USPOOF_MODERATELY_RESTRICTIVE, the string fails the check. 330 * 331 * <b>Note:</b> The Restriction Level is the most powerful of the checks. The full logic is documented in 332 * <a href="http://unicode.org/reports/tr39/#Restriction_Level_Detection">UTS 39</a>, but the basic idea is that strings 333 * are restricted to contain characters from only a single script, <em>except</em> that most scripts are allowed to have 334 * Latin characters interspersed. Although the default restriction level is <code>HIGHLY_RESTRICTIVE</code>, it is 335 * recommended that users set their restriction level to <code>MODERATELY_RESTRICTIVE</code>, which allows Latin mixed 336 * with all other scripts except Cyrillic, Greek, and Cherokee, with which it is often confusable. For more details on 337 * the levels, see UTS 39 or {@link URestrictionLevel}. The Restriction Level test is aware of the set of 338 * allowed characters set in {@link uspoof_setAllowedChars}. Note that characters which have script code 339 * COMMON or INHERITED, such as numbers and punctuation, are ignored when computing whether a string has multiple 340 * scripts. 341 * 342 * <h2>Additional Information</h2> 343 * 344 * A <code>USpoofChecker</code> instance may be used repeatedly to perform checks on any number of identifiers. 345 * 346 * <b>Thread Safety:</b> The test functions for checking a single identifier, or for testing whether 347 * two identifiers are possible confusable, are thread safe. They may called concurrently, from multiple threads, 348 * using the same USpoofChecker instance. 349 * 350 * More generally, the standard ICU thread safety rules apply: functions that take a const USpoofChecker parameter are 351 * thread safe. Those that take a non-const USpoofChecker are not thread safe.. 352 * 353 * @stable ICU 4.6 354 */ 355 356 U_CDECL_BEGIN 357 358 struct USpoofChecker; 359 /** 360 * @stable ICU 4.2 361 */ 362 typedef struct USpoofChecker USpoofChecker; /**< typedef for C of USpoofChecker */ 363 364 struct USpoofCheckResult; 365 /** 366 * @see uspoof_openCheckResult 367 * @stable ICU 58 368 */ 369 typedef struct USpoofCheckResult USpoofCheckResult; 370 371 /** 372 * Enum for the kinds of checks that USpoofChecker can perform. 373 * These enum values are used both to select the set of checks that 374 * will be performed, and to report results from the check function. 375 * 376 * @stable ICU 4.2 377 */ 378 typedef enum USpoofChecks { 379 /** 380 * When performing the two-string {@link uspoof_areConfusable} test, this flag in the return value indicates 381 * that the two strings are visually confusable and that they are from the same script, according to UTS 39 section 382 * 4. 383 * 384 * @see uspoof_areConfusable 385 * @stable ICU 4.2 386 */ 387 USPOOF_SINGLE_SCRIPT_CONFUSABLE = 1, 388 389 /** 390 * When performing the two-string {@link uspoof_areConfusable} test, this flag in the return value indicates 391 * that the two strings are visually confusable and that they are <b>not</b> from the same script, according to UTS 392 * 39 section 4. 393 * 394 * @see uspoof_areConfusable 395 * @stable ICU 4.2 396 */ 397 USPOOF_MIXED_SCRIPT_CONFUSABLE = 2, 398 399 /** 400 * When performing the two-string {@link uspoof_areConfusable} test, this flag in the return value indicates 401 * that the two strings are visually confusable and that they are not from the same script but both of them are 402 * single-script strings, according to UTS 39 section 4. 403 * 404 * @see uspoof_areConfusable 405 * @stable ICU 4.2 406 */ 407 USPOOF_WHOLE_SCRIPT_CONFUSABLE = 4, 408 409 /** 410 * Enable this flag in {@link uspoof_setChecks} to turn on all types of confusables. You may set 411 * the checks to some subset of SINGLE_SCRIPT_CONFUSABLE, MIXED_SCRIPT_CONFUSABLE, or WHOLE_SCRIPT_CONFUSABLE to 412 * make {@link uspoof_areConfusable} return only those types of confusables. 413 * 414 * @see uspoof_areConfusable 415 * @see uspoof_getSkeleton 416 * @stable ICU 58 417 */ 418 USPOOF_CONFUSABLE = USPOOF_SINGLE_SCRIPT_CONFUSABLE | USPOOF_MIXED_SCRIPT_CONFUSABLE | USPOOF_WHOLE_SCRIPT_CONFUSABLE, 419 420 #ifndef U_HIDE_DEPRECATED_API 421 /** 422 * This flag is deprecated and no longer affects the behavior of SpoofChecker. 423 * 424 * @deprecated ICU 58 Any case confusable mappings were removed from UTS 39; the corresponding ICU API was deprecated. 425 */ 426 USPOOF_ANY_CASE = 8, 427 #endif /* U_HIDE_DEPRECATED_API */ 428 429 /** 430 * Check that an identifier is no looser than the specified RestrictionLevel. 431 * The default if {@link uspoof_setRestrictionLevel} is not called is HIGHLY_RESTRICTIVE. 432 * 433 * If USPOOF_AUX_INFO is enabled the actual restriction level of the 434 * identifier being tested will also be returned by uspoof_check(). 435 * 436 * @see URestrictionLevel 437 * @see uspoof_setRestrictionLevel 438 * @see USPOOF_AUX_INFO 439 * 440 * @stable ICU 51 441 */ 442 USPOOF_RESTRICTION_LEVEL = 16, 443 444 #ifndef U_HIDE_DEPRECATED_API 445 /** Check that an identifier contains only characters from a 446 * single script (plus chars from the common and inherited scripts.) 447 * Applies to checks of a single identifier check only. 448 * @deprecated ICU 51 Use RESTRICTION_LEVEL instead. 449 */ 450 USPOOF_SINGLE_SCRIPT = USPOOF_RESTRICTION_LEVEL, 451 #endif /* U_HIDE_DEPRECATED_API */ 452 453 /** Check an identifier for the presence of invisible characters, 454 * such as zero-width spaces, or character sequences that are 455 * likely not to display, such as multiple occurrences of the same 456 * non-spacing mark. This check does not test the input string as a whole 457 * for conformance to any particular syntax for identifiers. 458 */ 459 USPOOF_INVISIBLE = 32, 460 461 /** Check that an identifier contains only characters from a specified set 462 * of acceptable characters. See {@link uspoof_setAllowedChars} and 463 * {@link uspoof_setAllowedLocales}. Note that a string that fails this check 464 * will also fail the {@link USPOOF_RESTRICTION_LEVEL} check. 465 */ 466 USPOOF_CHAR_LIMIT = 64, 467 468 /** 469 * Check that an identifier does not mix numbers from different numbering systems. 470 * For more information, see UTS 39 section 5.3. 471 * 472 * @stable ICU 51 473 */ 474 USPOOF_MIXED_NUMBERS = 128, 475 476 /** 477 * Check that an identifier does not have a combining character following a character in which that 478 * combining character would be hidden; for example 'i' followed by a U+0307 combining dot. 479 * 480 * More specifically, the following characters are forbidden from preceding a U+0307: 481 * <ul> 482 * <li>Those with the Soft_Dotted Unicode property (which includes 'i' and 'j')</li> 483 * <li>Latin lowercase letter 'l'</li> 484 * <li>Dotless 'i' and 'j' ('ı' and 'ȷ', U+0131 and U+0237)</li> 485 * <li>Any character whose confusable prototype ends with such a character 486 * (Soft_Dotted, 'l', 'ı', or 'ȷ')</li> 487 * </ul> 488 * In addition, combining characters are allowed between the above characters and U+0307 except those 489 * with combining class 0 or combining class "Above" (230, same class as U+0307). 490 * 491 * This list and the number of combing characters considered by this check may grow over time. 492 * 493 * @stable ICU 62 494 */ 495 USPOOF_HIDDEN_OVERLAY = 256, 496 497 /** 498 * Enable all spoof checks. 499 * 500 * @stable ICU 4.6 501 */ 502 USPOOF_ALL_CHECKS = 0xFFFF, 503 504 /** 505 * Enable the return of auxillary (non-error) information in the 506 * upper bits of the check results value. 507 * 508 * If this "check" is not enabled, the results of {@link uspoof_check} will be 509 * zero when an identifier passes all of the enabled checks. 510 * 511 * If this "check" is enabled, (uspoof_check() & {@link USPOOF_ALL_CHECKS}) will 512 * be zero when an identifier passes all checks. 513 * 514 * @stable ICU 51 515 */ 516 USPOOF_AUX_INFO = 0x40000000 517 518 } USpoofChecks; 519 520 521 /** 522 * Constants from UAX #39 for use in {@link uspoof_setRestrictionLevel}, and 523 * for returned identifier restriction levels in check results. 524 * 525 * @stable ICU 51 526 * 527 * @see uspoof_setRestrictionLevel 528 * @see uspoof_check 529 */ 530 typedef enum URestrictionLevel { 531 /** 532 * All characters in the string are in the identifier profile and all characters in the string are in the 533 * ASCII range. 534 * 535 * @stable ICU 51 536 */ 537 USPOOF_ASCII = 0x10000000, 538 /** 539 * The string classifies as ASCII-Only, or all characters in the string are in the identifier profile and 540 * the string is single-script, according to the definition in UTS 39 section 5.1. 541 * 542 * @stable ICU 53 543 */ 544 USPOOF_SINGLE_SCRIPT_RESTRICTIVE = 0x20000000, 545 /** 546 * The string classifies as Single Script, or all characters in the string are in the identifier profile and 547 * the string is covered by any of the following sets of scripts, according to the definition in UTS 39 548 * section 5.1: 549 * <ul> 550 * <li>Latin + Han + Bopomofo (or equivalently: Latn + Hanb)</li> 551 * <li>Latin + Han + Hiragana + Katakana (or equivalently: Latn + Jpan)</li> 552 * <li>Latin + Han + Hangul (or equivalently: Latn +Kore)</li> 553 * </ul> 554 * This is the default restriction in ICU. 555 * 556 * @stable ICU 51 557 */ 558 USPOOF_HIGHLY_RESTRICTIVE = 0x30000000, 559 /** 560 * The string classifies as Highly Restrictive, or all characters in the string are in the identifier profile 561 * and the string is covered by Latin and any one other Recommended or Aspirational script, except Cyrillic, 562 * Greek, and Cherokee. 563 * 564 * @stable ICU 51 565 */ 566 USPOOF_MODERATELY_RESTRICTIVE = 0x40000000, 567 /** 568 * All characters in the string are in the identifier profile. Allow arbitrary mixtures of scripts. 569 * 570 * @stable ICU 51 571 */ 572 USPOOF_MINIMALLY_RESTRICTIVE = 0x50000000, 573 /** 574 * Any valid identifiers, including characters outside of the Identifier Profile. 575 * 576 * @stable ICU 51 577 */ 578 USPOOF_UNRESTRICTIVE = 0x60000000, 579 /** 580 * Mask for selecting the Restriction Level bits from the return value of {@link uspoof_check}. 581 * 582 * @stable ICU 53 583 */ 584 USPOOF_RESTRICTION_LEVEL_MASK = 0x7F000000, 585 #ifndef U_HIDE_INTERNAL_API 586 /** 587 * An undefined restriction level. 588 * @internal 589 */ 590 USPOOF_UNDEFINED_RESTRICTIVE = -1 591 #endif /* U_HIDE_INTERNAL_API */ 592 } URestrictionLevel; 593 594 /** 595 * Create a Unicode Spoof Checker, configured to perform all 596 * checks except for USPOOF_LOCALE_LIMIT and USPOOF_CHAR_LIMIT. 597 * Note that additional checks may be added in the future, 598 * resulting in the changes to the default checking behavior. 599 * 600 * @param status The error code, set if this function encounters a problem. 601 * @return the newly created Spoof Checker 602 * @stable ICU 4.2 603 */ 604 U_CAPI USpoofChecker * U_EXPORT2 605 uspoof_open(UErrorCode *status); 606 607 608 /** 609 * Open a Spoof checker from its serialized form, stored in 32-bit-aligned memory. 610 * Inverse of uspoof_serialize(). 611 * The memory containing the serialized data must remain valid and unchanged 612 * as long as the spoof checker, or any cloned copies of the spoof checker, 613 * are in use. Ownership of the memory remains with the caller. 614 * The spoof checker (and any clones) must be closed prior to deleting the 615 * serialized data. 616 * 617 * @param data a pointer to 32-bit-aligned memory containing the serialized form of spoof data 618 * @param length the number of bytes available at data; 619 * can be more than necessary 620 * @param pActualLength receives the actual number of bytes at data taken up by the data; 621 * can be NULL 622 * @param pErrorCode ICU error code 623 * @return the spoof checker. 624 * 625 * @see uspoof_open 626 * @see uspoof_serialize 627 * @stable ICU 4.2 628 */ 629 U_CAPI USpoofChecker * U_EXPORT2 630 uspoof_openFromSerialized(const void *data, int32_t length, int32_t *pActualLength, 631 UErrorCode *pErrorCode); 632 633 /** 634 * Open a Spoof Checker from the source form of the spoof data. 635 * The input corresponds to the Unicode data file confusables.txt 636 * as described in Unicode UAX #39. The syntax of the source data 637 * is as described in UAX #39 for this file, and the content of 638 * this file is acceptable input. 639 * 640 * The character encoding of the (char *) input text is UTF-8. 641 * 642 * @param confusables a pointer to the confusable characters definitions, 643 * as found in file confusables.txt from unicode.org. 644 * @param confusablesLen The length of the confusables text, or -1 if the 645 * input string is zero terminated. 646 * @param confusablesWholeScript 647 * Deprecated in ICU 58. No longer used. 648 * @param confusablesWholeScriptLen 649 * Deprecated in ICU 58. No longer used. 650 * @param errType In the event of an error in the input, indicates 651 * which of the input files contains the error. 652 * The value is one of USPOOF_SINGLE_SCRIPT_CONFUSABLE or 653 * USPOOF_WHOLE_SCRIPT_CONFUSABLE, or 654 * zero if no errors are found. 655 * @param pe In the event of an error in the input, receives the position 656 * in the input text (line, offset) of the error. 657 * @param status an in/out ICU UErrorCode. Among the possible errors is 658 * U_PARSE_ERROR, which is used to report syntax errors 659 * in the input. 660 * @return A spoof checker that uses the rules from the input files. 661 * @stable ICU 4.2 662 */ 663 U_CAPI USpoofChecker * U_EXPORT2 664 uspoof_openFromSource(const char *confusables, int32_t confusablesLen, 665 const char *confusablesWholeScript, int32_t confusablesWholeScriptLen, 666 int32_t *errType, UParseError *pe, UErrorCode *status); 667 668 669 /** 670 * Close a Spoof Checker, freeing any memory that was being held by 671 * its implementation. 672 * @stable ICU 4.2 673 */ 674 U_CAPI void U_EXPORT2 675 uspoof_close(USpoofChecker *sc); 676 677 /** 678 * Clone a Spoof Checker. The clone will be set to perform the same checks 679 * as the original source. 680 * 681 * @param sc The source USpoofChecker 682 * @param status The error code, set if this function encounters a problem. 683 * @return 684 * @stable ICU 4.2 685 */ 686 U_CAPI USpoofChecker * U_EXPORT2 687 uspoof_clone(const USpoofChecker *sc, UErrorCode *status); 688 689 690 /** 691 * Specify the bitmask of checks that will be performed by {@link uspoof_check}. Calling this method 692 * overwrites any checks that may have already been enabled. By default, all checks are enabled. 693 * 694 * To enable specific checks and disable all others, 695 * OR together only the bit constants for the desired checks. 696 * For example, to fail strings containing characters outside of 697 * the set specified by {@link uspoof_setAllowedChars} and 698 * also strings that contain digits from mixed numbering systems: 699 * 700 * <pre> 701 * {@code 702 * uspoof_setChecks(USPOOF_CHAR_LIMIT | USPOOF_MIXED_NUMBERS); 703 * } 704 * </pre> 705 * 706 * To disable specific checks and enable all others, 707 * start with ALL_CHECKS and "AND away" the not-desired checks. 708 * For example, if you are not planning to use the {@link uspoof_areConfusable} functionality, 709 * it is good practice to disable the CONFUSABLE check: 710 * 711 * <pre> 712 * {@code 713 * uspoof_setChecks(USPOOF_ALL_CHECKS & ~USPOOF_CONFUSABLE); 714 * } 715 * </pre> 716 * 717 * Note that methods such as {@link uspoof_setAllowedChars}, {@link uspoof_setAllowedLocales}, and 718 * {@link uspoof_setRestrictionLevel} will enable certain checks when called. Those methods will OR the check they 719 * enable onto the existing bitmask specified by this method. For more details, see the documentation of those 720 * methods. 721 * 722 * @param sc The USpoofChecker 723 * @param checks The set of checks that this spoof checker will perform. 724 * The value is a bit set, obtained by OR-ing together 725 * values from enum USpoofChecks. 726 * @param status The error code, set if this function encounters a problem. 727 * @stable ICU 4.2 728 * 729 */ 730 U_CAPI void U_EXPORT2 731 uspoof_setChecks(USpoofChecker *sc, int32_t checks, UErrorCode *status); 732 733 /** 734 * Get the set of checks that this Spoof Checker has been configured to perform. 735 * 736 * @param sc The USpoofChecker 737 * @param status The error code, set if this function encounters a problem. 738 * @return The set of checks that this spoof checker will perform. 739 * The value is a bit set, obtained by OR-ing together 740 * values from enum USpoofChecks. 741 * @stable ICU 4.2 742 * 743 */ 744 U_CAPI int32_t U_EXPORT2 745 uspoof_getChecks(const USpoofChecker *sc, UErrorCode *status); 746 747 /** 748 * Set the loosest restriction level allowed for strings. The default if this is not called is 749 * {@link USPOOF_HIGHLY_RESTRICTIVE}. Calling this method enables the {@link USPOOF_RESTRICTION_LEVEL} and 750 * {@link USPOOF_MIXED_NUMBERS} checks, corresponding to Sections 5.1 and 5.2 of UTS 39. To customize which checks are 751 * to be performed by {@link uspoof_check}, see {@link uspoof_setChecks}. 752 * 753 * @param sc The USpoofChecker 754 * @param restrictionLevel The loosest restriction level allowed. 755 * @see URestrictionLevel 756 * @stable ICU 51 757 */ 758 U_CAPI void U_EXPORT2 759 uspoof_setRestrictionLevel(USpoofChecker *sc, URestrictionLevel restrictionLevel); 760 761 762 /** 763 * Get the Restriction Level that will be tested if the checks include {@link USPOOF_RESTRICTION_LEVEL}. 764 * 765 * @return The restriction level 766 * @see URestrictionLevel 767 * @stable ICU 51 768 */ 769 U_CAPI URestrictionLevel U_EXPORT2 770 uspoof_getRestrictionLevel(const USpoofChecker *sc); 771 772 /** 773 * Limit characters that are acceptable in identifiers being checked to those 774 * normally used with the languages associated with the specified locales. 775 * Any previously specified list of locales is replaced by the new settings. 776 * 777 * A set of languages is determined from the locale(s), and 778 * from those a set of acceptable Unicode scripts is determined. 779 * Characters from this set of scripts, along with characters from 780 * the "common" and "inherited" Unicode Script categories 781 * will be permitted. 782 * 783 * Supplying an empty string removes all restrictions; 784 * characters from any script will be allowed. 785 * 786 * The {@link USPOOF_CHAR_LIMIT} test is automatically enabled for this 787 * USpoofChecker when calling this function with a non-empty list 788 * of locales. 789 * 790 * The Unicode Set of characters that will be allowed is accessible 791 * via the uspoof_getAllowedChars() function. uspoof_setAllowedLocales() 792 * will <i>replace</i> any previously applied set of allowed characters. 793 * 794 * Adjustments, such as additions or deletions of certain classes of characters, 795 * can be made to the result of uspoof_setAllowedLocales() by 796 * fetching the resulting set with uspoof_getAllowedChars(), 797 * manipulating it with the Unicode Set API, then resetting the 798 * spoof detectors limits with uspoof_setAllowedChars(). 799 * 800 * @param sc The USpoofChecker 801 * @param localesList A list list of locales, from which the language 802 * and associated script are extracted. The locales 803 * are comma-separated if there is more than one. 804 * White space may not appear within an individual locale, 805 * but is ignored otherwise. 806 * The locales are syntactically like those from the 807 * HTTP Accept-Language header. 808 * If the localesList is empty, no restrictions will be placed on 809 * the allowed characters. 810 * 811 * @param status The error code, set if this function encounters a problem. 812 * @stable ICU 4.2 813 */ 814 U_CAPI void U_EXPORT2 815 uspoof_setAllowedLocales(USpoofChecker *sc, const char *localesList, UErrorCode *status); 816 817 /** 818 * Get a list of locales for the scripts that are acceptable in strings 819 * to be checked. If no limitations on scripts have been specified, 820 * an empty string will be returned. 821 * 822 * uspoof_setAllowedChars() will reset the list of allowed to be empty. 823 * 824 * The format of the returned list is the same as that supplied to 825 * uspoof_setAllowedLocales(), but returned list may not be identical 826 * to the originally specified string; the string may be reformatted, 827 * and information other than languages from 828 * the originally specified locales may be omitted. 829 * 830 * @param sc The USpoofChecker 831 * @param status The error code, set if this function encounters a problem. 832 * @return A string containing a list of locales corresponding 833 * to the acceptable scripts, formatted like an 834 * HTTP Accept Language value. 835 * 836 * @stable ICU 4.2 837 */ 838 U_CAPI const char * U_EXPORT2 839 uspoof_getAllowedLocales(USpoofChecker *sc, UErrorCode *status); 840 841 842 /** 843 * Limit the acceptable characters to those specified by a Unicode Set. 844 * Any previously specified character limit is 845 * is replaced by the new settings. This includes limits on 846 * characters that were set with the uspoof_setAllowedLocales() function. 847 * 848 * The USPOOF_CHAR_LIMIT test is automatically enabled for this 849 * USpoofChecker by this function. 850 * 851 * @param sc The USpoofChecker 852 * @param chars A Unicode Set containing the list of 853 * characters that are permitted. Ownership of the set 854 * remains with the caller. The incoming set is cloned by 855 * this function, so there are no restrictions on modifying 856 * or deleting the USet after calling this function. 857 * @param status The error code, set if this function encounters a problem. 858 * @stable ICU 4.2 859 */ 860 U_CAPI void U_EXPORT2 861 uspoof_setAllowedChars(USpoofChecker *sc, const USet *chars, UErrorCode *status); 862 863 864 /** 865 * Get a USet for the characters permitted in an identifier. 866 * This corresponds to the limits imposed by the Set Allowed Characters 867 * functions. Limitations imposed by other checks will not be 868 * reflected in the set returned by this function. 869 * 870 * The returned set will be frozen, meaning that it cannot be modified 871 * by the caller. 872 * 873 * Ownership of the returned set remains with the Spoof Detector. The 874 * returned set will become invalid if the spoof detector is closed, 875 * or if a new set of allowed characters is specified. 876 * 877 * 878 * @param sc The USpoofChecker 879 * @param status The error code, set if this function encounters a problem. 880 * @return A USet containing the characters that are permitted by 881 * the USPOOF_CHAR_LIMIT test. 882 * @stable ICU 4.2 883 */ 884 U_CAPI const USet * U_EXPORT2 885 uspoof_getAllowedChars(const USpoofChecker *sc, UErrorCode *status); 886 887 888 /** 889 * Check the specified string for possible security issues. 890 * The text to be checked will typically be an identifier of some sort. 891 * The set of checks to be performed is specified with uspoof_setChecks(). 892 * 893 * \note 894 * Consider using the newer API, {@link uspoof_check2}, instead. 895 * The newer API exposes additional information from the check procedure 896 * and is otherwise identical to this method. 897 * 898 * @param sc The USpoofChecker 899 * @param id The identifier to be checked for possible security issues, 900 * in UTF-16 format. 901 * @param length the length of the string to be checked, expressed in 902 * 16 bit UTF-16 code units, or -1 if the string is 903 * zero terminated. 904 * @param position Deprecated in ICU 51. Always returns zero. 905 * Originally, an out parameter for the index of the first 906 * string position that failed a check. 907 * This parameter may be NULL. 908 * @param status The error code, set if an error occurred while attempting to 909 * perform the check. 910 * Spoofing or security issues detected with the input string are 911 * not reported here, but through the function's return value. 912 * @return An integer value with bits set for any potential security 913 * or spoofing issues detected. The bits are defined by 914 * enum USpoofChecks. (returned_value & USPOOF_ALL_CHECKS) 915 * will be zero if the input string passes all of the 916 * enabled checks. 917 * @see uspoof_check2 918 * @stable ICU 4.2 919 */ 920 U_CAPI int32_t U_EXPORT2 921 uspoof_check(const USpoofChecker *sc, 922 const UChar *id, int32_t length, 923 int32_t *position, 924 UErrorCode *status); 925 926 927 /** 928 * Check the specified string for possible security issues. 929 * The text to be checked will typically be an identifier of some sort. 930 * The set of checks to be performed is specified with uspoof_setChecks(). 931 * 932 * \note 933 * Consider using the newer API, {@link uspoof_check2UTF8}, instead. 934 * The newer API exposes additional information from the check procedure 935 * and is otherwise identical to this method. 936 * 937 * @param sc The USpoofChecker 938 * @param id A identifier to be checked for possible security issues, in UTF8 format. 939 * @param length the length of the string to be checked, or -1 if the string is 940 * zero terminated. 941 * @param position Deprecated in ICU 51. Always returns zero. 942 * Originally, an out parameter for the index of the first 943 * string position that failed a check. 944 * This parameter may be NULL. 945 * @param status The error code, set if an error occurred while attempting to 946 * perform the check. 947 * Spoofing or security issues detected with the input string are 948 * not reported here, but through the function's return value. 949 * If the input contains invalid UTF-8 sequences, 950 * a status of U_INVALID_CHAR_FOUND will be returned. 951 * @return An integer value with bits set for any potential security 952 * or spoofing issues detected. The bits are defined by 953 * enum USpoofChecks. (returned_value & USPOOF_ALL_CHECKS) 954 * will be zero if the input string passes all of the 955 * enabled checks. 956 * @see uspoof_check2UTF8 957 * @stable ICU 4.2 958 */ 959 U_CAPI int32_t U_EXPORT2 960 uspoof_checkUTF8(const USpoofChecker *sc, 961 const char *id, int32_t length, 962 int32_t *position, 963 UErrorCode *status); 964 965 966 /** 967 * Check the specified string for possible security issues. 968 * The text to be checked will typically be an identifier of some sort. 969 * The set of checks to be performed is specified with uspoof_setChecks(). 970 * 971 * @param sc The USpoofChecker 972 * @param id The identifier to be checked for possible security issues, 973 * in UTF-16 format. 974 * @param length the length of the string to be checked, or -1 if the string is 975 * zero terminated. 976 * @param checkResult An instance of USpoofCheckResult to be filled with 977 * details about the identifier. Can be NULL. 978 * @param status The error code, set if an error occurred while attempting to 979 * perform the check. 980 * Spoofing or security issues detected with the input string are 981 * not reported here, but through the function's return value. 982 * @return An integer value with bits set for any potential security 983 * or spoofing issues detected. The bits are defined by 984 * enum USpoofChecks. (returned_value & USPOOF_ALL_CHECKS) 985 * will be zero if the input string passes all of the 986 * enabled checks. Any information in this bitmask will be 987 * consistent with the information saved in the optional 988 * checkResult parameter. 989 * @see uspoof_openCheckResult 990 * @see uspoof_check2UTF8 991 * @see uspoof_check2UnicodeString 992 * @stable ICU 58 993 */ 994 U_CAPI int32_t U_EXPORT2 995 uspoof_check2(const USpoofChecker *sc, 996 const UChar* id, int32_t length, 997 USpoofCheckResult* checkResult, 998 UErrorCode *status); 999 1000 /** 1001 * Check the specified string for possible security issues. 1002 * The text to be checked will typically be an identifier of some sort. 1003 * The set of checks to be performed is specified with uspoof_setChecks(). 1004 * 1005 * This version of {@link uspoof_check} accepts a USpoofCheckResult, which 1006 * returns additional information about the identifier. For more 1007 * information, see {@link uspoof_openCheckResult}. 1008 * 1009 * @param sc The USpoofChecker 1010 * @param id A identifier to be checked for possible security issues, in UTF8 format. 1011 * @param length the length of the string to be checked, or -1 if the string is 1012 * zero terminated. 1013 * @param checkResult An instance of USpoofCheckResult to be filled with 1014 * details about the identifier. Can be NULL. 1015 * @param status The error code, set if an error occurred while attempting to 1016 * perform the check. 1017 * Spoofing or security issues detected with the input string are 1018 * not reported here, but through the function's return value. 1019 * @return An integer value with bits set for any potential security 1020 * or spoofing issues detected. The bits are defined by 1021 * enum USpoofChecks. (returned_value & USPOOF_ALL_CHECKS) 1022 * will be zero if the input string passes all of the 1023 * enabled checks. Any information in this bitmask will be 1024 * consistent with the information saved in the optional 1025 * checkResult parameter. 1026 * @see uspoof_openCheckResult 1027 * @see uspoof_check2 1028 * @see uspoof_check2UnicodeString 1029 * @stable ICU 58 1030 */ 1031 U_CAPI int32_t U_EXPORT2 1032 uspoof_check2UTF8(const USpoofChecker *sc, 1033 const char *id, int32_t length, 1034 USpoofCheckResult* checkResult, 1035 UErrorCode *status); 1036 1037 /** 1038 * Create a USpoofCheckResult, used by the {@link uspoof_check2} class of functions to return 1039 * information about the identifier. Information includes: 1040 * <ul> 1041 * <li>A bitmask of the checks that failed</li> 1042 * <li>The identifier's restriction level (UTS 39 section 5.2)</li> 1043 * <li>The set of numerics in the string (UTS 39 section 5.3)</li> 1044 * </ul> 1045 * The data held in a USpoofCheckResult is cleared whenever it is passed into a new call 1046 * of {@link uspoof_check2}. 1047 * 1048 * @param status The error code, set if this function encounters a problem. 1049 * @return the newly created USpoofCheckResult 1050 * @see uspoof_check2 1051 * @see uspoof_check2UTF8 1052 * @see uspoof_check2UnicodeString 1053 * @stable ICU 58 1054 */ 1055 U_CAPI USpoofCheckResult* U_EXPORT2 1056 uspoof_openCheckResult(UErrorCode *status); 1057 1058 /** 1059 * Close a USpoofCheckResult, freeing any memory that was being held by 1060 * its implementation. 1061 * 1062 * @param checkResult The instance of USpoofCheckResult to close 1063 * @stable ICU 58 1064 */ 1065 U_CAPI void U_EXPORT2 1066 uspoof_closeCheckResult(USpoofCheckResult *checkResult); 1067 1068 /** 1069 * Indicates which of the spoof check(s) have failed. The value is a bitwise OR of the constants for the tests 1070 * in question: USPOOF_RESTRICTION_LEVEL, USPOOF_CHAR_LIMIT, and so on. 1071 * 1072 * @param checkResult The instance of USpoofCheckResult created by {@link uspoof_openCheckResult} 1073 * @param status The error code, set if an error occurred. 1074 * @return An integer value with bits set for any potential security 1075 * or spoofing issues detected. The bits are defined by 1076 * enum USpoofChecks. (returned_value & USPOOF_ALL_CHECKS) 1077 * will be zero if the input string passes all of the 1078 * enabled checks. 1079 * @see uspoof_setChecks 1080 * @stable ICU 58 1081 */ 1082 U_CAPI int32_t U_EXPORT2 1083 uspoof_getCheckResultChecks(const USpoofCheckResult *checkResult, UErrorCode *status); 1084 1085 /** 1086 * Gets the restriction level that the text meets, if the USPOOF_RESTRICTION_LEVEL check 1087 * was enabled; otherwise, undefined. 1088 * 1089 * @param checkResult The instance of USpoofCheckResult created by {@link uspoof_openCheckResult} 1090 * @param status The error code, set if an error occurred. 1091 * @return The restriction level contained in the USpoofCheckResult 1092 * @see uspoof_setRestrictionLevel 1093 * @stable ICU 58 1094 */ 1095 U_CAPI URestrictionLevel U_EXPORT2 1096 uspoof_getCheckResultRestrictionLevel(const USpoofCheckResult *checkResult, UErrorCode *status); 1097 1098 /** 1099 * Gets the set of numerics found in the string, if the USPOOF_MIXED_NUMBERS check was enabled; 1100 * otherwise, undefined. The set will contain the zero digit from each decimal number system found 1101 * in the input string. Ownership of the returned USet remains with the USpoofCheckResult. 1102 * The USet will be free'd when {@link uspoof_closeCheckResult} is called. 1103 * 1104 * @param checkResult The instance of USpoofCheckResult created by {@link uspoof_openCheckResult} 1105 * @return The set of numerics contained in the USpoofCheckResult 1106 * @param status The error code, set if an error occurred. 1107 * @stable ICU 58 1108 */ 1109 U_CAPI const USet* U_EXPORT2 1110 uspoof_getCheckResultNumerics(const USpoofCheckResult *checkResult, UErrorCode *status); 1111 1112 1113 /** 1114 * Check the whether two specified strings are visually confusable. 1115 * 1116 * If the strings are confusable, the return value will be nonzero, as long as 1117 * {@link USPOOF_CONFUSABLE} was enabled in uspoof_setChecks(). 1118 * 1119 * The bits in the return value correspond to flags for each of the classes of 1120 * confusables applicable to the two input strings. According to UTS 39 1121 * section 4, the possible flags are: 1122 * 1123 * <ul> 1124 * <li>{@link USPOOF_SINGLE_SCRIPT_CONFUSABLE}</li> 1125 * <li>{@link USPOOF_MIXED_SCRIPT_CONFUSABLE}</li> 1126 * <li>{@link USPOOF_WHOLE_SCRIPT_CONFUSABLE}</li> 1127 * </ul> 1128 * 1129 * If one or more of the above flags were not listed in uspoof_setChecks(), this 1130 * function will never report that class of confusable. The check 1131 * {@link USPOOF_CONFUSABLE} enables all three flags. 1132 * 1133 * 1134 * @param sc The USpoofChecker 1135 * @param id1 The first of the two identifiers to be compared for 1136 * confusability. The strings are in UTF-16 format. 1137 * @param length1 the length of the first identifer, expressed in 1138 * 16 bit UTF-16 code units, or -1 if the string is 1139 * nul terminated. 1140 * @param id2 The second of the two identifiers to be compared for 1141 * confusability. The identifiers are in UTF-16 format. 1142 * @param length2 The length of the second identifiers, expressed in 1143 * 16 bit UTF-16 code units, or -1 if the string is 1144 * nul terminated. 1145 * @param status The error code, set if an error occurred while attempting to 1146 * perform the check. 1147 * Confusability of the identifiers is not reported here, 1148 * but through this function's return value. 1149 * @return An integer value with bit(s) set corresponding to 1150 * the type of confusability found, as defined by 1151 * enum USpoofChecks. Zero is returned if the identifiers 1152 * are not confusable. 1153 * 1154 * @stable ICU 4.2 1155 */ 1156 U_CAPI int32_t U_EXPORT2 1157 uspoof_areConfusable(const USpoofChecker *sc, 1158 const UChar *id1, int32_t length1, 1159 const UChar *id2, int32_t length2, 1160 UErrorCode *status); 1161 1162 1163 1164 /** 1165 * A version of {@link uspoof_areConfusable} accepting strings in UTF-8 format. 1166 * 1167 * @param sc The USpoofChecker 1168 * @param id1 The first of the two identifiers to be compared for 1169 * confusability. The strings are in UTF-8 format. 1170 * @param length1 the length of the first identifiers, in bytes, or -1 1171 * if the string is nul terminated. 1172 * @param id2 The second of the two identifiers to be compared for 1173 * confusability. The strings are in UTF-8 format. 1174 * @param length2 The length of the second string in bytes, or -1 1175 * if the string is nul terminated. 1176 * @param status The error code, set if an error occurred while attempting to 1177 * perform the check. 1178 * Confusability of the strings is not reported here, 1179 * but through this function's return value. 1180 * @return An integer value with bit(s) set corresponding to 1181 * the type of confusability found, as defined by 1182 * enum USpoofChecks. Zero is returned if the strings 1183 * are not confusable. 1184 * 1185 * @stable ICU 4.2 1186 * 1187 * @see uspoof_areConfusable 1188 */ 1189 U_CAPI int32_t U_EXPORT2 1190 uspoof_areConfusableUTF8(const USpoofChecker *sc, 1191 const char *id1, int32_t length1, 1192 const char *id2, int32_t length2, 1193 UErrorCode *status); 1194 1195 1196 1197 1198 /** 1199 * Get the "skeleton" for an identifier. 1200 * Skeletons are a transformation of the input identifier; 1201 * Two identifiers are confusable if their skeletons are identical. 1202 * See Unicode UAX #39 for additional information. 1203 * 1204 * Using skeletons directly makes it possible to quickly check 1205 * whether an identifier is confusable with any of some large 1206 * set of existing identifiers, by creating an efficiently 1207 * searchable collection of the skeletons. 1208 * 1209 * @param sc The USpoofChecker 1210 * @param type Deprecated in ICU 58. You may pass any number. 1211 * Originally, controlled which of the Unicode confusable data 1212 * tables to use. 1213 * @param id The input identifier whose skeleton will be computed. 1214 * @param length The length of the input identifier, expressed in 16 bit 1215 * UTF-16 code units, or -1 if the string is zero terminated. 1216 * @param dest The output buffer, to receive the skeleton string. 1217 * @param destCapacity The length of the output buffer, in 16 bit units. 1218 * The destCapacity may be zero, in which case the function will 1219 * return the actual length of the skeleton. 1220 * @param status The error code, set if an error occurred while attempting to 1221 * perform the check. 1222 * @return The length of the skeleton string. The returned length 1223 * is always that of the complete skeleton, even when the 1224 * supplied buffer is too small (or of zero length) 1225 * 1226 * @stable ICU 4.2 1227 * @see uspoof_areConfusable 1228 */ 1229 U_CAPI int32_t U_EXPORT2 1230 uspoof_getSkeleton(const USpoofChecker *sc, 1231 uint32_t type, 1232 const UChar *id, int32_t length, 1233 UChar *dest, int32_t destCapacity, 1234 UErrorCode *status); 1235 1236 /** 1237 * Get the "skeleton" for an identifier. 1238 * Skeletons are a transformation of the input identifier; 1239 * Two identifiers are confusable if their skeletons are identical. 1240 * See Unicode UAX #39 for additional information. 1241 * 1242 * Using skeletons directly makes it possible to quickly check 1243 * whether an identifier is confusable with any of some large 1244 * set of existing identifiers, by creating an efficiently 1245 * searchable collection of the skeletons. 1246 * 1247 * @param sc The USpoofChecker 1248 * @param type Deprecated in ICU 58. You may pass any number. 1249 * Originally, controlled which of the Unicode confusable data 1250 * tables to use. 1251 * @param id The UTF-8 format identifier whose skeleton will be computed. 1252 * @param length The length of the input string, in bytes, 1253 * or -1 if the string is zero terminated. 1254 * @param dest The output buffer, to receive the skeleton string. 1255 * @param destCapacity The length of the output buffer, in bytes. 1256 * The destCapacity may be zero, in which case the function will 1257 * return the actual length of the skeleton. 1258 * @param status The error code, set if an error occurred while attempting to 1259 * perform the check. Possible Errors include U_INVALID_CHAR_FOUND 1260 * for invalid UTF-8 sequences, and 1261 * U_BUFFER_OVERFLOW_ERROR if the destination buffer is too small 1262 * to hold the complete skeleton. 1263 * @return The length of the skeleton string, in bytes. The returned length 1264 * is always that of the complete skeleton, even when the 1265 * supplied buffer is too small (or of zero length) 1266 * 1267 * @stable ICU 4.2 1268 */ 1269 U_CAPI int32_t U_EXPORT2 1270 uspoof_getSkeletonUTF8(const USpoofChecker *sc, 1271 uint32_t type, 1272 const char *id, int32_t length, 1273 char *dest, int32_t destCapacity, 1274 UErrorCode *status); 1275 1276 /** 1277 * Get the set of Candidate Characters for Inclusion in Identifiers, as defined 1278 * in http://unicode.org/Public/security/latest/xidmodifications.txt 1279 * and documented in http://www.unicode.org/reports/tr39/, Unicode Security Mechanisms. 1280 * 1281 * The returned set is frozen. Ownership of the set remains with the ICU library; it must not 1282 * be deleted by the caller. 1283 * 1284 * @param status The error code, set if a problem occurs while creating the set. 1285 * 1286 * @stable ICU 51 1287 */ 1288 U_CAPI const USet * U_EXPORT2 1289 uspoof_getInclusionSet(UErrorCode *status); 1290 1291 /** 1292 * Get the set of characters from Recommended Scripts for Inclusion in Identifiers, as defined 1293 * in http://unicode.org/Public/security/latest/xidmodifications.txt 1294 * and documented in http://www.unicode.org/reports/tr39/, Unicode Security Mechanisms. 1295 * 1296 * The returned set is frozen. Ownership of the set remains with the ICU library; it must not 1297 * be deleted by the caller. 1298 * 1299 * @param status The error code, set if a problem occurs while creating the set. 1300 * 1301 * @stable ICU 51 1302 */ 1303 U_CAPI const USet * U_EXPORT2 1304 uspoof_getRecommendedSet(UErrorCode *status); 1305 1306 /** 1307 * Serialize the data for a spoof detector into a chunk of memory. 1308 * The flattened spoof detection tables can later be used to efficiently 1309 * instantiate a new Spoof Detector. 1310 * 1311 * The serialized spoof checker includes only the data compiled from the 1312 * Unicode data tables by uspoof_openFromSource(); it does not include 1313 * include any other state or configuration that may have been set. 1314 * 1315 * @param sc the Spoof Detector whose data is to be serialized. 1316 * @param data a pointer to 32-bit-aligned memory to be filled with the data, 1317 * can be NULL if capacity==0 1318 * @param capacity the number of bytes available at data, 1319 * or 0 for preflighting 1320 * @param status an in/out ICU UErrorCode; possible errors include: 1321 * - U_BUFFER_OVERFLOW_ERROR if the data storage block is too small for serialization 1322 * - U_ILLEGAL_ARGUMENT_ERROR the data or capacity parameters are bad 1323 * @return the number of bytes written or needed for the spoof data 1324 * 1325 * @see utrie2_openFromSerialized() 1326 * @stable ICU 4.2 1327 */ 1328 U_CAPI int32_t U_EXPORT2 1329 uspoof_serialize(USpoofChecker *sc, 1330 void *data, int32_t capacity, 1331 UErrorCode *status); 1332 1333 U_CDECL_END 1334 1335 #if U_SHOW_CPLUSPLUS_API 1336 1337 U_NAMESPACE_BEGIN 1338 1339 /** 1340 * \class LocalUSpoofCheckerPointer 1341 * "Smart pointer" class, closes a USpoofChecker via uspoof_close(). 1342 * For most methods see the LocalPointerBase base class. 1343 * 1344 * @see LocalPointerBase 1345 * @see LocalPointer 1346 * @stable ICU 4.4 1347 */ 1348 /** 1349 * \cond 1350 * Note: Doxygen is giving a bogus warning on this U_DEFINE_LOCAL_OPEN_POINTER. 1351 * For now, suppress with a Doxygen cond 1352 */ 1353 U_DEFINE_LOCAL_OPEN_POINTER(LocalUSpoofCheckerPointer, USpoofChecker, uspoof_close); 1354 /** \endcond */ 1355 1356 /** 1357 * \class LocalUSpoofCheckResultPointer 1358 * "Smart pointer" class, closes a USpoofCheckResult via `uspoof_closeCheckResult()`. 1359 * For most methods see the LocalPointerBase base class. 1360 * 1361 * @see LocalPointerBase 1362 * @see LocalPointer 1363 * @stable ICU 58 1364 */ 1365 1366 /** 1367 * \cond 1368 * Note: Doxygen is giving a bogus warning on this U_DEFINE_LOCAL_OPEN_POINTER. 1369 * For now, suppress with a Doxygen cond 1370 */ 1371 U_DEFINE_LOCAL_OPEN_POINTER(LocalUSpoofCheckResultPointer, USpoofCheckResult, uspoof_closeCheckResult); 1372 /** \endcond */ 1373 1374 U_NAMESPACE_END 1375 1376 /** 1377 * Limit the acceptable characters to those specified by a Unicode Set. 1378 * Any previously specified character limit is 1379 * is replaced by the new settings. This includes limits on 1380 * characters that were set with the uspoof_setAllowedLocales() function. 1381 * 1382 * The USPOOF_CHAR_LIMIT test is automatically enabled for this 1383 * USoofChecker by this function. 1384 * 1385 * @param sc The USpoofChecker 1386 * @param chars A Unicode Set containing the list of 1387 * characters that are permitted. Ownership of the set 1388 * remains with the caller. The incoming set is cloned by 1389 * this function, so there are no restrictions on modifying 1390 * or deleting the UnicodeSet after calling this function. 1391 * @param status The error code, set if this function encounters a problem. 1392 * @stable ICU 4.2 1393 */ 1394 U_CAPI void U_EXPORT2 1395 uspoof_setAllowedUnicodeSet(USpoofChecker *sc, const icu::UnicodeSet *chars, UErrorCode *status); 1396 1397 1398 /** 1399 * Get a UnicodeSet for the characters permitted in an identifier. 1400 * This corresponds to the limits imposed by the Set Allowed Characters / 1401 * UnicodeSet functions. Limitations imposed by other checks will not be 1402 * reflected in the set returned by this function. 1403 * 1404 * The returned set will be frozen, meaning that it cannot be modified 1405 * by the caller. 1406 * 1407 * Ownership of the returned set remains with the Spoof Detector. The 1408 * returned set will become invalid if the spoof detector is closed, 1409 * or if a new set of allowed characters is specified. 1410 * 1411 * 1412 * @param sc The USpoofChecker 1413 * @param status The error code, set if this function encounters a problem. 1414 * @return A UnicodeSet containing the characters that are permitted by 1415 * the USPOOF_CHAR_LIMIT test. 1416 * @stable ICU 4.2 1417 */ 1418 U_CAPI const icu::UnicodeSet * U_EXPORT2 1419 uspoof_getAllowedUnicodeSet(const USpoofChecker *sc, UErrorCode *status); 1420 1421 /** 1422 * Check the specified string for possible security issues. 1423 * The text to be checked will typically be an identifier of some sort. 1424 * The set of checks to be performed is specified with uspoof_setChecks(). 1425 * 1426 * \note 1427 * Consider using the newer API, {@link uspoof_check2UnicodeString}, instead. 1428 * The newer API exposes additional information from the check procedure 1429 * and is otherwise identical to this method. 1430 * 1431 * @param sc The USpoofChecker 1432 * @param id A identifier to be checked for possible security issues. 1433 * @param position Deprecated in ICU 51. Always returns zero. 1434 * Originally, an out parameter for the index of the first 1435 * string position that failed a check. 1436 * This parameter may be NULL. 1437 * @param status The error code, set if an error occurred while attempting to 1438 * perform the check. 1439 * Spoofing or security issues detected with the input string are 1440 * not reported here, but through the function's return value. 1441 * @return An integer value with bits set for any potential security 1442 * or spoofing issues detected. The bits are defined by 1443 * enum USpoofChecks. (returned_value & USPOOF_ALL_CHECKS) 1444 * will be zero if the input string passes all of the 1445 * enabled checks. 1446 * @see uspoof_check2UnicodeString 1447 * @stable ICU 4.2 1448 */ 1449 U_CAPI int32_t U_EXPORT2 1450 uspoof_checkUnicodeString(const USpoofChecker *sc, 1451 const icu::UnicodeString &id, 1452 int32_t *position, 1453 UErrorCode *status); 1454 1455 /** 1456 * Check the specified string for possible security issues. 1457 * The text to be checked will typically be an identifier of some sort. 1458 * The set of checks to be performed is specified with uspoof_setChecks(). 1459 * 1460 * @param sc The USpoofChecker 1461 * @param id A identifier to be checked for possible security issues. 1462 * @param checkResult An instance of USpoofCheckResult to be filled with 1463 * details about the identifier. Can be NULL. 1464 * @param status The error code, set if an error occurred while attempting to 1465 * perform the check. 1466 * Spoofing or security issues detected with the input string are 1467 * not reported here, but through the function's return value. 1468 * @return An integer value with bits set for any potential security 1469 * or spoofing issues detected. The bits are defined by 1470 * enum USpoofChecks. (returned_value & USPOOF_ALL_CHECKS) 1471 * will be zero if the input string passes all of the 1472 * enabled checks. Any information in this bitmask will be 1473 * consistent with the information saved in the optional 1474 * checkResult parameter. 1475 * @see uspoof_openCheckResult 1476 * @see uspoof_check2 1477 * @see uspoof_check2UTF8 1478 * @stable ICU 58 1479 */ 1480 U_CAPI int32_t U_EXPORT2 1481 uspoof_check2UnicodeString(const USpoofChecker *sc, 1482 const icu::UnicodeString &id, 1483 USpoofCheckResult* checkResult, 1484 UErrorCode *status); 1485 1486 /** 1487 * A version of {@link uspoof_areConfusable} accepting UnicodeStrings. 1488 * 1489 * @param sc The USpoofChecker 1490 * @param s1 The first of the two identifiers to be compared for 1491 * confusability. The strings are in UTF-8 format. 1492 * @param s2 The second of the two identifiers to be compared for 1493 * confusability. The strings are in UTF-8 format. 1494 * @param status The error code, set if an error occurred while attempting to 1495 * perform the check. 1496 * Confusability of the identifiers is not reported here, 1497 * but through this function's return value. 1498 * @return An integer value with bit(s) set corresponding to 1499 * the type of confusability found, as defined by 1500 * enum USpoofChecks. Zero is returned if the identifiers 1501 * are not confusable. 1502 * 1503 * @stable ICU 4.2 1504 * 1505 * @see uspoof_areConfusable 1506 */ 1507 U_CAPI int32_t U_EXPORT2 1508 uspoof_areConfusableUnicodeString(const USpoofChecker *sc, 1509 const icu::UnicodeString &s1, 1510 const icu::UnicodeString &s2, 1511 UErrorCode *status); 1512 1513 /** 1514 * Get the "skeleton" for an identifier. 1515 * Skeletons are a transformation of the input identifier; 1516 * Two identifiers are confusable if their skeletons are identical. 1517 * See Unicode UAX #39 for additional information. 1518 * 1519 * Using skeletons directly makes it possible to quickly check 1520 * whether an identifier is confusable with any of some large 1521 * set of existing identifiers, by creating an efficiently 1522 * searchable collection of the skeletons. 1523 * 1524 * @param sc The USpoofChecker. 1525 * @param type Deprecated in ICU 58. You may pass any number. 1526 * Originally, controlled which of the Unicode confusable data 1527 * tables to use. 1528 * @param id The input identifier whose skeleton will be computed. 1529 * @param dest The output identifier, to receive the skeleton string. 1530 * @param status The error code, set if an error occurred while attempting to 1531 * perform the check. 1532 * @return A reference to the destination (skeleton) string. 1533 * 1534 * @stable ICU 4.2 1535 */ 1536 U_I18N_API icu::UnicodeString & U_EXPORT2 1537 uspoof_getSkeletonUnicodeString(const USpoofChecker *sc, 1538 uint32_t type, 1539 const icu::UnicodeString &id, 1540 icu::UnicodeString &dest, 1541 UErrorCode *status); 1542 1543 /** 1544 * Get the set of Candidate Characters for Inclusion in Identifiers, as defined 1545 * in http://unicode.org/Public/security/latest/xidmodifications.txt 1546 * and documented in http://www.unicode.org/reports/tr39/, Unicode Security Mechanisms. 1547 * 1548 * The returned set is frozen. Ownership of the set remains with the ICU library; it must not 1549 * be deleted by the caller. 1550 * 1551 * @param status The error code, set if a problem occurs while creating the set. 1552 * 1553 * @stable ICU 51 1554 */ 1555 U_CAPI const icu::UnicodeSet * U_EXPORT2 1556 uspoof_getInclusionUnicodeSet(UErrorCode *status); 1557 1558 /** 1559 * Get the set of characters from Recommended Scripts for Inclusion in Identifiers, as defined 1560 * in http://unicode.org/Public/security/latest/xidmodifications.txt 1561 * and documented in http://www.unicode.org/reports/tr39/, Unicode Security Mechanisms. 1562 * 1563 * The returned set is frozen. Ownership of the set remains with the ICU library; it must not 1564 * be deleted by the caller. 1565 * 1566 * @param status The error code, set if a problem occurs while creating the set. 1567 * 1568 * @stable ICU 51 1569 */ 1570 U_CAPI const icu::UnicodeSet * U_EXPORT2 1571 uspoof_getRecommendedUnicodeSet(UErrorCode *status); 1572 1573 #endif /* U_SHOW_CPLUSPLUS_API */ 1574 1575 #endif /* UCONFIG_NO_NORMALIZATION */ 1576 1577 #endif /* USPOOF_H */ 1578