jpayne@69: // © 2016 and later: Unicode, Inc. and others. jpayne@69: // License & terms of use: http://www.unicode.org/copyright.html jpayne@69: /* jpayne@69: *************************************************************************** jpayne@69: * Copyright (C) 2008-2016, International Business Machines Corporation jpayne@69: * and others. All Rights Reserved. jpayne@69: *************************************************************************** jpayne@69: * file name: uspoof.h jpayne@69: * encoding: UTF-8 jpayne@69: * tab size: 8 (not used) jpayne@69: * indentation:4 jpayne@69: * jpayne@69: * created on: 2008Feb13 jpayne@69: * created by: Andy Heninger jpayne@69: * jpayne@69: * Unicode Spoof Detection jpayne@69: */ jpayne@69: jpayne@69: #ifndef USPOOF_H jpayne@69: #define USPOOF_H jpayne@69: jpayne@69: #include "unicode/utypes.h" jpayne@69: #include "unicode/uset.h" jpayne@69: #include "unicode/parseerr.h" jpayne@69: #include "unicode/localpointer.h" jpayne@69: jpayne@69: #if !UCONFIG_NO_NORMALIZATION jpayne@69: jpayne@69: jpayne@69: #if U_SHOW_CPLUSPLUS_API jpayne@69: #include "unicode/unistr.h" jpayne@69: #include "unicode/uniset.h" jpayne@69: #endif jpayne@69: jpayne@69: jpayne@69: /** jpayne@69: * \file jpayne@69: * \brief Unicode Security and Spoofing Detection, C API. jpayne@69: * jpayne@69: *

jpayne@69: * This class, based on Unicode Technical Report #36 and jpayne@69: * Unicode Technical Standard #39, has two main functions: jpayne@69: * jpayne@69: *

    jpayne@69: *
  1. Checking whether two strings are visually confusable with each other, such as "Harvest" and jpayne@69: * "Ηarvest", where the second string starts with the Greek capital letter Eta.
    2. jpayne@69: *
  2. Checking whether an individual string is likely to be an attempt at confusing the reader (spoof jpayne@69: * detection), such as "paypal" with some Latin characters substituted with Cyrillic look-alikes.
    3. jpayne@69: *
jpayne@69: * jpayne@69: *

jpayne@69: * Although originally designed as a method for flagging suspicious identifier strings such as URLs, jpayne@69: * USpoofChecker has a number of other practical use cases, such as preventing attempts to evade bad-word jpayne@69: * content filters. jpayne@69: * jpayne@69: *

jpayne@69: * The functions of this class are exposed as C API, with a handful of syntactical conveniences for C++. jpayne@69: * jpayne@69: *

Confusables

jpayne@69: * jpayne@69: *

jpayne@69: * The following example shows how to use USpoofChecker to check for confusability between two strings: jpayne@69: * jpayne@69: * \code{.c} jpayne@69: * UErrorCode status = U_ZERO_ERROR; jpayne@69: * UChar* str1 = (UChar*) u"Harvest"; jpayne@69: * UChar* str2 = (UChar*) u"\u0397arvest"; // with U+0397 GREEK CAPITAL LETTER ETA jpayne@69: * jpayne@69: * USpoofChecker* sc = uspoof_open(&status); jpayne@69: * uspoof_setChecks(sc, USPOOF_CONFUSABLE, &status); jpayne@69: * jpayne@69: * int32_t bitmask = uspoof_areConfusable(sc, str1, -1, str2, -1, &status); jpayne@69: * UBool result = bitmask != 0; jpayne@69: * // areConfusable: 1 (status: U_ZERO_ERROR) jpayne@69: * printf("areConfusable: %d (status: %s)\n", result, u_errorName(status)); jpayne@69: * uspoof_close(sc); jpayne@69: * \endcode jpayne@69: * jpayne@69: *

jpayne@69: * The call to {@link uspoof_open} creates a USpoofChecker object; the call to {@link uspoof_setChecks} jpayne@69: * enables confusable checking and disables all other checks; the call to {@link uspoof_areConfusable} performs the jpayne@69: * confusability test; and the following line extracts the result out of the return value. For best performance, jpayne@69: * the instance should be created once (e.g., upon application startup), and the efficient jpayne@69: * {@link uspoof_areConfusable} method can be used at runtime. jpayne@69: * jpayne@69: *

jpayne@69: * The type {@link LocalUSpoofCheckerPointer} is exposed for C++ programmers. It will automatically call jpayne@69: * {@link uspoof_close} when the object goes out of scope: jpayne@69: * jpayne@69: * \code{.cpp} jpayne@69: * UErrorCode status = U_ZERO_ERROR; jpayne@69: * LocalUSpoofCheckerPointer sc(uspoof_open(&status)); jpayne@69: * uspoof_setChecks(sc.getAlias(), USPOOF_CONFUSABLE, &status); jpayne@69: * // ... jpayne@69: * \endcode jpayne@69: * jpayne@69: * UTS 39 defines two strings to be confusable if they map to the same skeleton string. A skeleton can jpayne@69: * be thought of as a "hash code". {@link uspoof_getSkeleton} computes the skeleton for a particular string, so jpayne@69: * the following snippet is equivalent to the example above: jpayne@69: * jpayne@69: * \code{.c} jpayne@69: * UErrorCode status = U_ZERO_ERROR; jpayne@69: * UChar* str1 = (UChar*) u"Harvest"; jpayne@69: * UChar* str2 = (UChar*) u"\u0397arvest"; // with U+0397 GREEK CAPITAL LETTER ETA jpayne@69: * jpayne@69: * USpoofChecker* sc = uspoof_open(&status); jpayne@69: * uspoof_setChecks(sc, USPOOF_CONFUSABLE, &status); jpayne@69: * jpayne@69: * // Get skeleton 1 jpayne@69: * int32_t skel1Len = uspoof_getSkeleton(sc, 0, str1, -1, NULL, 0, &status); jpayne@69: * UChar* skel1 = (UChar*) malloc(++skel1Len * sizeof(UChar)); jpayne@69: * status = U_ZERO_ERROR; jpayne@69: * uspoof_getSkeleton(sc, 0, str1, -1, skel1, skel1Len, &status); jpayne@69: * jpayne@69: * // Get skeleton 2 jpayne@69: * int32_t skel2Len = uspoof_getSkeleton(sc, 0, str2, -1, NULL, 0, &status); jpayne@69: * UChar* skel2 = (UChar*) malloc(++skel2Len * sizeof(UChar)); jpayne@69: * status = U_ZERO_ERROR; jpayne@69: * uspoof_getSkeleton(sc, 0, str2, -1, skel2, skel2Len, &status); jpayne@69: * jpayne@69: * // Are the skeletons the same? jpayne@69: * UBool result = u_strcmp(skel1, skel2) == 0; jpayne@69: * // areConfusable: 1 (status: U_ZERO_ERROR) jpayne@69: * printf("areConfusable: %d (status: %s)\n", result, u_errorName(status)); jpayne@69: * uspoof_close(sc); jpayne@69: * free(skel1); jpayne@69: * free(skel2); jpayne@69: * \endcode jpayne@69: * jpayne@69: * If you need to check if a string is confusable with any string in a dictionary of many strings, rather than calling jpayne@69: * {@link uspoof_areConfusable} many times in a loop, {@link uspoof_getSkeleton} can be used instead, as shown below: jpayne@69: * jpayne@69: * \code{.c} jpayne@69: * UErrorCode status = U_ZERO_ERROR; jpayne@69: * #define DICTIONARY_LENGTH 2 jpayne@69: * UChar* dictionary[DICTIONARY_LENGTH] = { (UChar*) u"lorem", (UChar*) u"ipsum" }; jpayne@69: * UChar* skeletons[DICTIONARY_LENGTH]; jpayne@69: * UChar* str = (UChar*) u"1orern"; jpayne@69: * jpayne@69: * // Setup: jpayne@69: * USpoofChecker* sc = uspoof_open(&status); jpayne@69: * uspoof_setChecks(sc, USPOOF_CONFUSABLE, &status); jpayne@69: * for (size_t i=0; iNote: Since the Unicode confusables mapping table is frequently updated, confusable skeletons are not jpayne@69: * guaranteed to be the same between ICU releases. We therefore recommend that you always compute confusable skeletons jpayne@69: * at runtime and do not rely on creating a permanent, or difficult to update, database of skeletons. jpayne@69: * jpayne@69: *

Spoof Detection

