SpoofChecker

java.lang.Object
- org.graalvm.shadowed.com.ibm.icu.text.SpoofChecker

```
public class SpoofChecker
extends Object
```
This class, based on Unicode Technical Report #36 and Unicode Technical Standard #39, has two main functions:
1. Checking whether two strings are visually confusable with each other, such as "desparejado" and "ԁеѕрагејаԁо".
2. Checking whether an individual string is likely to be an attempt at confusing the reader (spoof detection), such as "pаypаl" spelled with Cyrillic 'а' characters.
Although originally designed as a method for flagging suspicious identifier strings such as URLs, SpoofChecker has a number of other practical use cases, such as preventing attempts to evade bad-word content filters.
Confusables

The following example shows how to use SpoofChecker to check for confusability between two strings:
```
 
 SpoofChecker sc = new SpoofChecker.Builder().setChecks(SpoofChecker.CONFUSABLE).build();
 int result = sc.areConfusable("desparejado", "ԁеѕрагејаԁо");
 System.out.println(result != 0);  // true
 
 
```
SpoofChecker uses a builder paradigm: options are specified within the context of a lightweight SpoofChecker.Builder object, and upon calling SpoofChecker.Builder.build(), expensive data loading operations are performed, and an immutable SpoofChecker is returned.
The first line of the example creates a SpoofChecker object with confusable-checking enabled; the second line performs the confusability test. For best performance, the instance should be created once (e.g., upon application startup), and the more efficient SpoofChecker.areConfusable(java.lang.String, java.lang.String) method can be used at runtime.
UTS 39 defines two strings to be confusable if they map to the same skeleton. A skeleton is a sequence of families of confusable characters, where each family has a single exemplar character. SpoofChecker.getSkeleton(java.lang.CharSequence) computes the skeleton for a particular string, so the following snippet is equivalent to the example above:
```
 
 SpoofChecker sc = new SpoofChecker.Builder().setChecks(SpoofChecker.CONFUSABLE).build();
 boolean result = sc.getSkeleton("desparejado").equals(sc.getSkeleton("ԁеѕрагејаԁо"));
 System.out.println(result);  // true
 
 
```
If you need to check if a string is confusable with any string in a dictionary of many strings, rather than calling SpoofChecker.areConfusable(java.lang.String, java.lang.String) many times in a loop, SpoofChecker.getSkeleton(java.lang.CharSequence) can be used instead, as shown below:
```
 // Setup:
 String[] DICTIONARY = new String[]{ "lorem", "ipsum" }; // example
 SpoofChecker sc = new SpoofChecker.Builder().setChecks(SpoofChecker.CONFUSABLE).build();
 HashSet<String> skeletons = new HashSet<String>();
 for (String word : DICTIONARY) {
   skeletons.add(sc.getSkeleton(word));
 }

 // Live Check:
 boolean result = skeletons.contains(sc.getSkeleton("1orern"));
 System.out.println(result);  // true
 
```
Note: Since the Unicode confusables mapping table is frequently updated, confusable skeletons are not guaranteed to be the same between ICU releases. We therefore recommend that you always compute confusable skeletons at runtime and do not rely on creating a permanent, or difficult to update, database of skeletons.
Spoof Detection

