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 #include "unicode/localpointer.h" 26 27 #if !UCONFIG_NO_NORMALIZATION 28 29 30 #if U_SHOW_CPLUSPLUS_API 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_STABLE 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_STABLE 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_STABLE 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_STABLE 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_STABLE 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, the "whitelisted" checks should be ORed together. For 695 * example, to fail strings containing characters outside of the set specified by {@link uspoof_setAllowedChars} and 696 * also strings that contain digits from mixed numbering systems: 697 * 698 * <pre> 699 * {@code 700 * uspoof_setChecks(USPOOF_CHAR_LIMIT | USPOOF_MIXED_NUMBERS); 701 * } 702 * </pre> 703 * 704 * To disable specific checks and enable all others, the "blacklisted" checks should be ANDed away from 705 * ALL_CHECKS. For example, if you are not planning to use the {@link uspoof_areConfusable} functionality, 706 * it is good practice to disable the CONFUSABLE check: 707 * 708 * <pre> 709 * {@code 710 * uspoof_setChecks(USPOOF_ALL_CHECKS & ~USPOOF_CONFUSABLE); 711 * } 712 * </pre> 713 * 714 * Note that methods such as {@link uspoof_setAllowedChars}, {@link uspoof_setAllowedLocales}, and 715 * {@link uspoof_setRestrictionLevel} will enable certain checks when called. Those methods will OR the check they 716 * enable onto the existing bitmask specified by this method. For more details, see the documentation of those 717 * methods. 718 * 719 * @param sc The USpoofChecker 720 * @param checks The set of checks that this spoof checker will perform. 721 * The value is a bit set, obtained by OR-ing together 722 * values from enum USpoofChecks. 723 * @param status The error code, set if this function encounters a problem. 724 * @stable ICU 4.2 725 * 726 */ 727 U_STABLE void U_EXPORT2 728 uspoof_setChecks(USpoofChecker *sc, int32_t checks, UErrorCode *status); 729 730 /** 731 * Get the set of checks that this Spoof Checker has been configured to perform. 732 * 733 * @param sc The USpoofChecker 734 * @param status The error code, set if this function encounters a problem. 735 * @return The set of checks that this spoof checker will perform. 736 * The value is a bit set, obtained by OR-ing together 737 * values from enum USpoofChecks. 738 * @stable ICU 4.2 739 * 740 */ 741 U_STABLE int32_t U_EXPORT2 742 uspoof_getChecks(const USpoofChecker *sc, UErrorCode *status); 743 744 /** 745 * Set the loosest restriction level allowed for strings. The default if this is not called is 746 * {@link USPOOF_HIGHLY_RESTRICTIVE}. Calling this method enables the {@link USPOOF_RESTRICTION_LEVEL} and 747 * {@link USPOOF_MIXED_NUMBERS} checks, corresponding to Sections 5.1 and 5.2 of UTS 39. To customize which checks are 748 * to be performed by {@link uspoof_check}, see {@link uspoof_setChecks}. 749 * 750 * @param sc The USpoofChecker 751 * @param restrictionLevel The loosest restriction level allowed. 752 * @see URestrictionLevel 753 * @stable ICU 51 754 */ 755 U_STABLE void U_EXPORT2 756 uspoof_setRestrictionLevel(USpoofChecker *sc, URestrictionLevel restrictionLevel); 757 758 759 /** 760 * Get the Restriction Level that will be tested if the checks include {@link USPOOF_RESTRICTION_LEVEL}. 761 * 762 * @return The restriction level 763 * @see URestrictionLevel 764 * @stable ICU 51 765 */ 766 U_STABLE URestrictionLevel U_EXPORT2 767 uspoof_getRestrictionLevel(const USpoofChecker *sc); 768 769 /** 770 * Limit characters that are acceptable in identifiers being checked to those 771 * normally used with the languages associated with the specified locales. 772 * Any previously specified list of locales is replaced by the new settings. 773 * 774 * A set of languages is determined from the locale(s), and 775 * from those a set of acceptable Unicode scripts is determined. 776 * Characters from this set of scripts, along with characters from 777 * the "common" and "inherited" Unicode Script categories 778 * will be permitted. 779 * 780 * Supplying an empty string removes all restrictions; 781 * characters from any script will be allowed. 782 * 783 * The {@link USPOOF_CHAR_LIMIT} test is automatically enabled for this 784 * USpoofChecker when calling this function with a non-empty list 785 * of locales. 786 * 787 * The Unicode Set of characters that will be allowed is accessible 788 * via the uspoof_getAllowedChars() function. uspoof_setAllowedLocales() 789 * will <i>replace</i> any previously applied set of allowed characters. 790 * 791 * Adjustments, such as additions or deletions of certain classes of characters, 792 * can be made to the result of uspoof_setAllowedLocales() by 793 * fetching the resulting set with uspoof_getAllowedChars(), 794 * manipulating it with the Unicode Set API, then resetting the 795 * spoof detectors limits with uspoof_setAllowedChars(). 796 * 797 * @param sc The USpoofChecker 798 * @param localesList A list list of locales, from which the language 799 * and associated script are extracted. The locales 800 * are comma-separated if there is more than one. 801 * White space may not appear within an individual locale, 802 * but is ignored otherwise. 803 * The locales are syntactically like those from the 804 * HTTP Accept-Language header. 805 * If the localesList is empty, no restrictions will be placed on 806 * the allowed characters. 807 * 808 * @param status The error code, set if this function encounters a problem. 809 * @stable ICU 4.2 810 */ 811 U_STABLE void U_EXPORT2 812 uspoof_setAllowedLocales(USpoofChecker *sc, const char *localesList, UErrorCode *status); 813 814 /** 815 * Get a list of locales for the scripts that are acceptable in strings 816 * to be checked. If no limitations on scripts have been specified, 817 * an empty string will be returned. 818 * 819 * uspoof_setAllowedChars() will reset the list of allowed to be empty. 820 * 821 * The format of the returned list is the same as that supplied to 822 * uspoof_setAllowedLocales(), but returned list may not be identical 823 * to the originally specified string; the string may be reformatted, 824 * and information other than languages from 825 * the originally specified locales may be omitted. 826 * 827 * @param sc The USpoofChecker 828 * @param status The error code, set if this function encounters a problem. 829 * @return A string containing a list of locales corresponding 830 * to the acceptable scripts, formatted like an 831 * HTTP Accept Language value. 832 * 833 * @stable ICU 4.2 834 */ 835 U_STABLE const char * U_EXPORT2 836 uspoof_getAllowedLocales(USpoofChecker *sc, UErrorCode *status); 837 838 839 /** 840 * Limit the acceptable characters to those specified by a Unicode Set. 841 * Any previously specified character limit is 842 * is replaced by the new settings. This includes limits on 843 * characters that were set with the uspoof_setAllowedLocales() function. 844 * 845 * The USPOOF_CHAR_LIMIT test is automatically enabled for this 846 * USpoofChecker by this function. 847 * 848 * @param sc The USpoofChecker 849 * @param chars A Unicode Set containing the list of 850 * characters that are permitted. Ownership of the set 851 * remains with the caller. The incoming set is cloned by 852 * this function, so there are no restrictions on modifying 853 * or deleting the USet after calling this function. 854 * @param status The error code, set if this function encounters a problem. 855 * @stable ICU 4.2 856 */ 857 U_STABLE void U_EXPORT2 858 uspoof_setAllowedChars(USpoofChecker *sc, const USet *chars, UErrorCode *status); 859 860 861 /** 862 * Get a USet for the characters permitted in an identifier. 863 * This corresponds to the limits imposed by the Set Allowed Characters 864 * functions. Limitations imposed by other checks will not be 865 * reflected in the set returned by this function. 866 * 867 * The returned set will be frozen, meaning that it cannot be modified 868 * by the caller. 869 * 870 * Ownership of the returned set remains with the Spoof Detector. The 871 * returned set will become invalid if the spoof detector is closed, 872 * or if a new set of allowed characters is specified. 873 * 874 * 875 * @param sc The USpoofChecker 876 * @param status The error code, set if this function encounters a problem. 877 * @return A USet containing the characters that are permitted by 878 * the USPOOF_CHAR_LIMIT test. 879 * @stable ICU 4.2 880 */ 881 U_STABLE const USet * U_EXPORT2 882 uspoof_getAllowedChars(const USpoofChecker *sc, UErrorCode *status); 883 884 885 /** 886 * Check the specified string for possible security issues. 887 * The text to be checked will typically be an identifier of some sort. 888 * The set of checks to be performed is specified with uspoof_setChecks(). 889 * 890 * \note 891 * Consider using the newer API, {@link uspoof_check2}, instead. 892 * The newer API exposes additional information from the check procedure 893 * and is otherwise identical to this method. 894 * 895 * @param sc The USpoofChecker 896 * @param id The identifier to be checked for possible security issues, 897 * in UTF-16 format. 898 * @param length the length of the string to be checked, expressed in 899 * 16 bit UTF-16 code units, or -1 if the string is 900 * zero terminated. 901 * @param position Deprecated in ICU 51. Always returns zero. 902 * Originally, an out parameter for the index of the first 903 * string position that failed a check. 904 * This parameter may be NULL. 905 * @param status The error code, set if an error occurred while attempting to 906 * perform the check. 907 * Spoofing or security issues detected with the input string are 908 * not reported here, but through the function's return value. 909 * @return An integer value with bits set for any potential security 910 * or spoofing issues detected. The bits are defined by 911 * enum USpoofChecks. (returned_value & USPOOF_ALL_CHECKS) 912 * will be zero if the input string passes all of the 913 * enabled checks. 914 * @see uspoof_check2 915 * @stable ICU 4.2 916 */ 917 U_STABLE int32_t U_EXPORT2 918 uspoof_check(const USpoofChecker *sc, 919 const UChar *id, int32_t length, 920 int32_t *position, 921 UErrorCode *status); 922 923 924 /** 925 * Check the specified string for possible security issues. 926 * The text to be checked will typically be an identifier of some sort. 927 * The set of checks to be performed is specified with uspoof_setChecks(). 928 * 929 * \note 930 * Consider using the newer API, {@link uspoof_check2UTF8}, instead. 931 * The newer API exposes additional information from the check procedure 932 * and is otherwise identical to this method. 933 * 934 * @param sc The USpoofChecker 935 * @param id A identifier to be checked for possible security issues, in UTF8 format. 936 * @param length the length of the string to be checked, or -1 if the string is 937 * zero terminated. 938 * @param position Deprecated in ICU 51. Always returns zero. 939 * Originally, an out parameter for the index of the first 940 * string position that failed a check. 941 * This parameter may be NULL. 942 * @param status The error code, set if an error occurred while attempting to 943 * perform the check. 944 * Spoofing or security issues detected with the input string are 945 * not reported here, but through the function's return value. 946 * If the input contains invalid UTF-8 sequences, 947 * a status of U_INVALID_CHAR_FOUND will be returned. 948 * @return An integer value with bits set for any potential security 949 * or spoofing issues detected. The bits are defined by 950 * enum USpoofChecks. (returned_value & USPOOF_ALL_CHECKS) 951 * will be zero if the input string passes all of the 952 * enabled checks. 953 * @see uspoof_check2UTF8 954 * @stable ICU 4.2 955 */ 956 U_STABLE int32_t U_EXPORT2 957 uspoof_checkUTF8(const USpoofChecker *sc, 958 const char *id, int32_t length, 959 int32_t *position, 960 UErrorCode *status); 961 962 963 /** 964 * Check the specified string for possible security issues. 965 * The text to be checked will typically be an identifier of some sort. 966 * The set of checks to be performed is specified with uspoof_setChecks(). 967 * 968 * @param sc The USpoofChecker 969 * @param id The identifier to be checked for possible security issues, 970 * in UTF-16 format. 971 * @param length the length of the string to be checked, or -1 if the string is 972 * zero terminated. 973 * @param checkResult An instance of USpoofCheckResult to be filled with 974 * details about the identifier. Can be NULL. 975 * @param status The error code, set if an error occurred while attempting to 976 * perform the check. 977 * Spoofing or security issues detected with the input string are 978 * not reported here, but through the function's return value. 979 * @return An integer value with bits set for any potential security 980 * or spoofing issues detected. The bits are defined by 981 * enum USpoofChecks. (returned_value & USPOOF_ALL_CHECKS) 982 * will be zero if the input string passes all of the 983 * enabled checks. Any information in this bitmask will be 984 * consistent with the information saved in the optional 985 * checkResult parameter. 986 * @see uspoof_openCheckResult 987 * @see uspoof_check2UTF8 988 * @see uspoof_check2UnicodeString 989 * @stable ICU 58 990 */ 991 U_STABLE int32_t U_EXPORT2 992 uspoof_check2(const USpoofChecker *sc, 993 const UChar* id, int32_t length, 994 USpoofCheckResult* checkResult, 995 UErrorCode *status); 996 997 /** 998 * Check the specified string for possible security issues. 999 * The text to be checked will typically be an identifier of some sort. 1000 * The set of checks to be performed is specified with uspoof_setChecks(). 1001 * 1002 * This version of {@link uspoof_check} accepts a USpoofCheckResult, which 1003 * returns additional information about the identifier. For more 1004 * information, see {@link uspoof_openCheckResult}. 1005 * 1006 * @param sc The USpoofChecker 1007 * @param id A identifier to be checked for possible security issues, in UTF8 format. 1008 * @param length the length of the string to be checked, or -1 if the string is 1009 * zero terminated. 1010 * @param checkResult An instance of USpoofCheckResult to be filled with 1011 * details about the identifier. Can be NULL. 1012 * @param status The error code, set if an error occurred while attempting to 1013 * perform the check. 1014 * Spoofing or security issues detected with the input string are 1015 * not reported here, but through the function's return value. 1016 * @return An integer value with bits set for any potential security 1017 * or spoofing issues detected. The bits are defined by 1018 * enum USpoofChecks. (returned_value & USPOOF_ALL_CHECKS) 1019 * will be zero if the input string passes all of the 1020 * enabled checks. Any information in this bitmask will be 1021 * consistent with the information saved in the optional 1022 * checkResult parameter. 1023 * @see uspoof_openCheckResult 1024 * @see uspoof_check2 1025 * @see uspoof_check2UnicodeString 1026 * @stable ICU 58 1027 */ 1028 U_STABLE int32_t U_EXPORT2 1029 uspoof_check2UTF8(const USpoofChecker *sc, 1030 const char *id, int32_t length, 1031 USpoofCheckResult* checkResult, 1032 UErrorCode *status); 1033 1034 /** 1035 * Create a USpoofCheckResult, used by the {@link uspoof_check2} class of functions to return 1036 * information about the identifier. Information includes: 1037 * <ul> 1038 * <li>A bitmask of the checks that failed</li> 1039 * <li>The identifier's restriction level (UTS 39 section 5.2)</li> 1040 * <li>The set of numerics in the string (UTS 39 section 5.3)</li> 1041 * </ul> 1042 * The data held in a USpoofCheckResult is cleared whenever it is passed into a new call 1043 * of {@link uspoof_check2}. 1044 * 1045 * @param status The error code, set if this function encounters a problem. 1046 * @return the newly created USpoofCheckResult 1047 * @see uspoof_check2 1048 * @see uspoof_check2UTF8 1049 * @see uspoof_check2UnicodeString 1050 * @stable ICU 58 1051 */ 1052 U_STABLE USpoofCheckResult* U_EXPORT2 1053 uspoof_openCheckResult(UErrorCode *status); 1054 1055 /** 1056 * Close a USpoofCheckResult, freeing any memory that was being held by 1057 * its implementation. 1058 * 1059 * @param checkResult The instance of USpoofCheckResult to close 1060 * @stable ICU 58 1061 */ 1062 U_STABLE void U_EXPORT2 1063 uspoof_closeCheckResult(USpoofCheckResult *checkResult); 1064 1065 /** 1066 * Indicates which of the spoof check(s) have failed. The value is a bitwise OR of the constants for the tests 1067 * in question: USPOOF_RESTRICTION_LEVEL, USPOOF_CHAR_LIMIT, and so on. 1068 * 1069 * @param checkResult The instance of USpoofCheckResult created by {@link uspoof_openCheckResult} 1070 * @param status The error code, set if an error occurred. 1071 * @return An integer value with bits set for any potential security 1072 * or spoofing issues detected. The bits are defined by 1073 * enum USpoofChecks. (returned_value & USPOOF_ALL_CHECKS) 1074 * will be zero if the input string passes all of the 1075 * enabled checks. 1076 * @see uspoof_setChecks 1077 * @stable ICU 58 1078 */ 1079 U_STABLE int32_t U_EXPORT2 1080 uspoof_getCheckResultChecks(const USpoofCheckResult *checkResult, UErrorCode *status); 1081 1082 /** 1083 * Gets the restriction level that the text meets, if the USPOOF_RESTRICTION_LEVEL check 1084 * was enabled; otherwise, undefined. 1085 * 1086 * @param checkResult The instance of USpoofCheckResult created by {@link uspoof_openCheckResult} 1087 * @param status The error code, set if an error occurred. 1088 * @return The restriction level contained in the USpoofCheckResult 1089 * @see uspoof_setRestrictionLevel 1090 * @stable ICU 58 1091 */ 1092 U_STABLE URestrictionLevel U_EXPORT2 1093 uspoof_getCheckResultRestrictionLevel(const USpoofCheckResult *checkResult, UErrorCode *status); 1094 1095 /** 1096 * Gets the set of numerics found in the string, if the USPOOF_MIXED_NUMBERS check was enabled; 1097 * otherwise, undefined. The set will contain the zero digit from each decimal number system found 1098 * in the input string. Ownership of the returned USet remains with the USpoofCheckResult. 1099 * The USet will be free'd when {@link uspoof_closeCheckResult} is called. 1100 * 1101 * @param checkResult The instance of USpoofCheckResult created by {@link uspoof_openCheckResult} 1102 * @return The set of numerics contained in the USpoofCheckResult 1103 * @param status The error code, set if an error occurred. 1104 * @stable ICU 58 1105 */ 1106 U_STABLE const USet* U_EXPORT2 1107 uspoof_getCheckResultNumerics(const USpoofCheckResult *checkResult, UErrorCode *status); 1108 1109 1110 /** 1111 * Check the whether two specified strings are visually confusable. 1112 * 1113 * If the strings are confusable, the return value will be nonzero, as long as 1114 * {@link USPOOF_CONFUSABLE} was enabled in uspoof_setChecks(). 1115 * 1116 * The bits in the return value correspond to flags for each of the classes of 1117 * confusables applicable to the two input strings. According to UTS 39 1118 * section 4, the possible flags are: 1119 * 1120 * <ul> 1121 * <li>{@link USPOOF_SINGLE_SCRIPT_CONFUSABLE}</li> 1122 * <li>{@link USPOOF_MIXED_SCRIPT_CONFUSABLE}</li> 1123 * <li>{@link USPOOF_WHOLE_SCRIPT_CONFUSABLE}</li> 1124 * </ul> 1125 * 1126 * If one or more of the above flags were not listed in uspoof_setChecks(), this 1127 * function will never report that class of confusable. The check 1128 * {@link USPOOF_CONFUSABLE} enables all three flags. 1129 * 1130 * 1131 * @param sc The USpoofChecker 1132 * @param id1 The first of the two identifiers to be compared for 1133 * confusability. The strings are in UTF-16 format. 1134 * @param length1 the length of the first identifer, expressed in 1135 * 16 bit UTF-16 code units, or -1 if the string is 1136 * nul terminated. 1137 * @param id2 The second of the two identifiers to be compared for 1138 * confusability. The identifiers are in UTF-16 format. 1139 * @param length2 The length of the second identifiers, expressed in 1140 * 16 bit UTF-16 code units, or -1 if the string is 1141 * nul terminated. 1142 * @param status The error code, set if an error occurred while attempting to 1143 * perform the check. 1144 * Confusability of the identifiers is not reported here, 1145 * but through this function's return value. 1146 * @return An integer value with bit(s) set corresponding to 1147 * the type of confusability found, as defined by 1148 * enum USpoofChecks. Zero is returned if the identifiers 1149 * are not confusable. 1150 * 1151 * @stable ICU 4.2 1152 */ 1153 U_STABLE int32_t U_EXPORT2 1154 uspoof_areConfusable(const USpoofChecker *sc, 1155 const UChar *id1, int32_t length1, 1156 const UChar *id2, int32_t length2, 1157 UErrorCode *status); 1158 1159 1160 1161 /** 1162 * A version of {@link uspoof_areConfusable} accepting strings in UTF-8 format. 1163 * 1164 * @param sc The USpoofChecker 1165 * @param id1 The first of the two identifiers to be compared for 1166 * confusability. The strings are in UTF-8 format. 1167 * @param length1 the length of the first identifiers, in bytes, or -1 1168 * if the string is nul terminated. 1169 * @param id2 The second of the two identifiers to be compared for 1170 * confusability. The strings are in UTF-8 format. 1171 * @param length2 The length of the second string in bytes, or -1 1172 * if the string is nul terminated. 1173 * @param status The error code, set if an error occurred while attempting to 1174 * perform the check. 1175 * Confusability of the strings is not reported here, 1176 * but through this function's return value. 1177 * @return An integer value with bit(s) set corresponding to 1178 * the type of confusability found, as defined by 1179 * enum USpoofChecks. Zero is returned if the strings 1180 * are not confusable. 1181 * 1182 * @stable ICU 4.2 1183 * 1184 * @see uspoof_areConfusable 1185 */ 1186 U_STABLE int32_t U_EXPORT2 1187 uspoof_areConfusableUTF8(const USpoofChecker *sc, 1188 const char *id1, int32_t length1, 1189 const char *id2, int32_t length2, 1190 UErrorCode *status); 1191 1192 1193 1194 1195 /** 1196 * Get the "skeleton" for an identifier. 1197 * Skeletons are a transformation of the input identifier; 1198 * Two identifiers are confusable if their skeletons are identical. 1199 * See Unicode UAX #39 for additional information. 1200 * 1201 * Using skeletons directly makes it possible to quickly check 1202 * whether an identifier is confusable with any of some large 1203 * set of existing identifiers, by creating an efficiently 1204 * searchable collection of the skeletons. 1205 * 1206 * @param sc The USpoofChecker 1207 * @param type Deprecated in ICU 58. You may pass any number. 1208 * Originally, controlled which of the Unicode confusable data 1209 * tables to use. 1210 * @param id The input identifier whose skeleton will be computed. 1211 * @param length The length of the input identifier, expressed in 16 bit 1212 * UTF-16 code units, or -1 if the string is zero terminated. 1213 * @param dest The output buffer, to receive the skeleton string. 1214 * @param destCapacity The length of the output buffer, in 16 bit units. 1215 * The destCapacity may be zero, in which case the function will 1216 * return the actual length of the skeleton. 1217 * @param status The error code, set if an error occurred while attempting to 1218 * perform the check. 1219 * @return The length of the skeleton string. The returned length 1220 * is always that of the complete skeleton, even when the 1221 * supplied buffer is too small (or of zero length) 1222 * 1223 * @stable ICU 4.2 1224 * @see uspoof_areConfusable 1225 */ 1226 U_STABLE int32_t U_EXPORT2 1227 uspoof_getSkeleton(const USpoofChecker *sc, 1228 uint32_t type, 1229 const UChar *id, int32_t length, 1230 UChar *dest, int32_t destCapacity, 1231 UErrorCode *status); 1232 1233 /** 1234 * Get the "skeleton" for an identifier. 1235 * Skeletons are a transformation of the input identifier; 1236 * Two identifiers are confusable if their skeletons are identical. 1237 * See Unicode UAX #39 for additional information. 1238 * 1239 * Using skeletons directly makes it possible to quickly check 1240 * whether an identifier is confusable with any of some large 1241 * set of existing identifiers, by creating an efficiently 1242 * searchable collection of the skeletons. 1243 * 1244 * @param sc The USpoofChecker 1245 * @param type Deprecated in ICU 58. You may pass any number. 1246 * Originally, controlled which of the Unicode confusable data 1247 * tables to use. 1248 * @param id The UTF-8 format identifier whose skeleton will be computed. 1249 * @param length The length of the input string, in bytes, 1250 * or -1 if the string is zero terminated. 1251 * @param dest The output buffer, to receive the skeleton string. 1252 * @param destCapacity The length of the output buffer, in bytes. 1253 * The destCapacity may be zero, in which case the function will 1254 * return the actual length of the skeleton. 1255 * @param status The error code, set if an error occurred while attempting to 1256 * perform the check. Possible Errors include U_INVALID_CHAR_FOUND 1257 * for invalid UTF-8 sequences, and 1258 * U_BUFFER_OVERFLOW_ERROR if the destination buffer is too small 1259 * to hold the complete skeleton. 1260 * @return The length of the skeleton string, in bytes. The returned length 1261 * is always that of the complete skeleton, even when the 1262 * supplied buffer is too small (or of zero length) 1263 * 1264 * @stable ICU 4.2 1265 */ 1266 U_STABLE int32_t U_EXPORT2 1267 uspoof_getSkeletonUTF8(const USpoofChecker *sc, 1268 uint32_t type, 1269 const char *id, int32_t length, 1270 char *dest, int32_t destCapacity, 1271 UErrorCode *status); 1272 1273 /** 1274 * Get the set of Candidate Characters for Inclusion in Identifiers, as defined 1275 * in http://unicode.org/Public/security/latest/xidmodifications.txt 1276 * and documented in http://www.unicode.org/reports/tr39/, Unicode Security Mechanisms. 1277 * 1278 * The returned set is frozen. Ownership of the set remains with the ICU library; it must not 1279 * be deleted by the caller. 1280 * 1281 * @param status The error code, set if a problem occurs while creating the set. 1282 * 1283 * @stable ICU 51 1284 */ 1285 U_STABLE const USet * U_EXPORT2 1286 uspoof_getInclusionSet(UErrorCode *status); 1287 1288 /** 1289 * Get the set of characters from Recommended Scripts for Inclusion in Identifiers, as defined 1290 * in http://unicode.org/Public/security/latest/xidmodifications.txt 1291 * and documented in http://www.unicode.org/reports/tr39/, Unicode Security Mechanisms. 1292 * 1293 * The returned set is frozen. Ownership of the set remains with the ICU library; it must not 1294 * be deleted by the caller. 1295 * 1296 * @param status The error code, set if a problem occurs while creating the set. 1297 * 1298 * @stable ICU 51 1299 */ 1300 U_STABLE const USet * U_EXPORT2 1301 uspoof_getRecommendedSet(UErrorCode *status); 1302 1303 /** 1304 * Serialize the data for a spoof detector into a chunk of memory. 1305 * The flattened spoof detection tables can later be used to efficiently 1306 * instantiate a new Spoof Detector. 1307 * 1308 * The serialized spoof checker includes only the data compiled from the 1309 * Unicode data tables by uspoof_openFromSource(); it does not include 1310 * include any other state or configuration that may have been set. 1311 * 1312 * @param sc the Spoof Detector whose data is to be serialized. 1313 * @param data a pointer to 32-bit-aligned memory to be filled with the data, 1314 * can be NULL if capacity==0 1315 * @param capacity the number of bytes available at data, 1316 * or 0 for preflighting 1317 * @param status an in/out ICU UErrorCode; possible errors include: 1318 * - U_BUFFER_OVERFLOW_ERROR if the data storage block is too small for serialization 1319 * - U_ILLEGAL_ARGUMENT_ERROR the data or capacity parameters are bad 1320 * @return the number of bytes written or needed for the spoof data 1321 * 1322 * @see utrie2_openFromSerialized() 1323 * @stable ICU 4.2 1324 */ 1325 U_STABLE int32_t U_EXPORT2 1326 uspoof_serialize(USpoofChecker *sc, 1327 void *data, int32_t capacity, 1328 UErrorCode *status); 1329 1330 U_CDECL_END 1331 1332 #if U_SHOW_CPLUSPLUS_API 1333 1334 U_NAMESPACE_BEGIN 1335 1336 /** 1337 * \class LocalUSpoofCheckerPointer 1338 * "Smart pointer" class, closes a USpoofChecker via uspoof_close(). 1339 * For most methods see the LocalPointerBase base class. 1340 * 1341 * @see LocalPointerBase 1342 * @see LocalPointer 1343 * @stable ICU 4.4 1344 */ 1345 /** 1346 * \cond 1347 * Note: Doxygen is giving a bogus warning on this U_DEFINE_LOCAL_OPEN_POINTER. 1348 * For now, suppress with a Doxygen cond 1349 */ 1350 U_DEFINE_LOCAL_OPEN_POINTER(LocalUSpoofCheckerPointer, USpoofChecker, uspoof_close); 1351 /** \endcond */ 1352 1353 /** 1354 * \class LocalUSpoofCheckResultPointer 1355 * "Smart pointer" class, closes a USpoofCheckResult via `uspoof_closeCheckResult()`. 1356 * For most methods see the LocalPointerBase base class. 1357 * 1358 * @see LocalPointerBase 1359 * @see LocalPointer 1360 * @stable ICU 58 1361 */ 1362 1363 /** 1364 * \cond 1365 * Note: Doxygen is giving a bogus warning on this U_DEFINE_LOCAL_OPEN_POINTER. 1366 * For now, suppress with a Doxygen cond 1367 */ 1368 U_DEFINE_LOCAL_OPEN_POINTER(LocalUSpoofCheckResultPointer, USpoofCheckResult, uspoof_closeCheckResult); 1369 /** \endcond */ 1370 1371 U_NAMESPACE_END 1372 1373 /** 1374 * Limit the acceptable characters to those specified by a Unicode Set. 1375 * Any previously specified character limit is 1376 * is replaced by the new settings. This includes limits on 1377 * characters that were set with the uspoof_setAllowedLocales() function. 1378 * 1379 * The USPOOF_CHAR_LIMIT test is automatically enabled for this 1380 * USoofChecker by this function. 1381 * 1382 * @param sc The USpoofChecker 1383 * @param chars A Unicode Set containing the list of 1384 * characters that are permitted. Ownership of the set 1385 * remains with the caller. The incoming set is cloned by 1386 * this function, so there are no restrictions on modifying 1387 * or deleting the UnicodeSet after calling this function. 1388 * @param status The error code, set if this function encounters a problem. 1389 * @stable ICU 4.2 1390 */ 1391 U_STABLE void U_EXPORT2 1392 uspoof_setAllowedUnicodeSet(USpoofChecker *sc, const icu::UnicodeSet *chars, UErrorCode *status); 1393 1394 1395 /** 1396 * Get a UnicodeSet for the characters permitted in an identifier. 1397 * This corresponds to the limits imposed by the Set Allowed Characters / 1398 * UnicodeSet functions. Limitations imposed by other checks will not be 1399 * reflected in the set returned by this function. 1400 * 1401 * The returned set will be frozen, meaning that it cannot be modified 1402 * by the caller. 1403 * 1404 * Ownership of the returned set remains with the Spoof Detector. The 1405 * returned set will become invalid if the spoof detector is closed, 1406 * or if a new set of allowed characters is specified. 1407 * 1408 * 1409 * @param sc The USpoofChecker 1410 * @param status The error code, set if this function encounters a problem. 1411 * @return A UnicodeSet containing the characters that are permitted by 1412 * the USPOOF_CHAR_LIMIT test. 1413 * @stable ICU 4.2 1414 */ 1415 U_STABLE const icu::UnicodeSet * U_EXPORT2 1416 uspoof_getAllowedUnicodeSet(const USpoofChecker *sc, UErrorCode *status); 1417 1418 /** 1419 * Check the specified string for possible security issues. 1420 * The text to be checked will typically be an identifier of some sort. 1421 * The set of checks to be performed is specified with uspoof_setChecks(). 1422 * 1423 * \note 1424 * Consider using the newer API, {@link uspoof_check2UnicodeString}, instead. 1425 * The newer API exposes additional information from the check procedure 1426 * and is otherwise identical to this method. 1427 * 1428 * @param sc The USpoofChecker 1429 * @param id A identifier to be checked for possible security issues. 1430 * @param position Deprecated in ICU 51. Always returns zero. 1431 * Originally, an out parameter for the index of the first 1432 * string position that failed a check. 1433 * This parameter may be NULL. 1434 * @param status The error code, set if an error occurred while attempting to 1435 * perform the check. 1436 * Spoofing or security issues detected with the input string are 1437 * not reported here, but through the function's return value. 1438 * @return An integer value with bits set for any potential security 1439 * or spoofing issues detected. The bits are defined by 1440 * enum USpoofChecks. (returned_value & USPOOF_ALL_CHECKS) 1441 * will be zero if the input string passes all of the 1442 * enabled checks. 1443 * @see uspoof_check2UnicodeString 1444 * @stable ICU 4.2 1445 */ 1446 U_STABLE int32_t U_EXPORT2 1447 uspoof_checkUnicodeString(const USpoofChecker *sc, 1448 const icu::UnicodeString &id, 1449 int32_t *position, 1450 UErrorCode *status); 1451 1452 /** 1453 * Check the specified string for possible security issues. 1454 * The text to be checked will typically be an identifier of some sort. 1455 * The set of checks to be performed is specified with uspoof_setChecks(). 1456 * 1457 * @param sc The USpoofChecker 1458 * @param id A identifier to be checked for possible security issues. 1459 * @param checkResult An instance of USpoofCheckResult to be filled with 1460 * details about the identifier. Can be NULL. 1461 * @param status The error code, set if an error occurred while attempting to 1462 * perform the check. 1463 * Spoofing or security issues detected with the input string are 1464 * not reported here, but through the function's return value. 1465 * @return An integer value with bits set for any potential security 1466 * or spoofing issues detected. The bits are defined by 1467 * enum USpoofChecks. (returned_value & USPOOF_ALL_CHECKS) 1468 * will be zero if the input string passes all of the 1469 * enabled checks. Any information in this bitmask will be 1470 * consistent with the information saved in the optional 1471 * checkResult parameter. 1472 * @see uspoof_openCheckResult 1473 * @see uspoof_check2 1474 * @see uspoof_check2UTF8 1475 * @stable ICU 58 1476 */ 1477 U_STABLE int32_t U_EXPORT2 1478 uspoof_check2UnicodeString(const USpoofChecker *sc, 1479 const icu::UnicodeString &id, 1480 USpoofCheckResult* checkResult, 1481 UErrorCode *status); 1482 1483 /** 1484 * A version of {@link uspoof_areConfusable} accepting UnicodeStrings. 1485 * 1486 * @param sc The USpoofChecker 1487 * @param s1 The first of the two identifiers to be compared for 1488 * confusability. The strings are in UTF-8 format. 1489 * @param s2 The second of the two identifiers to be compared for 1490 * confusability. The strings are in UTF-8 format. 1491 * @param status The error code, set if an error occurred while attempting to 1492 * perform the check. 1493 * Confusability of the identifiers is not reported here, 1494 * but through this function's return value. 1495 * @return An integer value with bit(s) set corresponding to 1496 * the type of confusability found, as defined by 1497 * enum USpoofChecks. Zero is returned if the identifiers 1498 * are not confusable. 1499 * 1500 * @stable ICU 4.2 1501 * 1502 * @see uspoof_areConfusable 1503 */ 1504 U_STABLE int32_t U_EXPORT2 1505 uspoof_areConfusableUnicodeString(const USpoofChecker *sc, 1506 const icu::UnicodeString &s1, 1507 const icu::UnicodeString &s2, 1508 UErrorCode *status); 1509 1510 /** 1511 * Get the "skeleton" for an identifier. 1512 * Skeletons are a transformation of the input identifier; 1513 * Two identifiers are confusable if their skeletons are identical. 1514 * See Unicode UAX #39 for additional information. 1515 * 1516 * Using skeletons directly makes it possible to quickly check 1517 * whether an identifier is confusable with any of some large 1518 * set of existing identifiers, by creating an efficiently 1519 * searchable collection of the skeletons. 1520 * 1521 * @param sc The USpoofChecker. 1522 * @param type Deprecated in ICU 58. You may pass any number. 1523 * Originally, controlled which of the Unicode confusable data 1524 * tables to use. 1525 * @param id The input identifier whose skeleton will be computed. 1526 * @param dest The output identifier, to receive the skeleton string. 1527 * @param status The error code, set if an error occurred while attempting to 1528 * perform the check. 1529 * @return A reference to the destination (skeleton) string. 1530 * 1531 * @stable ICU 4.2 1532 */ 1533 U_I18N_API icu::UnicodeString & U_EXPORT2 1534 uspoof_getSkeletonUnicodeString(const USpoofChecker *sc, 1535 uint32_t type, 1536 const icu::UnicodeString &id, 1537 icu::UnicodeString &dest, 1538 UErrorCode *status); 1539 1540 /** 1541 * Get the set of Candidate Characters for Inclusion in Identifiers, as defined 1542 * in http://unicode.org/Public/security/latest/xidmodifications.txt 1543 * and documented in http://www.unicode.org/reports/tr39/, Unicode Security Mechanisms. 1544 * 1545 * The returned set is frozen. Ownership of the set remains with the ICU library; it must not 1546 * be deleted by the caller. 1547 * 1548 * @param status The error code, set if a problem occurs while creating the set. 1549 * 1550 * @stable ICU 51 1551 */ 1552 U_STABLE const icu::UnicodeSet * U_EXPORT2 1553 uspoof_getInclusionUnicodeSet(UErrorCode *status); 1554 1555 /** 1556 * Get the set of characters from Recommended Scripts for Inclusion in Identifiers, as defined 1557 * in http://unicode.org/Public/security/latest/xidmodifications.txt 1558 * and documented in http://www.unicode.org/reports/tr39/, Unicode Security Mechanisms. 1559 * 1560 * The returned set is frozen. Ownership of the set remains with the ICU library; it must not 1561 * be deleted by the caller. 1562 * 1563 * @param status The error code, set if a problem occurs while creating the set. 1564 * 1565 * @stable ICU 51 1566 */ 1567 U_STABLE const icu::UnicodeSet * U_EXPORT2 1568 uspoof_getRecommendedUnicodeSet(UErrorCode *status); 1569 1570 #endif /* U_SHOW_CPLUSPLUS_API */ 1571 1572 #endif /* UCONFIG_NO_NORMALIZATION */ 1573 1574 #endif /* USPOOF_H */ 1575