jpayne@69: * jpayne@69: * The following snippet shows a minimal example of using USpoofChecker to perform spoof detection on a jpayne@69: * string: jpayne@69: * jpayne@69: * \code{.c} jpayne@69: * UErrorCode status = U_ZERO_ERROR; jpayne@69: * UChar* str = (UChar*) u"p\u0430ypal"; // with U+0430 CYRILLIC SMALL LETTER A jpayne@69: * jpayne@69: * // Get the default set of allowable characters: jpayne@69: * USet* allowed = uset_openEmpty(); jpayne@69: * uset_addAll(allowed, uspoof_getRecommendedSet(&status)); jpayne@69: * uset_addAll(allowed, uspoof_getInclusionSet(&status)); jpayne@69: * jpayne@69: * USpoofChecker* sc = uspoof_open(&status); jpayne@69: * uspoof_setAllowedChars(sc, allowed, &status); jpayne@69: * uspoof_setRestrictionLevel(sc, USPOOF_MODERATELY_RESTRICTIVE); jpayne@69: * jpayne@69: * int32_t bitmask = uspoof_check(sc, str, -1, NULL, &status); jpayne@69: * UBool result = bitmask != 0; jpayne@69: * // fails checks: 1 (status: U_ZERO_ERROR) jpayne@69: * printf("fails checks: %d (status: %s)\n", result, u_errorName(status)); jpayne@69: * uspoof_close(sc); jpayne@69: * uset_close(allowed); jpayne@69: * \endcode jpayne@69: * jpayne@69: * As in the case for confusability checking, it is good practice to create one USpoofChecker instance at jpayne@69: * startup, and call the cheaper {@link uspoof_check} online. We specify the set of jpayne@69: * allowed characters to be those with type RECOMMENDED or INCLUSION, according to the recommendation in UTS 39. jpayne@69: * jpayne@69: * In addition to {@link uspoof_check}, the function {@link uspoof_checkUTF8} is exposed for UTF8-encoded char* strings, jpayne@69: * and {@link uspoof_checkUnicodeString} is exposed for C++ programmers. jpayne@69: * jpayne@69: * If the {@link USPOOF_AUX_INFO} check is enabled, a limited amount of information on why a string failed the checks jpayne@69: * is available in the returned bitmask. For complete information, use the {@link uspoof_check2} class of functions jpayne@69: * with a {@link USpoofCheckResult} parameter: jpayne@69: * jpayne@69: * \code{.c} jpayne@69: * UErrorCode status = U_ZERO_ERROR; jpayne@69: * UChar* str = (UChar*) u"p\u0430ypal"; // with U+0430 CYRILLIC SMALL LETTER A jpayne@69: * jpayne@69: * // Get the default set of allowable characters: jpayne@69: * USet* allowed = uset_openEmpty(); jpayne@69: * uset_addAll(allowed, uspoof_getRecommendedSet(&status)); jpayne@69: * uset_addAll(allowed, uspoof_getInclusionSet(&status)); jpayne@69: * jpayne@69: * USpoofChecker* sc = uspoof_open(&status); jpayne@69: * uspoof_setAllowedChars(sc, allowed, &status); jpayne@69: * uspoof_setRestrictionLevel(sc, USPOOF_MODERATELY_RESTRICTIVE); jpayne@69: * jpayne@69: * USpoofCheckResult* checkResult = uspoof_openCheckResult(&status); jpayne@69: * int32_t bitmask = uspoof_check2(sc, str, -1, checkResult, &status); jpayne@69: * jpayne@69: * int32_t failures1 = bitmask; jpayne@69: * int32_t failures2 = uspoof_getCheckResultChecks(checkResult, &status); jpayne@69: * assert(failures1 == failures2); jpayne@69: * // checks that failed: 0x00000010 (status: U_ZERO_ERROR) jpayne@69: * printf("checks that failed: %#010x (status: %s)\n", failures1, u_errorName(status)); jpayne@69: * jpayne@69: * // Cleanup: jpayne@69: * uspoof_close(sc); jpayne@69: * uset_close(allowed); jpayne@69: * uspoof_closeCheckResult(checkResult); jpayne@69: * \endcode jpayne@69: * jpayne@69: * C++ users can take advantage of a few syntactical conveniences. The following snippet is functionally jpayne@69: * equivalent to the one above: jpayne@69: * jpayne@69: * \code{.cpp} jpayne@69: * UErrorCode status = U_ZERO_ERROR; jpayne@69: * UnicodeString str((UChar*) u"p\u0430ypal"); // with U+0430 CYRILLIC SMALL LETTER A jpayne@69: * jpayne@69: * // Get the default set of allowable characters: jpayne@69: * UnicodeSet allowed; jpayne@69: * allowed.addAll(*uspoof_getRecommendedUnicodeSet(&status)); jpayne@69: * allowed.addAll(*uspoof_getInclusionUnicodeSet(&status)); jpayne@69: * jpayne@69: * LocalUSpoofCheckerPointer sc(uspoof_open(&status)); jpayne@69: * uspoof_setAllowedChars(sc.getAlias(), allowed.toUSet(), &status); jpayne@69: * uspoof_setRestrictionLevel(sc.getAlias(), USPOOF_MODERATELY_RESTRICTIVE); jpayne@69: * jpayne@69: * LocalUSpoofCheckResultPointer checkResult(uspoof_openCheckResult(&status)); jpayne@69: * int32_t bitmask = uspoof_check2UnicodeString(sc.getAlias(), str, checkResult.getAlias(), &status); jpayne@69: * jpayne@69: * int32_t failures1 = bitmask; jpayne@69: * int32_t failures2 = uspoof_getCheckResultChecks(checkResult.getAlias(), &status); jpayne@69: * assert(failures1 == failures2); jpayne@69: * // checks that failed: 0x00000010 (status: U_ZERO_ERROR) jpayne@69: * printf("checks that failed: %#010x (status: %s)\n", failures1, u_errorName(status)); jpayne@69: * jpayne@69: * // Explicit cleanup not necessary. jpayne@69: * \endcode jpayne@69: * jpayne@69: * The return value is a bitmask of the checks that failed. In this case, there was one check that failed: jpayne@69: * {@link USPOOF_RESTRICTION_LEVEL}, corresponding to the fifth bit (16). The possible checks are: jpayne@69: * jpayne@69: * jpayne@69: * jpayne@69: *

jpayne@69: * These checks can be enabled independently of each other. For example, if you were interested in checking for only the jpayne@69: * INVISIBLE and MIXED_NUMBERS conditions, you could do: jpayne@69: * jpayne@69: * \code{.c} jpayne@69: * UErrorCode status = U_ZERO_ERROR; jpayne@69: * UChar* str = (UChar*) u"8\u09EA"; // 8 mixed with U+09EA BENGALI DIGIT FOUR jpayne@69: * jpayne@69: * USpoofChecker* sc = uspoof_open(&status); jpayne@69: * uspoof_setChecks(sc, USPOOF_INVISIBLE | USPOOF_MIXED_NUMBERS, &status); jpayne@69: * jpayne@69: * int32_t bitmask = uspoof_check2(sc, str, -1, NULL, &status); jpayne@69: * UBool result = bitmask != 0; jpayne@69: * // fails checks: 1 (status: U_ZERO_ERROR) jpayne@69: * printf("fails checks: %d (status: %s)\n", result, u_errorName(status)); jpayne@69: * uspoof_close(sc); jpayne@69: * \endcode jpayne@69: * jpayne@69: * Here is an example in C++ showing how to compute the restriction level of a string: jpayne@69: * jpayne@69: * \code{.cpp} jpayne@69: * UErrorCode status = U_ZERO_ERROR; jpayne@69: * UnicodeString str((UChar*) u"p\u0430ypal"); // with U+0430 CYRILLIC SMALL LETTER A jpayne@69: * jpayne@69: * // Get the default set of allowable characters: jpayne@69: * UnicodeSet allowed; jpayne@69: * allowed.addAll(*uspoof_getRecommendedUnicodeSet(&status)); jpayne@69: * allowed.addAll(*uspoof_getInclusionUnicodeSet(&status)); jpayne@69: * jpayne@69: * LocalUSpoofCheckerPointer sc(uspoof_open(&status)); jpayne@69: * uspoof_setAllowedChars(sc.getAlias(), allowed.toUSet(), &status); jpayne@69: * uspoof_setRestrictionLevel(sc.getAlias(), USPOOF_MODERATELY_RESTRICTIVE); jpayne@69: * uspoof_setChecks(sc.getAlias(), USPOOF_RESTRICTION_LEVEL | USPOOF_AUX_INFO, &status); jpayne@69: * jpayne@69: * LocalUSpoofCheckResultPointer checkResult(uspoof_openCheckResult(&status)); jpayne@69: * int32_t bitmask = uspoof_check2UnicodeString(sc.getAlias(), str, checkResult.getAlias(), &status); jpayne@69: * jpayne@69: * URestrictionLevel restrictionLevel = uspoof_getCheckResultRestrictionLevel(checkResult.getAlias(), &status); jpayne@69: * // Since USPOOF_AUX_INFO was enabled, the restriction level is also available in the upper bits of the bitmask: jpayne@69: * assert((restrictionLevel & bitmask) == restrictionLevel); jpayne@69: * // Restriction level: 0x50000000 (status: U_ZERO_ERROR) jpayne@69: * printf("Restriction level: %#010x (status: %s)\n", restrictionLevel, u_errorName(status)); jpayne@69: * \endcode jpayne@69: * jpayne@69: * The code '0x50000000' corresponds to the restriction level USPOOF_MINIMALLY_RESTRICTIVE. Since jpayne@69: * USPOOF_MINIMALLY_RESTRICTIVE is weaker than USPOOF_MODERATELY_RESTRICTIVE, the string fails the check. jpayne@69: * jpayne@69: * Note: The Restriction Level is the most powerful of the checks. The full logic is documented in jpayne@69: * UTS 39, but the basic idea is that strings jpayne@69: * are restricted to contain characters from only a single script, except that most scripts are allowed to have jpayne@69: * Latin characters interspersed. Although the default restriction level is HIGHLY_RESTRICTIVE, it is jpayne@69: * recommended that users set their restriction level to MODERATELY_RESTRICTIVE, which allows Latin mixed jpayne@69: * with all other scripts except Cyrillic, Greek, and Cherokee, with which it is often confusable. For more details on jpayne@69: * the levels, see UTS 39 or {@link URestrictionLevel}. The Restriction Level test is aware of the set of jpayne@69: * allowed characters set in {@link uspoof_setAllowedChars}. Note that characters which have script code jpayne@69: * COMMON or INHERITED, such as numbers and punctuation, are ignored when computing whether a string has multiple jpayne@69: * scripts. jpayne@69: * jpayne@69: *

Additional Information