The following snippet shows a minimal example of using SpoofChecker to perform spoof detection on a string:
```
 SpoofChecker sc = new SpoofChecker.Builder()
     .setAllowedChars(SpoofChecker.RECOMMENDED.cloneAsThawed().addAll(SpoofChecker.INCLUSION))
     .setRestrictionLevel(SpoofChecker.RestrictionLevel.MODERATELY_RESTRICTIVE)
     .setChecks(SpoofChecker.ALL_CHECKS &~ SpoofChecker.CONFUSABLE)
     .build();
 boolean result = sc.failsChecks("pаypаl");  // with Cyrillic 'а' characters
 System.out.println(result);  // true
 
```
As in the case for confusability checking, it is good practice to create one SpoofChecker instance at startup, and call the cheaper SpoofChecker.failsChecks(java.lang.String, org.graalvm.shadowed.com.ibm.icu.text.SpoofChecker.CheckResult) online. In the second line, we specify the set of allowed characters to be those with type RECOMMENDED or INCLUSION, according to the recommendation in UTS 39. In the third line, the CONFUSABLE checks are disabled. It is good practice to disable them if you won't be using the instance to perform confusability checking.
To get more details on why a string failed the checks, use a SpoofChecker.CheckResult:
```
 
 SpoofChecker sc = new SpoofChecker.Builder()
     .setAllowedChars(SpoofChecker.RECOMMENDED.cloneAsThawed().addAll(SpoofChecker.INCLUSION))
     .setRestrictionLevel(SpoofChecker.RestrictionLevel.MODERATELY_RESTRICTIVE)
     .setChecks(SpoofChecker.ALL_CHECKS &~ SpoofChecker.CONFUSABLE)
     .build();
 SpoofChecker.CheckResult checkResult = new SpoofChecker.CheckResult();
 boolean result = sc.failsChecks("pаypаl", checkResult);
 System.out.println(checkResult.checks);  // 16
 
 
```
The return value is a bitmask of the checks that failed. In this case, there was one check that failed: SpoofChecker.RESTRICTION_LEVEL, corresponding to the fifth bit (16). The possible checks are:
- RESTRICTION_LEVEL: flags strings that violate the Restriction Level test as specified in UTS 39; in most cases, this means flagging strings that contain characters from multiple different scripts.
- INVISIBLE: flags strings that contain invisible characters, such as zero-width spaces, or character sequences that are likely not to display, such as multiple occurrences of the same non-spacing mark.
- CHAR_LIMIT: flags strings that contain characters outside of a specified set of acceptable characters. See SpoofChecker.Builder.setAllowedChars(org.graalvm.shadowed.com.ibm.icu.text.UnicodeSet) and SpoofChecker.Builder.setAllowedLocales(java.util.Set<org.graalvm.shadowed.com.ibm.icu.util.ULocale>).
- MIXED_NUMBERS: flags strings that contain digits from multiple different numbering systems.
These checks can be enabled independently of each other. For example, if you were interested in checking for only the INVISIBLE and MIXED_NUMBERS conditions, you could do:
```
 
 SpoofChecker sc = new SpoofChecker.Builder()
     .setChecks(SpoofChecker.INVISIBLE | SpoofChecker.MIXED_NUMBERS)
     .build();
 boolean result = sc.failsChecks("৪8");
 System.out.println(result);  // true
 
 
```
Note: The Restriction Level is the most powerful of the checks. The full logic is documented in UTS 39, but the basic idea is that strings are restricted to contain characters from only a single script, except that most scripts are allowed to have Latin characters interspersed. Although the default restriction level is HIGHLY_RESTRICTIVE, it is recommended that users set their restriction level to MODERATELY_RESTRICTIVE, which allows Latin mixed with all other scripts except Cyrillic, Greek, and Cherokee, with which it is often confusable. For more details on the levels, see UTS 39 or SpoofChecker.RestrictionLevel. The Restriction Level test is aware of the set of allowed characters set in SpoofChecker.Builder.setAllowedChars(org.graalvm.shadowed.com.ibm.icu.text.UnicodeSet). Note that characters which have script code COMMON or INHERITED, such as numbers and punctuation, are ignored when computing whether a string has multiple scripts.
Additional Information

