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