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