A SpoofChecker instance may be used repeatedly to perform checks on any number of identifiers.
Thread Safety: The methods on SpoofChecker objects are thread safe. The test functions for checking a single identifier, or for testing whether two identifiers are potentially confusable, may called concurrently from multiple threads using the same SpoofChecker instance.

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static class`	`SpoofChecker.Builder` SpoofChecker Builder.
`static class`	`SpoofChecker.CheckResult` A struct-like class to hold the results of a Spoof Check operation.
`static class`	`SpoofChecker.RestrictionLevel` Constants from UTS 39 for use in setRestrictionLevel.

Field Summary

Fields
Modifier and Type	Field and Description
`static int`	`ALL_CHECKS` Enable all spoof checks.
`static int`	`CHAR_LIMIT` Check that an identifier contains only characters from a specified set of acceptable characters.
`static int`	`CONFUSABLE` Enable this flag in `SpoofChecker.Builder.setChecks(int)` to turn on all types of confusables.
`static int`	`HIDDEN_OVERLAY` Check that an identifier does not have a combining character following a character in which that combining character would be hidden; for example 'i' followed by a U+0307 combining dot.
`static UnicodeSet`	`INCLUSION` Security Profile constant from UTS 39 for use in `SpoofChecker.Builder.setAllowedChars(org.graalvm.shadowed.com.ibm.icu.text.UnicodeSet)`.
`static int`	`INVISIBLE` Check an identifier for the presence of invisible characters, such as zero-width spaces, or character sequences that are likely not to display, such as multiple occurrences of the same non-spacing mark.
`static int`	`MIXED_NUMBERS` Check that an identifier does not mix numbers from different numbering systems.
`static int`	`MIXED_SCRIPT_CONFUSABLE` When performing the two-string `SpoofChecker.areConfusable(java.lang.String, java.lang.String)` test, this flag in the return value indicates that the two strings are visually confusable and that they are not from the same script, according to UTS 39 section 4.
`static UnicodeSet`	`RECOMMENDED` Security Profile constant from UTS 39 for use in `SpoofChecker.Builder.setAllowedChars(org.graalvm.shadowed.com.ibm.icu.text.UnicodeSet)`.
`static int`	`RESTRICTION_LEVEL` Check that an identifier satisfies the requirements for the restriction level specified in `SpoofChecker.Builder.setRestrictionLevel(org.graalvm.shadowed.com.ibm.icu.text.SpoofChecker.RestrictionLevel)`.
`static int`	`SINGLE_SCRIPT_CONFUSABLE` When performing the two-string `SpoofChecker.areConfusable(java.lang.String, java.lang.String)` test, this flag in the return value indicates that the two strings are visually confusable and that they are from the same script, according to UTS 39 section 4.
`static int`	`WHOLE_SCRIPT_CONFUSABLE` When performing the two-string `SpoofChecker.areConfusable(java.lang.String, java.lang.String)` test, this flag in the return value indicates that the two strings are visually confusable and that they are not from the same script but both of them are single-script strings, according to UTS 39 section 4.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`int`	`areConfusable(String s1, String s2)` Check the whether two specified strings are visually confusable.
`boolean`	`equals(Object other)` Equality function.
`boolean`	`failsChecks(String text)` Check the specified string for possible security issues.
`boolean`	`failsChecks(String text, SpoofChecker.CheckResult checkResult)` Check the specified string for possible security issues.
`UnicodeSet`	`getAllowedChars()` Get a UnicodeSet for the characters permitted in an identifier.
`Set<Locale>`	`getAllowedJavaLocales()` Get a set of `Locale` instances for the scripts that are acceptable in strings to be checked.
`Set<ULocale>`	`getAllowedLocales()` Get a read-only set of locales for the scripts that are acceptable in strings to be checked.
`int`	`getChecks()` Get the set of checks that this Spoof Checker has been configured to perform.
`String`	`getSkeleton(CharSequence str)` Get the "skeleton" for an identifier string.
`int`	`hashCode()` Overrides `Object.hashCode()`.

Methods inherited from class java.lang.Object
clone, getClass, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - INCLUSION
```
public static final UnicodeSet INCLUSION
```
    Security Profile constant from UTS 39 for use in SpoofChecker.Builder.setAllowedChars(org.graalvm.shadowed.com.ibm.icu.text.UnicodeSet).
  - RECOMMENDED
```
public static final UnicodeSet RECOMMENDED
```
    Security Profile constant from UTS 39 for use in SpoofChecker.Builder.setAllowedChars(org.graalvm.shadowed.com.ibm.icu.text.UnicodeSet).
  - SINGLE_SCRIPT_CONFUSABLE
```
public static final int SINGLE_SCRIPT_CONFUSABLE
```
    When performing the two-string SpoofChecker.areConfusable(java.lang.String, java.lang.String) test, this flag in the return value indicates that the two strings are visually confusable and that they are from the same script, according to UTS 39 section 4.
    
    See Also:
    
    Constant Field Values
  - MIXED_SCRIPT_CONFUSABLE
```
public static final int MIXED_SCRIPT_CONFUSABLE
```
    When performing the two-string SpoofChecker.areConfusable(java.lang.String, java.lang.String) test, this flag in the return value indicates that the two strings are visually confusable and that they are not from the same script, according to UTS 39 section 4.
    
    See Also:
    
    Constant Field Values
  - WHOLE_SCRIPT_CONFUSABLE
```
public static final int WHOLE_SCRIPT_CONFUSABLE
```
    When performing the two-string SpoofChecker.areConfusable(java.lang.String, java.lang.String) test, this flag in the return value indicates that the two strings are visually confusable and that they are not from the same script but both of them are single-script strings, according to UTS 39 section 4.
    
    See Also:
    
    Constant Field Values
  - CONFUSABLE
```
public static final int CONFUSABLE
```
    Enable this flag in SpoofChecker.Builder.setChecks(int) to turn on all types of confusables. You may set the checks to some subset of SINGLE_SCRIPT_CONFUSABLE, MIXED_SCRIPT_CONFUSABLE, or WHOLE_SCRIPT_CONFUSABLE to make SpoofChecker.areConfusable(java.lang.String, java.lang.String) return only those types of confusables.
    
    See Also:
    
    Constant Field Values
  - RESTRICTION_LEVEL
```
public static final int RESTRICTION_LEVEL
```
    Check that an identifier satisfies the requirements for the restriction level specified in SpoofChecker.Builder.setRestrictionLevel(org.graalvm.shadowed.com.ibm.icu.text.SpoofChecker.RestrictionLevel). The default restriction level is SpoofChecker.RestrictionLevel.HIGHLY_RESTRICTIVE.
    
    See Also:
    
    Constant Field Values
  - INVISIBLE
```
public static final int INVISIBLE
```
    Check an identifier for the presence of invisible characters, such as zero-width spaces, or character sequences that are likely not to display, such as multiple occurrences of the same non-spacing mark. This check does not test the input string as a whole for conformance to any particular syntax for identifiers.
    
    See Also:
    
    Constant Field Values
  - CHAR_LIMIT
```
public static final int CHAR_LIMIT
```
    Check that an identifier contains only characters from a specified set of acceptable characters. See SpoofChecker.Builder.setAllowedChars(org.graalvm.shadowed.com.ibm.icu.text.UnicodeSet) and SpoofChecker.Builder.setAllowedLocales(java.util.Set<org.graalvm.shadowed.com.ibm.icu.util.ULocale>). Note that a string that fails this check will also fail the SpoofChecker.RESTRICTION_LEVEL check.
    
    See Also:
    
    Constant Field Values
  - MIXED_NUMBERS
```
public static final int MIXED_NUMBERS
```
    Check that an identifier does not mix numbers from different numbering systems. For more information, see UTS 39 section 5.3.
    
    See Also:
    
    Constant Field Values
  - HIDDEN_OVERLAY
```
public static final int HIDDEN_OVERLAY
```
    Check that an identifier does not have a combining character following a character in which that combining character would be hidden; for example 'i' followed by a U+0307 combining dot.
    More specifically, the following characters are forbidden from preceding a U+0307:
    - Those with the Soft_Dotted Unicode property (which includes 'i' and 'j')
    - Latin lowercase letter 'l'
    - Dotless 'i' and 'j' ('ı' and 'ȷ', U+0131 and U+0237)
    - Any character whose confusable prototype ends with such a character (Soft_Dotted, 'l', 'ı', or 'ȷ')
    In addition, combining characters are allowed between the above characters and U+0307 except those with combining class 0 or combining class "Above" (230, same class as U+0307).
    This list and the number of combing characters considered by this check may grow over time.
    See Also:
    
    Constant Field Values
  - ALL_CHECKS
```
public static final int ALL_CHECKS
```
    Enable all spoof checks.
    
    See Also:
    
    Constant Field Values
- Method Detail
  - getChecks
```
public int getChecks()
```
    Get the set of checks that this Spoof Checker has been configured to perform.
    
    Returns:
    
    The set of checks that this spoof checker will perform.
  - getAllowedLocales
```
public Set<ULocale> getAllowedLocales()
```
    Get a read-only set of locales for the scripts that are acceptable in strings to be checked. If no limitations on scripts have been specified, an empty set will be returned. setAllowedChars() will reset the list of allowed locales to be empty. The returned set may not be identical to the originally specified set that is supplied to setAllowedLocales(); the information other than languages from the originally specified locales may be omitted.
    
    Returns:
    
    A set of locales corresponding to the acceptable scripts.
  - getAllowedJavaLocales
```
public Set<Locale> getAllowedJavaLocales()
```
    Get a set of Locale instances for the scripts that are acceptable in strings to be checked. If no limitations on scripts have been specified, an empty set will be returned.
    
    Returns:
    
    A set of locales corresponding to the acceptable scripts.
  - getAllowedChars
```
public UnicodeSet getAllowedChars()
```
    Get a UnicodeSet for the characters permitted in an identifier. This corresponds to the limits imposed by the Set Allowed Characters functions. Limitations imposed by other checks will not be reflected in the set returned by this function. The returned set will be frozen, meaning that it cannot be modified by the caller.
    
    Returns:
    
    A UnicodeSet containing the characters that are permitted by the CHAR_LIMIT test.
  - failsChecks
```
public boolean failsChecks(String text,
                           SpoofChecker.CheckResult checkResult)
