IDS13-J. Account for supplementary and combining characters in globalized code

According to the Java API [[API 2006]], class Character documentation (Unicode Character Representations)

The char data type (and consequently the value that a Character object encapsulates) are based on the original Unicode specification, which defined characters as fixed-width 16-bit entities. The Unicode standard has since been changed to allow for characters whose representation requires more than 16 bits. The range of legal code points is now U+0000 to U+10FFFF, known as Unicode scalar value.

The Java 2 platform uses the UTF-16 representation in char arrays and in the String and StringBuffer classes. In this representation, supplementary characters are represented as a pair of char values, the first from the high-surrogates range, (\uD800-\uDBFF), the second from the low-surrogates range (\uDC00-\uDFFF).

An int value represents all Unicode code points, including supplementary code points. The lower (least significant) 21 bits of int are used to represent Unicode code points and the upper (most significant) 11 bits must be zero. Unless otherwise specified, the behavior with respect to supplementary characters and surrogate char values is as follows:

• The methods that only accept a char value cannot support supplementary characters. They treat char values from the surrogate ranges as undefined characters. For example, Character.isLetter('\uD840') returns false, even though this specific value if followed by any low-surrogate value in a string would represent a letter.
• The methods that accept an int value support all Unicode characters, including supplementary characters. For example, Character.isLetter(0x2F81A) returns true because the code point value represents a letter (a CJK ideograph).

Security vulnerabilities may arise if an application expects input in a form that an adversary is capable of bypassing. This can happen when an application disregards supplementary characters or when it does not use combining characters appropriately. Combining characters are characters that modify other characters. Refer to the Combining Diacritical Marks chart for more details on combining characters.

Noncompliant Code Example

This noncompliant code example attempts to trim leading letters from the string. It fails to accomplish this task because Character.isLetter() does not work for supplementary and combining characters [[Hornig 2007]].

// Fails for supplementary or combining characters
public static String trim_bad1(String string) {
  char ch;
  for (int i = 0; i < string.length(); i += 1) {
    ch = string.charAt(i);
    if (!Character.isLetter(ch)) {
      break;
    }
  }
  return string.substring(i);
}

Noncompliant Code Example

This noncompliant code example ameliorates the problem by using the String.codePointAt() method, which accepts an int argument. This works for supplementary characters but not for combining characters [[Hornig 2007]].

// Fails for combining characters
public static String trim_bad2(String string) {
  int ch;
  for (int i = 0; i < string.length(); i += Character.charCount(ch)) {
    int ch = string.codePointAt(i);
    if (!Character.isLetter(ch)) {
      break;
    }
  }
  
  return string.substring(i);
}

Compliant Solution

This compliant solution works for both supplementary and combining characters [[Hornig 2007]]. According to the Java API [[API 2006]], class java.text.BreakIterator documentation

The BreakIterator class implements methods for finding the location of boundaries in text. Instances of BreakIterator maintain a current position and scan over text returning the index of characters where boundaries occur.

The boundaries returned may be those of supplementary characters, combining character sequences, or ligature clusters. For example, an accented character might be stored as a base character and a diacritical mark.

public static String trim_good(String string) {
  BreakIterator iter = BreakIterator.getCharacterInstance();
  iter.setText(string);
  for (int i = iter.first(); i != BreakIterator.DONE; i = iter.next()) {
    int ch = string.codePointAt(i);
    if (!Character.isLetter(ch)) {
      break;
    }    
  }
  
  if (i == BreakIterator.DONE) { // Reached first or last text boundary
    return ""; // The input was either blank or had only (leading) letters
  } else {
    return string.substring(i);
  }
}

To perform locale-sensitive String comparisons for searching and sorting, use the java.text.Collator class.

Risk Assessment

Failing to account for supplementary and combining characters can lead to unexpected behavior.

Automated Detection

TODO

Related Vulnerabilities

Search for vulnerabilities resulting from the violation of this guideline on the CERT website.

Bibliography

[[API 2006]] Classes Character and BreakIterator
[[Hornig 2007]] Problem areas: Characters

IDS12-J. Prevent code injection      13. Input Validation and Data Sanitization (IDS)      IDS14-J. Perform loss less conversion of String to given encoding and back