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