```
    Check the specified string for possible security issues. The text to be checked will typically be an identifier of some sort. The set of checks to be performed was specified when building the SpoofChecker.
    
    Parameters:
    
    text - A String to be checked for possible security issues.
    
    checkResult - Output parameter, indicates which specific tests failed. May be null if the information is not wanted.
    
    Returns:
    
    True there any issue is found with the input string.
  - failsChecks
```
public boolean failsChecks(String text)
```
    Check the specified string for possible security issues. The text to be checked will typically be an identifier of some sort. The set of checks to be performed was specified when building the SpoofChecker.
    
    Parameters:
    
    text - A String to be checked for possible security issues.
    
    Returns:
    
    True there any issue is found with the input string.
  - areConfusable
```
public int areConfusable(String s1,
                         String s2)
```
    Check the whether two specified strings are visually confusable. The types of confusability to be tested - single script, mixed script, or whole script - are determined by the check options set for the SpoofChecker. The tests to be performed are controlled by the flags SINGLE_SCRIPT_CONFUSABLE MIXED_SCRIPT_CONFUSABLE WHOLE_SCRIPT_CONFUSABLE At least one of these tests must be selected. ANY_CASE is a modifier for the tests. Select it if the identifiers may be of mixed case. If identifiers are case folded for comparison and display to the user, do not select the ANY_CASE option.
    
    Parameters:
    
    s1 - The first of the two strings to be compared for confusability.
    
    s2 - The second of the two strings to be compared for confusability.
    
    Returns:
    
    Non-zero if s1 and s1 are confusable. If not 0, the value will indicate the type(s) of confusability found, as defined by spoof check test constants.
  - getSkeleton
```
public String getSkeleton(CharSequence str)
```
    Get the "skeleton" for an identifier string. Skeletons are a transformation of the input string; Two strings are confusable if their skeletons are identical. See Unicode UAX 39 for additional information. Using skeletons directly makes it possible to quickly check whether an identifier is confusable with any of some large set of existing identifiers, by creating an efficiently searchable collection of the skeletons. Skeletons are computed using the algorithm and data described in Unicode UAX 39.
    
    Parameters:
    
    str - The input string whose skeleton will be generated.
    
    Returns:
    
    The output skeleton string.
  - equals
```
public boolean equals(Object other)
```
    Equality function. Return true if the two SpoofChecker objects incorporate the same confusable data and have enabled the same set of checks.
    
    Overrides:
    
    equals in class Object
    
    Parameters:
    
    other - the SpoofChecker being compared with.
    
    Returns:
    
    true if the two SpoofCheckers are equal.
  - hashCode
```
public int hashCode()
```
    Overrides Object.hashCode().
    
    Overrides:
    
    hashCode in class Object

Class SpoofChecker

Confusables

Spoof Detection

Additional Information

Nested Class Summary

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

INCLUSION

RECOMMENDED

SINGLE_SCRIPT_CONFUSABLE

MIXED_SCRIPT_CONFUSABLE

WHOLE_SCRIPT_CONFUSABLE

CONFUSABLE

RESTRICTION_LEVEL

INVISIBLE

CHAR_LIMIT

MIXED_NUMBERS

HIDDEN_OVERLAY

ALL_CHECKS

Method Detail

getChecks

getAllowedLocales

getAllowedJavaLocales

getAllowedChars

failsChecks

failsChecks

areConfusable

getSkeleton

equals

hashCode