Mercurial > repos > rliterman > csp2

annotate CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/include/unicode/uspoof.h @ 69:33d812a61356

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