IDS15-J. Use a subset of ASCII for file names

File names and path names containing particular characters can be troublesome and can cause unexpected behavior leading to potential vulnerabilities. If a program allows the user to specify a file name in the creation or renaming of a file, certain checks should be made to disallow the following characters and patterns:

• Leading dashes—Leading dashes can cause problems when programs are called with the file name as a parameter because the first character or characters of the file name might be interpreted as an option switch.
• Control characters, such as newlines, carriage returns, and escape—Control characters in a file name can cause unexpected results from shell scripts and in logging.
• Spaces—Spaces can cause problems with scripts and when double quotes aren't used to surround the file name.
• Invalid character encodings — Character encodings can be a huge issue. (See guideline IDS03-J. Sanitize non-character code points before performing other sanitization.)
• Any characters other than letters, numbers, and punctuation designated here as portable — Other special characters are included in this recommendation because they are commonly used as separators and having them in a file name can cause unexpected and potentially insecure behavior.

Also, many of the punctuation characters aren't unconditionally safe for file names even if they are portably available.

These characters or patterns are primarily a problem to scripts and automated parsing, but because they are not commonly used, it is best to disallow their use to reduce potential problems. Interoperability concerns also exist because different operating systems handle file names of this sort in different ways.

As a result of the influence of MS-DOS, file names of the form xxxxxxxx.xxx, where x denotes an alphanumeric character, are generally supported by modern systems. On some platforms, file names are case sensitive; while on other platforms, they are case insensitive. VU#439395 is an example of a vulnerability resulting from a failure to deal appropriately with case sensitivity issues [[VU#439395]].

In addition to the letters of the English alphabet ("A" through "Z" and "a" through "z"), the digits ("0" through "9"), and the space, only the following characters are portable:

% & + , - . : = _

Only these characters should be considered for use in file and path names. This is an instance of guideline IDS01-J. Sanitize untrusted data passed across a trust boundary.

Noncompliant Code Example

In the following noncompliant code, unsafe characters are used as part of a file name.

File f = new File("A\uD8AB");
OutputStream out = new FileOutputStream(f);

An implementation is free to define its own mapping of the non-"safe" characters. For example, when tested on an Ubuntu Linux distribution, this noncompliant code example resulted in the following file name:

A?

Compliant Solution

Use a descriptive file name, containing only the subset of ASCII previously described.

File f = new File("name.ext");
OutputStream out = new FileOutputStream(f);

Noncompliant Code Example

This noncompliant code example creates a file with input from the user without sanitizing it.

public static void main(String[] args) throws Exception {
  if (args.length < 1) {
    // handle error
  }
  File f = new File(args[0]);
  OutputStream out = new FileOutputStream(f);
  // ...
}

No checks are performed on the file name to prevent troublesome characters. If an attacker knew this code was in a program used to create or rename files that would later be used in a script or automated process of some sort, they could choose particular characters in the output file name to confuse the later process for malicious purposes.

Compliant Solution

In this compliant solution, the program uses a whitelist to reject unsafe file names.

public static void main(String[] args) throws Exception {
  if (args.length < 1) {
    // handle error
  }
  String filename = args[0];

  Pattern pattern = Pattern.compile("[A-Za-z0-9%&+,.:=_]");
  Matcher matcher = pattern.matcher(filename);
  if (matcher.find()) {
    // filename contains bad chars, handle error
  }
  File f = new File(filename);
  OutputStream out = new FileOutputStream(f);
  // ...
}

Similarly, all file names originating from untrusted sources must be sanitized to ensure they contain only safe characters.

Risk Assessment

Failing to use only the subset of ASCII that is guaranteed to work can result in misinterpreted data.

Related Guidelines

CERT C Secure Coding Standard: MSC09-C. Character Encoding - Use Subset of ASCII for Safety
CERT C++ Secure Coding Standard: MSC09-CPP. Character Encoding - Use Subset of ASCII for Safety

ISO/IEC 646-1991 ISO 7-bit coded character set for information interchange

ISO/IEC 9899:1999 Section 5.2.1, "Character sets"

ISO/IEC TR 24772 "AJN Choice of Filenames and other External Identifiers"

MISRA Rule 3.2, "The character set and the corresponding encoding shall be documented," and Rule 4.1, "Only those escape sequences that are defined in the ISO C standard shall be used"

MITRE CWE: CWE-116, "Improper Encoding or Escaping of Output"

Bibliography

[[Kuhn 2006]] UTF-8 and Unicode FAQ for UNIX/Linux
[[Wheeler 2003]] 5.4 File Names
[[VU#881872]]

IDS14-J. Perform lossless conversion of String data between differing character encodings            IDS16-J. Do not use locale-dependent methods on locale-sensitive data without specifying the appropriate locale