jpayne@69: * jpayne@69: * A USpoofChecker instance may be used repeatedly to perform checks on any number of identifiers. jpayne@69: * jpayne@69: * Thread Safety: The test functions for checking a single identifier, or for testing whether jpayne@69: * two identifiers are possible confusable, are thread safe. They may called concurrently, from multiple threads, jpayne@69: * using the same USpoofChecker instance. jpayne@69: * jpayne@69: * More generally, the standard ICU thread safety rules apply: functions that take a const USpoofChecker parameter are jpayne@69: * thread safe. Those that take a non-const USpoofChecker are not thread safe.. jpayne@69: * jpayne@69: * @stable ICU 4.6 jpayne@69: */ jpayne@69: jpayne@69: U_CDECL_BEGIN jpayne@69: jpayne@69: struct USpoofChecker; jpayne@69: /** jpayne@69: * @stable ICU 4.2 jpayne@69: */ jpayne@69: typedef struct USpoofChecker USpoofChecker; /**< typedef for C of USpoofChecker */ jpayne@69: jpayne@69: struct USpoofCheckResult; jpayne@69: /** jpayne@69: * @see uspoof_openCheckResult jpayne@69: * @stable ICU 58 jpayne@69: */ jpayne@69: typedef struct USpoofCheckResult USpoofCheckResult; jpayne@69: jpayne@69: /** jpayne@69: * Enum for the kinds of checks that USpoofChecker can perform. jpayne@69: * These enum values are used both to select the set of checks that jpayne@69: * will be performed, and to report results from the check function. jpayne@69: * jpayne@69: * @stable ICU 4.2 jpayne@69: */ jpayne@69: typedef enum USpoofChecks { jpayne@69: /** jpayne@69: * When performing the two-string {@link uspoof_areConfusable} test, this flag in the return value indicates jpayne@69: * that the two strings are visually confusable and that they are from the same script, according to UTS 39 section jpayne@69: * 4. jpayne@69: * jpayne@69: * @see uspoof_areConfusable jpayne@69: * @stable ICU 4.2 jpayne@69: */ jpayne@69: USPOOF_SINGLE_SCRIPT_CONFUSABLE = 1, jpayne@69: jpayne@69: /** jpayne@69: * When performing the two-string {@link uspoof_areConfusable} test, this flag in the return value indicates jpayne@69: * that the two strings are visually confusable and that they are not from the same script, according to UTS jpayne@69: * 39 section 4. jpayne@69: * jpayne@69: * @see uspoof_areConfusable jpayne@69: * @stable ICU 4.2 jpayne@69: */ jpayne@69: USPOOF_MIXED_SCRIPT_CONFUSABLE = 2, jpayne@69: jpayne@69: /** jpayne@69: * When performing the two-string {@link uspoof_areConfusable} test, this flag in the return value indicates jpayne@69: * that the two strings are visually confusable and that they are not from the same script but both of them are jpayne@69: * single-script strings, according to UTS 39 section 4. jpayne@69: * jpayne@69: * @see uspoof_areConfusable jpayne@69: * @stable ICU 4.2 jpayne@69: */ jpayne@69: USPOOF_WHOLE_SCRIPT_CONFUSABLE = 4, jpayne@69: jpayne@69: /** jpayne@69: * Enable this flag in {@link uspoof_setChecks} to turn on all types of confusables. You may set jpayne@69: * the checks to some subset of SINGLE_SCRIPT_CONFUSABLE, MIXED_SCRIPT_CONFUSABLE, or WHOLE_SCRIPT_CONFUSABLE to jpayne@69: * make {@link uspoof_areConfusable} return only those types of confusables. jpayne@69: * jpayne@69: * @see uspoof_areConfusable jpayne@69: * @see uspoof_getSkeleton jpayne@69: * @stable ICU 58 jpayne@69: */ jpayne@69: USPOOF_CONFUSABLE = USPOOF_SINGLE_SCRIPT_CONFUSABLE | USPOOF_MIXED_SCRIPT_CONFUSABLE | USPOOF_WHOLE_SCRIPT_CONFUSABLE, jpayne@69: jpayne@69: #ifndef U_HIDE_DEPRECATED_API jpayne@69: /** jpayne@69: * This flag is deprecated and no longer affects the behavior of SpoofChecker. jpayne@69: * jpayne@69: * @deprecated ICU 58 Any case confusable mappings were removed from UTS 39; the corresponding ICU API was deprecated. jpayne@69: */ jpayne@69: USPOOF_ANY_CASE = 8, jpayne@69: #endif /* U_HIDE_DEPRECATED_API */ jpayne@69: jpayne@69: /** jpayne@69: * Check that an identifier is no looser than the specified RestrictionLevel. jpayne@69: * The default if {@link uspoof_setRestrictionLevel} is not called is HIGHLY_RESTRICTIVE. jpayne@69: * jpayne@69: * If USPOOF_AUX_INFO is enabled the actual restriction level of the jpayne@69: * identifier being tested will also be returned by uspoof_check(). jpayne@69: * jpayne@69: * @see URestrictionLevel jpayne@69: * @see uspoof_setRestrictionLevel jpayne@69: * @see USPOOF_AUX_INFO jpayne@69: * jpayne@69: * @stable ICU 51 jpayne@69: */ jpayne@69: USPOOF_RESTRICTION_LEVEL = 16, jpayne@69: jpayne@69: #ifndef U_HIDE_DEPRECATED_API jpayne@69: /** Check that an identifier contains only characters from a jpayne@69: * single script (plus chars from the common and inherited scripts.) jpayne@69: * Applies to checks of a single identifier check only. jpayne@69: * @deprecated ICU 51 Use RESTRICTION_LEVEL instead. jpayne@69: */ jpayne@69: USPOOF_SINGLE_SCRIPT = USPOOF_RESTRICTION_LEVEL, jpayne@69: #endif /* U_HIDE_DEPRECATED_API */ jpayne@69: jpayne@69: /** Check an identifier for the presence of invisible characters, jpayne@69: * such as zero-width spaces, or character sequences that are jpayne@69: * likely not to display, such as multiple occurrences of the same jpayne@69: * non-spacing mark. This check does not test the input string as a whole jpayne@69: * for conformance to any particular syntax for identifiers. jpayne@69: */ jpayne@69: USPOOF_INVISIBLE = 32, jpayne@69: jpayne@69: /** Check that an identifier contains only characters from a specified set jpayne@69: * of acceptable characters. See {@link uspoof_setAllowedChars} and jpayne@69: * {@link uspoof_setAllowedLocales}. Note that a string that fails this check jpayne@69: * will also fail the {@link USPOOF_RESTRICTION_LEVEL} check. jpayne@69: */ jpayne@69: USPOOF_CHAR_LIMIT = 64, jpayne@69: jpayne@69: /** jpayne@69: * Check that an identifier does not mix numbers from different numbering systems. jpayne@69: * For more information, see UTS 39 section 5.3. jpayne@69: * jpayne@69: * @stable ICU 51 jpayne@69: */ jpayne@69: USPOOF_MIXED_NUMBERS = 128, jpayne@69: jpayne@69: /** jpayne@69: * Check that an identifier does not have a combining character following a character in which that jpayne@69: * combining character would be hidden; for example 'i' followed by a U+0307 combining dot. jpayne@69: * jpayne@69: * More specifically, the following characters are forbidden from preceding a U+0307: jpayne@69: * jpayne@69: * In addition, combining characters are allowed between the above characters and U+0307 except those jpayne@69: * with combining class 0 or combining class "Above" (230, same class as U+0307). jpayne@69: * jpayne@69: * This list and the number of combing characters considered by this check may grow over time. jpayne@69: * jpayne@69: * @stable ICU 62 jpayne@69: */ jpayne@69: USPOOF_HIDDEN_OVERLAY = 256, jpayne@69: jpayne@69: /** jpayne@69: * Enable all spoof checks. jpayne@69: * jpayne@69: * @stable ICU 4.6 jpayne@69: */ jpayne@69: USPOOF_ALL_CHECKS = 0xFFFF, jpayne@69: jpayne@69: /** jpayne@69: * Enable the return of auxillary (non-error) information in the jpayne@69: * upper bits of the check results value. jpayne@69: * jpayne@69: * If this "check" is not enabled, the results of {@link uspoof_check} will be jpayne@69: * zero when an identifier passes all of the enabled checks. jpayne@69: * jpayne@69: * If this "check" is enabled, (uspoof_check() & {@link USPOOF_ALL_CHECKS}) will jpayne@69: * be zero when an identifier passes all checks. jpayne@69: * jpayne@69: * @stable ICU 51 jpayne@69: */ jpayne@69: USPOOF_AUX_INFO = 0x40000000 jpayne@69: jpayne@69: } USpoofChecks; jpayne@69: jpayne@69: jpayne@69: /** jpayne@69: * Constants from UAX #39 for use in {@link uspoof_setRestrictionLevel}, and jpayne@69: * for returned identifier restriction levels in check results. jpayne@69: * jpayne@69: * @stable ICU 51 jpayne@69: * jpayne@69: * @see uspoof_setRestrictionLevel jpayne@69: * @see uspoof_check jpayne@69: */ jpayne@69: typedef enum URestrictionLevel { jpayne@69: /** jpayne@69: * All characters in the string are in the identifier profile and all characters in the string are in the jpayne@69: * ASCII range. jpayne@69: * jpayne@69: * @stable ICU 51 jpayne@69: */ jpayne@69: USPOOF_ASCII = 0x10000000, jpayne@69: /** jpayne@69: * The string classifies as ASCII-Only, or all characters in the string are in the identifier profile and jpayne@69: * the string is single-script, according to the definition in UTS 39 section 5.1. jpayne@69: * jpayne@69: * @stable ICU 53 jpayne@69: */ jpayne@69: USPOOF_SINGLE_SCRIPT_RESTRICTIVE = 0x20000000, jpayne@69: /** jpayne@69: * The string classifies as Single Script, or all characters in the string are in the identifier profile and jpayne@69: * the string is covered by any of the following sets of scripts, according to the definition in UTS 39 jpayne@69: * section 5.1: jpayne@69: * jpayne@69: * This is the default restriction in ICU. jpayne@69: * jpayne@69: * @stable ICU 51 jpayne@69: */ jpayne@69: USPOOF_HIGHLY_RESTRICTIVE = 0x30000000, jpayne@69: /** jpayne@69: * The string classifies as Highly Restrictive, or all characters in the string are in the identifier profile jpayne@69: * and the string is covered by Latin and any one other Recommended or Aspirational script, except Cyrillic, jpayne@69: * Greek, and Cherokee. jpayne@69: * jpayne@69: * @stable ICU 51 jpayne@69: */ jpayne@69: USPOOF_MODERATELY_RESTRICTIVE = 0x40000000, jpayne@69: /** jpayne@69: * All characters in the string are in the identifier profile. Allow arbitrary mixtures of scripts. jpayne@69: * jpayne@69: * @stable ICU 51 jpayne@69: */ jpayne@69: USPOOF_MINIMALLY_RESTRICTIVE = 0x50000000, jpayne@69: /** jpayne@69: * Any valid identifiers, including characters outside of the Identifier Profile. jpayne@69: * jpayne@69: * @stable ICU 51 jpayne@69: */ jpayne@69: USPOOF_UNRESTRICTIVE = 0x60000000, jpayne@69: /** jpayne@69: * Mask for selecting the Restriction Level bits from the return value of {@link uspoof_check}. jpayne@69: * jpayne@69: * @stable ICU 53 jpayne@69: */ jpayne@69: USPOOF_RESTRICTION_LEVEL_MASK = 0x7F000000, jpayne@69: #ifndef U_HIDE_INTERNAL_API jpayne@69: /** jpayne@69: * An undefined restriction level. jpayne@69: * @internal jpayne@69: */ jpayne@69: USPOOF_UNDEFINED_RESTRICTIVE = -1 jpayne@69: #endif /* U_HIDE_INTERNAL_API */ jpayne@69: } URestrictionLevel; jpayne@69: jpayne@69: /** jpayne@69: * Create a Unicode Spoof Checker, configured to perform all jpayne@69: * checks except for USPOOF_LOCALE_LIMIT and USPOOF_CHAR_LIMIT. jpayne@69: * Note that additional checks may be added in the future, jpayne@69: * resulting in the changes to the default checking behavior. jpayne@69: * jpayne@69: * @param status The error code, set if this function encounters a problem. jpayne@69: * @return the newly created Spoof Checker jpayne@69: * @stable ICU 4.2 jpayne@69: */ jpayne@69: U_STABLE USpoofChecker * U_EXPORT2 jpayne@69: uspoof_open(UErrorCode *status); jpayne@69: jpayne@69: jpayne@69: /** jpayne@69: * Open a Spoof checker from its serialized form, stored in 32-bit-aligned memory. jpayne@69: * Inverse of uspoof_serialize(). jpayne@69: * The memory containing the serialized data must remain valid and unchanged jpayne@69: * as long as the spoof checker, or any cloned copies of the spoof checker, jpayne@69: * are in use. Ownership of the memory remains with the caller. jpayne@69: * The spoof checker (and any clones) must be closed prior to deleting the jpayne@69: * serialized data. jpayne@69: * jpayne@69: * @param data a pointer to 32-bit-aligned memory containing the serialized form of spoof data jpayne@69: * @param length the number of bytes available at data; jpayne@69: * can be more than necessary jpayne@69: * @param pActualLength receives the actual number of bytes at data taken up by the data; jpayne@69: * can be NULL jpayne@69: * @param pErrorCode ICU error code jpayne@69: * @return the spoof checker. jpayne@69: * jpayne@69: * @see uspoof_open jpayne@69: * @see uspoof_serialize jpayne@69: * @stable ICU 4.2 jpayne@69: */ jpayne@69: U_STABLE USpoofChecker * U_EXPORT2 jpayne@69: uspoof_openFromSerialized(const void *data, int32_t length, int32_t *pActualLength, jpayne@69: UErrorCode *pErrorCode); jpayne@69: jpayne@69: /** jpayne@69: * Open a Spoof Checker from the source form of the spoof data. jpayne@69: * The input corresponds to the Unicode data file confusables.txt jpayne@69: * as described in Unicode UAX #39. The syntax of the source data jpayne@69: * is as described in UAX #39 for this file, and the content of jpayne@69: * this file is acceptable input. jpayne@69: * jpayne@69: * The character encoding of the (char *) input text is UTF-8. jpayne@69: * jpayne@69: * @param confusables a pointer to the confusable characters definitions, jpayne@69: * as found in file confusables.txt from unicode.org. jpayne@69: * @param confusablesLen The length of the confusables text, or -1 if the jpayne@69: * input string is zero terminated. jpayne@69: * @param confusablesWholeScript jpayne@69: * Deprecated in ICU 58. No longer used. jpayne@69: * @param confusablesWholeScriptLen jpayne@69: * Deprecated in ICU 58. No longer used. jpayne@69: * @param errType In the event of an error in the input, indicates jpayne@69: * which of the input files contains the error. jpayne@69: * The value is one of USPOOF_SINGLE_SCRIPT_CONFUSABLE or jpayne@69: * USPOOF_WHOLE_SCRIPT_CONFUSABLE, or jpayne@69: * zero if no errors are found. jpayne@69: * @param pe In the event of an error in the input, receives the position jpayne@69: * in the input text (line, offset) of the error. jpayne@69: * @param status an in/out ICU UErrorCode. Among the possible errors is jpayne@69: * U_PARSE_ERROR, which is used to report syntax errors jpayne@69: * in the input. jpayne@69: * @return A spoof checker that uses the rules from the input files. jpayne@69: * @stable ICU 4.2 jpayne@69: */ jpayne@69: U_STABLE USpoofChecker * U_EXPORT2 jpayne@69: uspoof_openFromSource(const char *confusables, int32_t confusablesLen, jpayne@69: const char *confusablesWholeScript, int32_t confusablesWholeScriptLen, jpayne@69: int32_t *errType, UParseError *pe, UErrorCode *status); jpayne@69: jpayne@69: jpayne@69: /** jpayne@69: * Close a Spoof Checker, freeing any memory that was being held by jpayne@69: * its implementation. jpayne@69: * @stable ICU 4.2 jpayne@69: */ jpayne@69: U_STABLE void U_EXPORT2 jpayne@69: uspoof_close(USpoofChecker *sc); jpayne@69: jpayne@69: /** jpayne@69: * Clone a Spoof Checker. The clone will be set to perform the same checks jpayne@69: * as the original source. jpayne@69: * jpayne@69: * @param sc The source USpoofChecker jpayne@69: * @param status The error code, set if this function encounters a problem. jpayne@69: * @return jpayne@69: * @stable ICU 4.2 jpayne@69: */ jpayne@69: U_STABLE USpoofChecker * U_EXPORT2 jpayne@69: uspoof_clone(const USpoofChecker *sc, UErrorCode *status); jpayne@69: jpayne@69: jpayne@69: /** jpayne@69: * Specify the bitmask of checks that will be performed by {@link uspoof_check}. Calling this method jpayne@69: * overwrites any checks that may have already been enabled. By default, all checks are enabled. jpayne@69: * jpayne@69: * To enable specific checks and disable all others, the "whitelisted" checks should be ORed together. For jpayne@69: * example, to fail strings containing characters outside of the set specified by {@link uspoof_setAllowedChars} and jpayne@69: * also strings that contain digits from mixed numbering systems: jpayne@69: * jpayne@69: * 
jpayne@69:  * {@code
jpayne@69:  * uspoof_setChecks(USPOOF_CHAR_LIMIT | USPOOF_MIXED_NUMBERS);
jpayne@69:  * }
jpayne@69:  *
jpayne@69: * jpayne@69: * To disable specific checks and enable all others, the "blacklisted" checks should be ANDed away from jpayne@69: * ALL_CHECKS. For example, if you are not planning to use the {@link uspoof_areConfusable} functionality, jpayne@69: * it is good practice to disable the CONFUSABLE check: jpayne@69: * jpayne@69: * 
jpayne@69:  * {@code
jpayne@69:  * uspoof_setChecks(USPOOF_ALL_CHECKS & ~USPOOF_CONFUSABLE);
jpayne@69:  * }
jpayne@69:  *
jpayne@69: * jpayne@69: * Note that methods such as {@link uspoof_setAllowedChars}, {@link uspoof_setAllowedLocales}, and jpayne@69: * {@link uspoof_setRestrictionLevel} will enable certain checks when called. Those methods will OR the check they jpayne@69: * enable onto the existing bitmask specified by this method. For more details, see the documentation of those jpayne@69: * methods. jpayne@69: * jpayne@69: * @param sc The USpoofChecker jpayne@69: * @param checks The set of checks that this spoof checker will perform. jpayne@69: * The value is a bit set, obtained by OR-ing together jpayne@69: * values from enum USpoofChecks. jpayne@69: * @param status The error code, set if this function encounters a problem. jpayne@69: * @stable ICU 4.2 jpayne@69: * jpayne@69: */ jpayne@69: U_STABLE void U_EXPORT2 jpayne@69: uspoof_setChecks(USpoofChecker *sc, int32_t checks, UErrorCode *status); jpayne@69: jpayne@69: /** jpayne@69: * Get the set of checks that this Spoof Checker has been configured to perform. jpayne@69: * jpayne@69: * @param sc The USpoofChecker jpayne@69: * @param status The error code, set if this function encounters a problem. jpayne@69: * @return The set of checks that this spoof checker will perform. jpayne@69: * The value is a bit set, obtained by OR-ing together jpayne@69: * values from enum USpoofChecks. jpayne@69: * @stable ICU 4.2 jpayne@69: * jpayne@69: */ jpayne@69: U_STABLE int32_t U_EXPORT2 jpayne@69: uspoof_getChecks(const USpoofChecker *sc, UErrorCode *status); jpayne@69: jpayne@69: /** jpayne@69: * Set the loosest restriction level allowed for strings. The default if this is not called is jpayne@69: * {@link USPOOF_HIGHLY_RESTRICTIVE}. Calling this method enables the {@link USPOOF_RESTRICTION_LEVEL} and jpayne@69: * {@link USPOOF_MIXED_NUMBERS} checks, corresponding to Sections 5.1 and 5.2 of UTS 39. To customize which checks are jpayne@69: * to be performed by {@link uspoof_check}, see {@link uspoof_setChecks}. jpayne@69: * jpayne@69: * @param sc The USpoofChecker jpayne@69: * @param restrictionLevel The loosest restriction level allowed. jpayne@69: * @see URestrictionLevel jpayne@69: * @stable ICU 51 jpayne@69: */ jpayne@69: U_STABLE void U_EXPORT2 jpayne@69: uspoof_setRestrictionLevel(USpoofChecker *sc, URestrictionLevel restrictionLevel); jpayne@69: jpayne@69: jpayne@69: /** jpayne@69: * Get the Restriction Level that will be tested if the checks include {@link USPOOF_RESTRICTION_LEVEL}. jpayne@69: * jpayne@69: * @return The restriction level jpayne@69: * @see URestrictionLevel jpayne@69: * @stable ICU 51 jpayne@69: */ jpayne@69: U_STABLE URestrictionLevel U_EXPORT2 jpayne@69: uspoof_getRestrictionLevel(const USpoofChecker *sc); jpayne@69: jpayne@69: /** jpayne@69: * Limit characters that are acceptable in identifiers being checked to those jpayne@69: * normally used with the languages associated with the specified locales. jpayne@69: * Any previously specified list of locales is replaced by the new settings. jpayne@69: * jpayne@69: * A set of languages is determined from the locale(s), and jpayne@69: * from those a set of acceptable Unicode scripts is determined. jpayne@69: * Characters from this set of scripts, along with characters from jpayne@69: * the "common" and "inherited" Unicode Script categories jpayne@69: * will be permitted. jpayne@69: * jpayne@69: * Supplying an empty string removes all restrictions; jpayne@69: * characters from any script will be allowed. jpayne@69: * jpayne@69: * The {@link USPOOF_CHAR_LIMIT} test is automatically enabled for this jpayne@69: * USpoofChecker when calling this function with a non-empty list jpayne@69: * of locales. jpayne@69: * jpayne@69: * The Unicode Set of characters that will be allowed is accessible jpayne@69: * via the uspoof_getAllowedChars() function. uspoof_setAllowedLocales() jpayne@69: * will replace any previously applied set of allowed characters. jpayne@69: * jpayne@69: * Adjustments, such as additions or deletions of certain classes of characters, jpayne@69: * can be made to the result of uspoof_setAllowedLocales() by jpayne@69: * fetching the resulting set with uspoof_getAllowedChars(), jpayne@69: * manipulating it with the Unicode Set API, then resetting the jpayne@69: * spoof detectors limits with uspoof_setAllowedChars(). jpayne@69: * jpayne@69: * @param sc The USpoofChecker jpayne@69: * @param localesList A list list of locales, from which the language jpayne@69: * and associated script are extracted. The locales jpayne@69: * are comma-separated if there is more than one. jpayne@69: * White space may not appear within an individual locale, jpayne@69: * but is ignored otherwise. jpayne@69: * The locales are syntactically like those from the jpayne@69: * HTTP Accept-Language header. jpayne@69: * If the localesList is empty, no restrictions will be placed on jpayne@69: * the allowed characters. jpayne@69: * jpayne@69: * @param status The error code, set if this function encounters a problem. jpayne@69: * @stable ICU 4.2 jpayne@69: */ jpayne@69: U_STABLE void U_EXPORT2 jpayne@69: uspoof_setAllowedLocales(USpoofChecker *sc, const char *localesList, UErrorCode *status); jpayne@69: jpayne@69: /** jpayne@69: * Get a list of locales for the scripts that are acceptable in strings jpayne@69: * to be checked. If no limitations on scripts have been specified, jpayne@69: * an empty string will be returned. jpayne@69: * jpayne@69: * uspoof_setAllowedChars() will reset the list of allowed to be empty. jpayne@69: * jpayne@69: * The format of the returned list is the same as that supplied to jpayne@69: * uspoof_setAllowedLocales(), but returned list may not be identical jpayne@69: * to the originally specified string; the string may be reformatted, jpayne@69: * and information other than languages from jpayne@69: * the originally specified locales may be omitted. jpayne@69: * jpayne@69: * @param sc The USpoofChecker jpayne@69: * @param status The error code, set if this function encounters a problem. jpayne@69: * @return A string containing a list of locales corresponding jpayne@69: * to the acceptable scripts, formatted like an jpayne@69: * HTTP Accept Language value. jpayne@69: * jpayne@69: * @stable ICU 4.2 jpayne@69: */ jpayne@69: U_STABLE const char * U_EXPORT2 jpayne@69: uspoof_getAllowedLocales(USpoofChecker *sc, UErrorCode *status); jpayne@69: jpayne@69: jpayne@69: /** jpayne@69: * Limit the acceptable characters to those specified by a Unicode Set. jpayne@69: * Any previously specified character limit is jpayne@69: * is replaced by the new settings. This includes limits on jpayne@69: * characters that were set with the uspoof_setAllowedLocales() function. jpayne@69: * jpayne@69: * The USPOOF_CHAR_LIMIT test is automatically enabled for this jpayne@69: * USpoofChecker by this function. jpayne@69: * jpayne@69: * @param sc The USpoofChecker jpayne@69: * @param chars A Unicode Set containing the list of jpayne@69: * characters that are permitted. Ownership of the set jpayne@69: * remains with the caller. The incoming set is cloned by jpayne@69: * this function, so there are no restrictions on modifying jpayne@69: * or deleting the USet after calling this function. jpayne@69: * @param status The error code, set if this function encounters a problem. jpayne@69: * @stable ICU 4.2 jpayne@69: */ jpayne@69: U_STABLE void U_EXPORT2 jpayne@69: uspoof_setAllowedChars(USpoofChecker *sc, const USet *chars, UErrorCode *status); jpayne@69: jpayne@69: jpayne@69: /** jpayne@69: * Get a USet for the characters permitted in an identifier. jpayne@69: * This corresponds to the limits imposed by the Set Allowed Characters jpayne@69: * functions. Limitations imposed by other checks will not be jpayne@69: * reflected in the set returned by this function. jpayne@69: * jpayne@69: * The returned set will be frozen, meaning that it cannot be modified jpayne@69: * by the caller. jpayne@69: * jpayne@69: * Ownership of the returned set remains with the Spoof Detector. The jpayne@69: * returned set will become invalid if the spoof detector is closed, jpayne@69: * or if a new set of allowed characters is specified. jpayne@69: * jpayne@69: * jpayne@69: * @param sc The USpoofChecker jpayne@69: * @param status The error code, set if this function encounters a problem. jpayne@69: * @return A USet containing the characters that are permitted by jpayne@69: * the USPOOF_CHAR_LIMIT test. jpayne@69: * @stable ICU 4.2 jpayne@69: */ jpayne@69: U_STABLE const USet * U_EXPORT2 jpayne@69: uspoof_getAllowedChars(const USpoofChecker *sc, UErrorCode *status); jpayne@69: jpayne@69: jpayne@69: /** jpayne@69: * Check the specified string for possible security issues. jpayne@69: * The text to be checked will typically be an identifier of some sort. jpayne@69: * The set of checks to be performed is specified with uspoof_setChecks(). jpayne@69: * jpayne@69: * \note jpayne@69: * Consider using the newer API, {@link uspoof_check2}, instead. jpayne@69: * The newer API exposes additional information from the check procedure jpayne@69: * and is otherwise identical to this method. jpayne@69: * jpayne@69: * @param sc The USpoofChecker jpayne@69: * @param id The identifier to be checked for possible security issues, jpayne@69: * in UTF-16 format. jpayne@69: * @param length the length of the string to be checked, expressed in jpayne@69: * 16 bit UTF-16 code units, or -1 if the string is jpayne@69: * zero terminated. jpayne@69: * @param position Deprecated in ICU 51. Always returns zero. jpayne@69: * Originally, an out parameter for the index of the first jpayne@69: * string position that failed a check. jpayne@69: * This parameter may be NULL. jpayne@69: * @param status The error code, set if an error occurred while attempting to jpayne@69: * perform the check. jpayne@69: * Spoofing or security issues detected with the input string are jpayne@69: * not reported here, but through the function's return value. jpayne@69: * @return An integer value with bits set for any potential security jpayne@69: * or spoofing issues detected. The bits are defined by jpayne@69: * enum USpoofChecks. (returned_value & USPOOF_ALL_CHECKS) jpayne@69: * will be zero if the input string passes all of the jpayne@69: * enabled checks. jpayne@69: * @see uspoof_check2 jpayne@69: * @stable ICU 4.2 jpayne@69: */ jpayne@69: U_STABLE int32_t U_EXPORT2 jpayne@69: uspoof_check(const USpoofChecker *sc, jpayne@69: const UChar *id, int32_t length, jpayne@69: int32_t *position, jpayne@69: UErrorCode *status); jpayne@69: jpayne@69: jpayne@69: /** jpayne@69: * Check the specified string for possible security issues. jpayne@69: * The text to be checked will typically be an identifier of some sort. jpayne@69: * The set of checks to be performed is specified with uspoof_setChecks(). jpayne@69: * jpayne@69: * \note jpayne@69: * Consider using the newer API, {@link uspoof_check2UTF8}, instead. jpayne@69: * The newer API exposes additional information from the check procedure jpayne@69: * and is otherwise identical to this method. jpayne@69: * jpayne@69: * @param sc The USpoofChecker jpayne@69: * @param id A identifier to be checked for possible security issues, in UTF8 format. jpayne@69: * @param length the length of the string to be checked, or -1 if the string is jpayne@69: * zero terminated. jpayne@69: * @param position Deprecated in ICU 51. Always returns zero. jpayne@69: * Originally, an out parameter for the index of the first jpayne@69: * string position that failed a check. jpayne@69: * This parameter may be NULL. jpayne@69: * @param status The error code, set if an error occurred while attempting to jpayne@69: * perform the check. jpayne@69: * Spoofing or security issues detected with the input string are jpayne@69: * not reported here, but through the function's return value. jpayne@69: * If the input contains invalid UTF-8 sequences, jpayne@69: * a status of U_INVALID_CHAR_FOUND will be returned. jpayne@69: * @return An integer value with bits set for any potential security jpayne@69: * or spoofing issues detected. The bits are defined by jpayne@69: * enum USpoofChecks. (returned_value & USPOOF_ALL_CHECKS) jpayne@69: * will be zero if the input string passes all of the jpayne@69: * enabled checks. jpayne@69: * @see uspoof_check2UTF8 jpayne@69: * @stable ICU 4.2 jpayne@69: */ jpayne@69: U_STABLE int32_t U_EXPORT2 jpayne@69: uspoof_checkUTF8(const USpoofChecker *sc, jpayne@69: const char *id, int32_t length, jpayne@69: int32_t *position, jpayne@69: UErrorCode *status); jpayne@69: jpayne@69: jpayne@69: /** jpayne@69: * Check the specified string for possible security issues. jpayne@69: * The text to be checked will typically be an identifier of some sort. jpayne@69: * The set of checks to be performed is specified with uspoof_setChecks(). jpayne@69: * jpayne@69: * @param sc The USpoofChecker jpayne@69: * @param id The identifier to be checked for possible security issues, jpayne@69: * in UTF-16 format. jpayne@69: * @param length the length of the string to be checked, or -1 if the string is jpayne@69: * zero terminated. jpayne@69: * @param checkResult An instance of USpoofCheckResult to be filled with jpayne@69: * details about the identifier. Can be NULL. jpayne@69: * @param status The error code, set if an error occurred while attempting to jpayne@69: * perform the check. jpayne@69: * Spoofing or security issues detected with the input string are jpayne@69: * not reported here, but through the function's return value. jpayne@69: * @return An integer value with bits set for any potential security jpayne@69: * or spoofing issues detected. The bits are defined by jpayne@69: * enum USpoofChecks. (returned_value & USPOOF_ALL_CHECKS) jpayne@69: * will be zero if the input string passes all of the jpayne@69: * enabled checks. Any information in this bitmask will be jpayne@69: * consistent with the information saved in the optional jpayne@69: * checkResult parameter. jpayne@69: * @see uspoof_openCheckResult jpayne@69: * @see uspoof_check2UTF8 jpayne@69: * @see uspoof_check2UnicodeString jpayne@69: * @stable ICU 58 jpayne@69: */ jpayne@69: U_STABLE int32_t U_EXPORT2 jpayne@69: uspoof_check2(const USpoofChecker *sc, jpayne@69: const UChar* id, int32_t length, jpayne@69: USpoofCheckResult* checkResult, jpayne@69: UErrorCode *status); jpayne@69: jpayne@69: /** jpayne@69: * Check the specified string for possible security issues. jpayne@69: * The text to be checked will typically be an identifier of some sort. jpayne@69: * The set of checks to be performed is specified with uspoof_setChecks(). jpayne@69: * jpayne@69: * This version of {@link uspoof_check} accepts a USpoofCheckResult, which jpayne@69: * returns additional information about the identifier. For more jpayne@69: * information, see {@link uspoof_openCheckResult}. jpayne@69: * jpayne@69: * @param sc The USpoofChecker jpayne@69: * @param id A identifier to be checked for possible security issues, in UTF8 format. jpayne@69: * @param length the length of the string to be checked, or -1 if the string is jpayne@69: * zero terminated. jpayne@69: * @param checkResult An instance of USpoofCheckResult to be filled with jpayne@69: * details about the identifier. Can be NULL. jpayne@69: * @param status The error code, set if an error occurred while attempting to jpayne@69: * perform the check. jpayne@69: * Spoofing or security issues detected with the input string are jpayne@69: * not reported here, but through the function's return value. jpayne@69: * @return An integer value with bits set for any potential security jpayne@69: * or spoofing issues detected. The bits are defined by jpayne@69: * enum USpoofChecks. (returned_value & USPOOF_ALL_CHECKS) jpayne@69: * will be zero if the input string passes all of the jpayne@69: * enabled checks. Any information in this bitmask will be jpayne@69: * consistent with the information saved in the optional jpayne@69: * checkResult parameter. jpayne@69: * @see uspoof_openCheckResult jpayne@69: * @see uspoof_check2 jpayne@69: * @see uspoof_check2UnicodeString jpayne@69: * @stable ICU 58 jpayne@69: */ jpayne@69: U_STABLE int32_t U_EXPORT2 jpayne@69: uspoof_check2UTF8(const USpoofChecker *sc, jpayne@69: const char *id, int32_t length, jpayne@69: USpoofCheckResult* checkResult, jpayne@69: UErrorCode *status); jpayne@69: jpayne@69: /** jpayne@69: * Create a USpoofCheckResult, used by the {@link uspoof_check2} class of functions to return jpayne@69: * information about the identifier. Information includes: jpayne@69: * jpayne@69: * The data held in a USpoofCheckResult is cleared whenever it is passed into a new call jpayne@69: * of {@link uspoof_check2}. jpayne@69: * jpayne@69: * @param status The error code, set if this function encounters a problem. jpayne@69: * @return the newly created USpoofCheckResult jpayne@69: * @see uspoof_check2 jpayne@69: * @see uspoof_check2UTF8 jpayne@69: * @see uspoof_check2UnicodeString jpayne@69: * @stable ICU 58 jpayne@69: */ jpayne@69: U_STABLE USpoofCheckResult* U_EXPORT2 jpayne@69: uspoof_openCheckResult(UErrorCode *status); jpayne@69: jpayne@69: /** jpayne@69: * Close a USpoofCheckResult, freeing any memory that was being held by jpayne@69: * its implementation. jpayne@69: * jpayne@69: * @param checkResult The instance of USpoofCheckResult to close jpayne@69: * @stable ICU 58 jpayne@69: */ jpayne@69: U_STABLE void U_EXPORT2 jpayne@69: uspoof_closeCheckResult(USpoofCheckResult *checkResult); jpayne@69: jpayne@69: /** jpayne@69: * Indicates which of the spoof check(s) have failed. The value is a bitwise OR of the constants for the tests jpayne@69: * in question: USPOOF_RESTRICTION_LEVEL, USPOOF_CHAR_LIMIT, and so on. jpayne@69: * jpayne@69: * @param checkResult The instance of USpoofCheckResult created by {@link uspoof_openCheckResult} jpayne@69: * @param status The error code, set if an error occurred. jpayne@69: * @return An integer value with bits set for any potential security jpayne@69: * or spoofing issues detected. The bits are defined by jpayne@69: * enum USpoofChecks. (returned_value & USPOOF_ALL_CHECKS) jpayne@69: * will be zero if the input string passes all of the jpayne@69: * enabled checks. jpayne@69: * @see uspoof_setChecks jpayne@69: * @stable ICU 58 jpayne@69: */ jpayne@69: U_STABLE int32_t U_EXPORT2 jpayne@69: uspoof_getCheckResultChecks(const USpoofCheckResult *checkResult, UErrorCode *status); jpayne@69: jpayne@69: /** jpayne@69: * Gets the restriction level that the text meets, if the USPOOF_RESTRICTION_LEVEL check jpayne@69: * was enabled; otherwise, undefined. jpayne@69: * jpayne@69: * @param checkResult The instance of USpoofCheckResult created by {@link uspoof_openCheckResult} jpayne@69: * @param status The error code, set if an error occurred. jpayne@69: * @return The restriction level contained in the USpoofCheckResult jpayne@69: * @see uspoof_setRestrictionLevel jpayne@69: * @stable ICU 58 jpayne@69: */ jpayne@69: U_STABLE URestrictionLevel U_EXPORT2 jpayne@69: uspoof_getCheckResultRestrictionLevel(const USpoofCheckResult *checkResult, UErrorCode *status); jpayne@69: jpayne@69: /** jpayne@69: * Gets the set of numerics found in the string, if the USPOOF_MIXED_NUMBERS check was enabled; jpayne@69: * otherwise, undefined. The set will contain the zero digit from each decimal number system found jpayne@69: * in the input string. Ownership of the returned USet remains with the USpoofCheckResult. jpayne@69: * The USet will be free'd when {@link uspoof_closeCheckResult} is called. jpayne@69: * jpayne@69: * @param checkResult The instance of USpoofCheckResult created by {@link uspoof_openCheckResult} jpayne@69: * @return The set of numerics contained in the USpoofCheckResult jpayne@69: * @param status The error code, set if an error occurred. jpayne@69: * @stable ICU 58 jpayne@69: */ jpayne@69: U_STABLE const USet* U_EXPORT2 jpayne@69: uspoof_getCheckResultNumerics(const USpoofCheckResult *checkResult, UErrorCode *status); jpayne@69: jpayne@69: jpayne@69: /** jpayne@69: * Check the whether two specified strings are visually confusable. jpayne@69: * jpayne@69: * If the strings are confusable, the return value will be nonzero, as long as jpayne@69: * {@link USPOOF_CONFUSABLE} was enabled in uspoof_setChecks(). jpayne@69: * jpayne@69: * The bits in the return value correspond to flags for each of the classes of jpayne@69: * confusables applicable to the two input strings. According to UTS 39 jpayne@69: * section 4, the possible flags are: jpayne@69: * jpayne@69: * jpayne@69: * jpayne@69: * If one or more of the above flags were not listed in uspoof_setChecks(), this jpayne@69: * function will never report that class of confusable. The check jpayne@69: * {@link USPOOF_CONFUSABLE} enables all three flags. jpayne@69: * jpayne@69: * jpayne@69: * @param sc The USpoofChecker jpayne@69: * @param id1 The first of the two identifiers to be compared for jpayne@69: * confusability. The strings are in UTF-16 format. jpayne@69: * @param length1 the length of the first identifer, expressed in jpayne@69: * 16 bit UTF-16 code units, or -1 if the string is jpayne@69: * nul terminated. jpayne@69: * @param id2 The second of the two identifiers to be compared for jpayne@69: * confusability. The identifiers are in UTF-16 format. jpayne@69: * @param length2 The length of the second identifiers, expressed in jpayne@69: * 16 bit UTF-16 code units, or -1 if the string is jpayne@69: * nul terminated. jpayne@69: * @param status The error code, set if an error occurred while attempting to jpayne@69: * perform the check. jpayne@69: * Confusability of the identifiers is not reported here, jpayne@69: * but through this function's return value. jpayne@69: * @return An integer value with bit(s) set corresponding to jpayne@69: * the type of confusability found, as defined by jpayne@69: * enum USpoofChecks. Zero is returned if the identifiers jpayne@69: * are not confusable. jpayne@69: * jpayne@69: * @stable ICU 4.2 jpayne@69: */ jpayne@69: U_STABLE int32_t U_EXPORT2 jpayne@69: uspoof_areConfusable(const USpoofChecker *sc, jpayne@69: const UChar *id1, int32_t length1, jpayne@69: const UChar *id2, int32_t length2, jpayne@69: UErrorCode *status); jpayne@69: jpayne@69: jpayne@69: jpayne@69: /** jpayne@69: * A version of {@link uspoof_areConfusable} accepting strings in UTF-8 format. jpayne@69: * jpayne@69: * @param sc The USpoofChecker jpayne@69: * @param id1 The first of the two identifiers to be compared for jpayne@69: * confusability. The strings are in UTF-8 format. jpayne@69: * @param length1 the length of the first identifiers, in bytes, or -1 jpayne@69: * if the string is nul terminated. jpayne@69: * @param id2 The second of the two identifiers to be compared for jpayne@69: * confusability. The strings are in UTF-8 format. jpayne@69: * @param length2 The length of the second string in bytes, or -1 jpayne@69: * if the string is nul terminated. jpayne@69: * @param status The error code, set if an error occurred while attempting to jpayne@69: * perform the check. jpayne@69: * Confusability of the strings is not reported here, jpayne@69: * but through this function's return value. jpayne@69: * @return An integer value with bit(s) set corresponding to jpayne@69: * the type of confusability found, as defined by jpayne@69: * enum USpoofChecks. Zero is returned if the strings jpayne@69: * are not confusable. jpayne@69: * jpayne@69: * @stable ICU 4.2 jpayne@69: * jpayne@69: * @see uspoof_areConfusable jpayne@69: */ jpayne@69: U_STABLE int32_t U_EXPORT2 jpayne@69: uspoof_areConfusableUTF8(const USpoofChecker *sc, jpayne@69: const char *id1, int32_t length1, jpayne@69: const char *id2, int32_t length2, jpayne@69: UErrorCode *status); jpayne@69: jpayne@69: jpayne@69: jpayne@69: jpayne@69: /** jpayne@69: * Get the "skeleton" for an identifier. jpayne@69: * Skeletons are a transformation of the input identifier; jpayne@69: * Two identifiers are confusable if their skeletons are identical. jpayne@69: * See Unicode UAX #39 for additional information. jpayne@69: * jpayne@69: * Using skeletons directly makes it possible to quickly check jpayne@69: * whether an identifier is confusable with any of some large jpayne@69: * set of existing identifiers, by creating an efficiently jpayne@69: * searchable collection of the skeletons. jpayne@69: * jpayne@69: * @param sc The USpoofChecker jpayne@69: * @param type Deprecated in ICU 58. You may pass any number. jpayne@69: * Originally, controlled which of the Unicode confusable data jpayne@69: * tables to use. jpayne@69: * @param id The input identifier whose skeleton will be computed. jpayne@69: * @param length The length of the input identifier, expressed in 16 bit jpayne@69: * UTF-16 code units, or -1 if the string is zero terminated. jpayne@69: * @param dest The output buffer, to receive the skeleton string. jpayne@69: * @param destCapacity The length of the output buffer, in 16 bit units. jpayne@69: * The destCapacity may be zero, in which case the function will jpayne@69: * return the actual length of the skeleton. jpayne@69: * @param status The error code, set if an error occurred while attempting to jpayne@69: * perform the check. jpayne@69: * @return The length of the skeleton string. The returned length jpayne@69: * is always that of the complete skeleton, even when the jpayne@69: * supplied buffer is too small (or of zero length) jpayne@69: * jpayne@69: * @stable ICU 4.2 jpayne@69: * @see uspoof_areConfusable jpayne@69: */ jpayne@69: U_STABLE int32_t U_EXPORT2 jpayne@69: uspoof_getSkeleton(const USpoofChecker *sc, jpayne@69: uint32_t type, jpayne@69: const UChar *id, int32_t length, jpayne@69: UChar *dest, int32_t destCapacity, jpayne@69: UErrorCode *status); jpayne@69: jpayne@69: /** jpayne@69: * Get the "skeleton" for an identifier. jpayne@69: * Skeletons are a transformation of the input identifier; jpayne@69: * Two identifiers are confusable if their skeletons are identical. jpayne@69: * See Unicode UAX #39 for additional information. jpayne@69: * jpayne@69: * Using skeletons directly makes it possible to quickly check jpayne@69: * whether an identifier is confusable with any of some large jpayne@69: * set of existing identifiers, by creating an efficiently jpayne@69: * searchable collection of the skeletons. jpayne@69: * jpayne@69: * @param sc The USpoofChecker jpayne@69: * @param type Deprecated in ICU 58. You may pass any number. jpayne@69: * Originally, controlled which of the Unicode confusable data jpayne@69: * tables to use. jpayne@69: * @param id The UTF-8 format identifier whose skeleton will be computed. jpayne@69: * @param length The length of the input string, in bytes, jpayne@69: * or -1 if the string is zero terminated. jpayne@69: * @param dest The output buffer, to receive the skeleton string. jpayne@69: * @param destCapacity The length of the output buffer, in bytes. jpayne@69: * The destCapacity may be zero, in which case the function will jpayne@69: * return the actual length of the skeleton. jpayne@69: * @param status The error code, set if an error occurred while attempting to jpayne@69: * perform the check. Possible Errors include U_INVALID_CHAR_FOUND jpayne@69: * for invalid UTF-8 sequences, and jpayne@69: * U_BUFFER_OVERFLOW_ERROR if the destination buffer is too small jpayne@69: * to hold the complete skeleton. jpayne@69: * @return The length of the skeleton string, in bytes. The returned length jpayne@69: * is always that of the complete skeleton, even when the jpayne@69: * supplied buffer is too small (or of zero length) jpayne@69: * jpayne@69: * @stable ICU 4.2 jpayne@69: */ jpayne@69: U_STABLE int32_t U_EXPORT2 jpayne@69: uspoof_getSkeletonUTF8(const USpoofChecker *sc, jpayne@69: uint32_t type, jpayne@69: const char *id, int32_t length, jpayne@69: char *dest, int32_t destCapacity, jpayne@69: UErrorCode *status); jpayne@69: jpayne@69: /** jpayne@69: * Get the set of Candidate Characters for Inclusion in Identifiers, as defined jpayne@69: * in http://unicode.org/Public/security/latest/xidmodifications.txt jpayne@69: * and documented in http://www.unicode.org/reports/tr39/, Unicode Security Mechanisms. jpayne@69: * jpayne@69: * The returned set is frozen. Ownership of the set remains with the ICU library; it must not jpayne@69: * be deleted by the caller. jpayne@69: * jpayne@69: * @param status The error code, set if a problem occurs while creating the set. jpayne@69: * jpayne@69: * @stable ICU 51 jpayne@69: */ jpayne@69: U_STABLE const USet * U_EXPORT2 jpayne@69: uspoof_getInclusionSet(UErrorCode *status); jpayne@69: jpayne@69: /** jpayne@69: * Get the set of characters from Recommended Scripts for Inclusion in Identifiers, as defined jpayne@69: * in http://unicode.org/Public/security/latest/xidmodifications.txt jpayne@69: * and documented in http://www.unicode.org/reports/tr39/, Unicode Security Mechanisms. jpayne@69: * jpayne@69: * The returned set is frozen. Ownership of the set remains with the ICU library; it must not jpayne@69: * be deleted by the caller. jpayne@69: * jpayne@69: * @param status The error code, set if a problem occurs while creating the set. jpayne@69: * jpayne@69: * @stable ICU 51 jpayne@69: */ jpayne@69: U_STABLE const USet * U_EXPORT2 jpayne@69: uspoof_getRecommendedSet(UErrorCode *status); jpayne@69: jpayne@69: /** jpayne@69: * Serialize the data for a spoof detector into a chunk of memory. jpayne@69: * The flattened spoof detection tables can later be used to efficiently jpayne@69: * instantiate a new Spoof Detector. jpayne@69: * jpayne@69: * The serialized spoof checker includes only the data compiled from the jpayne@69: * Unicode data tables by uspoof_openFromSource(); it does not include jpayne@69: * include any other state or configuration that may have been set. jpayne@69: * jpayne@69: * @param sc the Spoof Detector whose data is to be serialized. jpayne@69: * @param data a pointer to 32-bit-aligned memory to be filled with the data, jpayne@69: * can be NULL if capacity==0 jpayne@69: * @param capacity the number of bytes available at data, jpayne@69: * or 0 for preflighting jpayne@69: * @param status an in/out ICU UErrorCode; possible errors include: jpayne@69: * - U_BUFFER_OVERFLOW_ERROR if the data storage block is too small for serialization jpayne@69: * - U_ILLEGAL_ARGUMENT_ERROR the data or capacity parameters are bad jpayne@69: * @return the number of bytes written or needed for the spoof data jpayne@69: * jpayne@69: * @see utrie2_openFromSerialized() jpayne@69: * @stable ICU 4.2 jpayne@69: */ jpayne@69: U_STABLE int32_t U_EXPORT2 jpayne@69: uspoof_serialize(USpoofChecker *sc, jpayne@69: void *data, int32_t capacity, jpayne@69: UErrorCode *status); jpayne@69: jpayne@69: U_CDECL_END jpayne@69: jpayne@69: #if U_SHOW_CPLUSPLUS_API jpayne@69: jpayne@69: U_NAMESPACE_BEGIN jpayne@69: jpayne@69: /** jpayne@69: * \class LocalUSpoofCheckerPointer jpayne@69: * "Smart pointer" class, closes a USpoofChecker via uspoof_close(). jpayne@69: * For most methods see the LocalPointerBase base class. jpayne@69: * jpayne@69: * @see LocalPointerBase jpayne@69: * @see LocalPointer jpayne@69: * @stable ICU 4.4 jpayne@69: */ jpayne@69: /** jpayne@69: * \cond jpayne@69: * Note: Doxygen is giving a bogus warning on this U_DEFINE_LOCAL_OPEN_POINTER. jpayne@69: * For now, suppress with a Doxygen cond jpayne@69: */ jpayne@69: U_DEFINE_LOCAL_OPEN_POINTER(LocalUSpoofCheckerPointer, USpoofChecker, uspoof_close); jpayne@69: /** \endcond */ jpayne@69: jpayne@69: /** jpayne@69: * \class LocalUSpoofCheckResultPointer jpayne@69: * "Smart pointer" class, closes a USpoofCheckResult via `uspoof_closeCheckResult()`. jpayne@69: * For most methods see the LocalPointerBase base class. jpayne@69: * jpayne@69: * @see LocalPointerBase jpayne@69: * @see LocalPointer jpayne@69: * @stable ICU 58 jpayne@69: */ jpayne@69: jpayne@69: /** jpayne@69: * \cond jpayne@69: * Note: Doxygen is giving a bogus warning on this U_DEFINE_LOCAL_OPEN_POINTER. jpayne@69: * For now, suppress with a Doxygen cond jpayne@69: */ jpayne@69: U_DEFINE_LOCAL_OPEN_POINTER(LocalUSpoofCheckResultPointer, USpoofCheckResult, uspoof_closeCheckResult); jpayne@69: /** \endcond */ jpayne@69: jpayne@69: U_NAMESPACE_END jpayne@69: jpayne@69: /** jpayne@69: * Limit the acceptable characters to those specified by a Unicode Set. jpayne@69: * Any previously specified character limit is jpayne@69: * is replaced by the new settings. This includes limits on jpayne@69: * characters that were set with the uspoof_setAllowedLocales() function. jpayne@69: * jpayne@69: * The USPOOF_CHAR_LIMIT test is automatically enabled for this jpayne@69: * USoofChecker by this function. jpayne@69: * jpayne@69: * @param sc The USpoofChecker jpayne@69: * @param chars A Unicode Set containing the list of jpayne@69: * characters that are permitted. Ownership of the set jpayne@69: * remains with the caller. The incoming set is cloned by jpayne@69: * this function, so there are no restrictions on modifying jpayne@69: * or deleting the UnicodeSet after calling this function. jpayne@69: * @param status The error code, set if this function encounters a problem. jpayne@69: * @stable ICU 4.2 jpayne@69: */ jpayne@69: U_STABLE void U_EXPORT2 jpayne@69: uspoof_setAllowedUnicodeSet(USpoofChecker *sc, const icu::UnicodeSet *chars, UErrorCode *status); jpayne@69: jpayne@69: jpayne@69: /** jpayne@69: * Get a UnicodeSet for the characters permitted in an identifier. jpayne@69: * This corresponds to the limits imposed by the Set Allowed Characters / jpayne@69: * UnicodeSet functions. Limitations imposed by other checks will not be jpayne@69: * reflected in the set returned by this function. jpayne@69: * jpayne@69: * The returned set will be frozen, meaning that it cannot be modified jpayne@69: * by the caller. jpayne@69: * jpayne@69: * Ownership of the returned set remains with the Spoof Detector. The jpayne@69: * returned set will become invalid if the spoof detector is closed, jpayne@69: * or if a new set of allowed characters is specified. jpayne@69: * jpayne@69: * jpayne@69: * @param sc The USpoofChecker jpayne@69: * @param status The error code, set if this function encounters a problem. jpayne@69: * @return A UnicodeSet containing the characters that are permitted by jpayne@69: * the USPOOF_CHAR_LIMIT test. jpayne@69: * @stable ICU 4.2 jpayne@69: */ jpayne@69: U_STABLE const icu::UnicodeSet * U_EXPORT2 jpayne@69: uspoof_getAllowedUnicodeSet(const USpoofChecker *sc, UErrorCode *status); jpayne@69: jpayne@69: /** jpayne@69: * Check the specified string for possible security issues. jpayne@69: * The text to be checked will typically be an identifier of some sort. jpayne@69: * The set of checks to be performed is specified with uspoof_setChecks(). jpayne@69: * jpayne@69: * \note jpayne@69: * Consider using the newer API, {@link uspoof_check2UnicodeString}, instead. jpayne@69: * The newer API exposes additional information from the check procedure jpayne@69: * and is otherwise identical to this method. jpayne@69: * jpayne@69: * @param sc The USpoofChecker jpayne@69: * @param id A identifier to be checked for possible security issues. jpayne@69: * @param position Deprecated in ICU 51. Always returns zero. jpayne@69: * Originally, an out parameter for the index of the first jpayne@69: * string position that failed a check. jpayne@69: * This parameter may be NULL. jpayne@69: * @param status The error code, set if an error occurred while attempting to jpayne@69: * perform the check. jpayne@69: * Spoofing or security issues detected with the input string are jpayne@69: * not reported here, but through the function's return value. jpayne@69: * @return An integer value with bits set for any potential security jpayne@69: * or spoofing issues detected. The bits are defined by jpayne@69: * enum USpoofChecks. (returned_value & USPOOF_ALL_CHECKS) jpayne@69: * will be zero if the input string passes all of the jpayne@69: * enabled checks. jpayne@69: * @see uspoof_check2UnicodeString jpayne@69: * @stable ICU 4.2 jpayne@69: */ jpayne@69: U_STABLE int32_t U_EXPORT2 jpayne@69: uspoof_checkUnicodeString(const USpoofChecker *sc, jpayne@69: const icu::UnicodeString &id, jpayne@69: int32_t *position, jpayne@69: UErrorCode *status); jpayne@69: jpayne@69: /** jpayne@69: * Check the specified string for possible security issues. jpayne@69: * The text to be checked will typically be an identifier of some sort. jpayne@69: * The set of checks to be performed is specified with uspoof_setChecks(). jpayne@69: * jpayne@69: * @param sc The USpoofChecker jpayne@69: * @param id A identifier to be checked for possible security issues. jpayne@69: * @param checkResult An instance of USpoofCheckResult to be filled with jpayne@69: * details about the identifier. Can be NULL. jpayne@69: * @param status The error code, set if an error occurred while attempting to jpayne@69: * perform the check. jpayne@69: * Spoofing or security issues detected with the input string are jpayne@69: * not reported here, but through the function's return value. jpayne@69: * @return An integer value with bits set for any potential security jpayne@69: * or spoofing issues detected. The bits are defined by jpayne@69: * enum USpoofChecks. (returned_value & USPOOF_ALL_CHECKS) jpayne@69: * will be zero if the input string passes all of the jpayne@69: * enabled checks. Any information in this bitmask will be jpayne@69: * consistent with the information saved in the optional jpayne@69: * checkResult parameter. jpayne@69: * @see uspoof_openCheckResult jpayne@69: * @see uspoof_check2 jpayne@69: * @see uspoof_check2UTF8 jpayne@69: * @stable ICU 58 jpayne@69: */ jpayne@69: U_STABLE int32_t U_EXPORT2 jpayne@69: uspoof_check2UnicodeString(const USpoofChecker *sc, jpayne@69: const icu::UnicodeString &id, jpayne@69: USpoofCheckResult* checkResult, jpayne@69: UErrorCode *status); jpayne@69: jpayne@69: /** jpayne@69: * A version of {@link uspoof_areConfusable} accepting UnicodeStrings. jpayne@69: * jpayne@69: * @param sc The USpoofChecker jpayne@69: * @param s1 The first of the two identifiers to be compared for jpayne@69: * confusability. The strings are in UTF-8 format. jpayne@69: * @param s2 The second of the two identifiers to be compared for jpayne@69: * confusability. The strings are in UTF-8 format. jpayne@69: * @param status The error code, set if an error occurred while attempting to jpayne@69: * perform the check. jpayne@69: * Confusability of the identifiers is not reported here, jpayne@69: * but through this function's return value. jpayne@69: * @return An integer value with bit(s) set corresponding to jpayne@69: * the type of confusability found, as defined by jpayne@69: * enum USpoofChecks. Zero is returned if the identifiers jpayne@69: * are not confusable. jpayne@69: * jpayne@69: * @stable ICU 4.2 jpayne@69: * jpayne@69: * @see uspoof_areConfusable jpayne@69: */ jpayne@69: U_STABLE int32_t U_EXPORT2 jpayne@69: uspoof_areConfusableUnicodeString(const USpoofChecker *sc, jpayne@69: const icu::UnicodeString &s1, jpayne@69: const icu::UnicodeString &s2, jpayne@69: UErrorCode *status); jpayne@69: jpayne@69: /** jpayne@69: * Get the "skeleton" for an identifier. jpayne@69: * Skeletons are a transformation of the input identifier; jpayne@69: * Two identifiers are confusable if their skeletons are identical. jpayne@69: * See Unicode UAX #39 for additional information. jpayne@69: * jpayne@69: * Using skeletons directly makes it possible to quickly check jpayne@69: * whether an identifier is confusable with any of some large jpayne@69: * set of existing identifiers, by creating an efficiently jpayne@69: * searchable collection of the skeletons. jpayne@69: * jpayne@69: * @param sc The USpoofChecker. jpayne@69: * @param type Deprecated in ICU 58. You may pass any number. jpayne@69: * Originally, controlled which of the Unicode confusable data jpayne@69: * tables to use. jpayne@69: * @param id The input identifier whose skeleton will be computed. jpayne@69: * @param dest The output identifier, to receive the skeleton string. jpayne@69: * @param status The error code, set if an error occurred while attempting to jpayne@69: * perform the check. jpayne@69: * @return A reference to the destination (skeleton) string. jpayne@69: * jpayne@69: * @stable ICU 4.2 jpayne@69: */ jpayne@69: U_I18N_API icu::UnicodeString & U_EXPORT2 jpayne@69: uspoof_getSkeletonUnicodeString(const USpoofChecker *sc, jpayne@69: uint32_t type, jpayne@69: const icu::UnicodeString &id, jpayne@69: icu::UnicodeString &dest, jpayne@69: UErrorCode *status); jpayne@69: jpayne@69: /** jpayne@69: * Get the set of Candidate Characters for Inclusion in Identifiers, as defined jpayne@69: * in http://unicode.org/Public/security/latest/xidmodifications.txt jpayne@69: * and documented in http://www.unicode.org/reports/tr39/, Unicode Security Mechanisms. jpayne@69: * jpayne@69: * The returned set is frozen. Ownership of the set remains with the ICU library; it must not jpayne@69: * be deleted by the caller. jpayne@69: * jpayne@69: * @param status The error code, set if a problem occurs while creating the set. jpayne@69: * jpayne@69: * @stable ICU 51 jpayne@69: */ jpayne@69: U_STABLE const icu::UnicodeSet * U_EXPORT2 jpayne@69: uspoof_getInclusionUnicodeSet(UErrorCode *status); jpayne@69: jpayne@69: /** jpayne@69: * Get the set of characters from Recommended Scripts for Inclusion in Identifiers, as defined jpayne@69: * in http://unicode.org/Public/security/latest/xidmodifications.txt jpayne@69: * and documented in http://www.unicode.org/reports/tr39/, Unicode Security Mechanisms. jpayne@69: * jpayne@69: * The returned set is frozen. Ownership of the set remains with the ICU library; it must not jpayne@69: * be deleted by the caller. jpayne@69: * jpayne@69: * @param status The error code, set if a problem occurs while creating the set. jpayne@69: * jpayne@69: * @stable ICU 51 jpayne@69: */ jpayne@69: U_STABLE const icu::UnicodeSet * U_EXPORT2 jpayne@69: uspoof_getRecommendedUnicodeSet(UErrorCode *status); jpayne@69: jpayne@69: #endif /* U_SHOW_CPLUSPLUS_API */ jpayne@69: jpayne@69: #endif /* UCONFIG_NO_NORMALIZATION */ jpayne@69: jpayne@69: #endif /* USPOOF_H */