IDS02-J. Canonicalize path names before validating them

According to the Java API [[API 2006]], class java.io.File

A path name, whether abstract or in string form, may be either absolute or relative. An absolute path name is complete in that no other information is required to locate the file that it denotes. A relative path name, in contrast, must be interpreted in terms of information taken from some other path name.

Absolute or relative path names may contain file links such as symbolic (soft) links, hard links, short cuts, shadows, aliases, and junctions rather than canonical paths. These aliases must be fully resolved before any file validation operations are performed. For example, the final target of a symbolic link called trace might be the path name /home/system/trace. Path names may also contain special file names that make validation difficult:

1. “.” refers to the directory itself.
2. Inside a directory, the special file name “..” refers to the directory’s parent directory.

In addition to these specific issues, there are a wide variety of operating and file system specific naming conventions which make validation difficult.

The process of canonicalizing file names makes it easier to validate an path name. More than one path name can refer to a single directory or file. Further, the textual representation of an path name may yield little or no information regarding the directory or file to which it refers. Consequently, all path names must be fully resolved or canonicalized before validation.

This is necessary because operating on untrusted user input may result in a directory traversal or path equivalence vulnerability. A directory traversal vulnerability allows an I/O operation to escape a specified operating directory. A path equivalence vulnerabilities occur when an attacker provides a different but equivalent name for a resource to bypass security checks.

Canonicalization contains an inherent race condition between the time you

1. create the canonical path name
2. perform the validation
3. open the file

During this time the canonical path name may have been modified and may no longer be referencing a valid file. The canonical path name can be used to determine if the referenced file name is in a secure directory (see FIO00-J. Do not operate on files in shared directories). If the referenced file is in a secure directory, then by definition, an attacker cannot tamper with it, and cannot exploit the race condition.

This rule is a specific instance of IDS01-J. Normalize strings before validating them.

Noncompliant Code Example

This noncompliant code example accepts a file path as a command line argument and uses the File.getAbsolutePath() method to obtain the absolute file path. It also uses the isInSecureDir() method defined in FIO00-J. Do not operate on files in shared directories to ensure that the file is in a secure directory but does not resolve file links or eliminate equivalence errors.

public static void main(String[] args) {
  File f = new File("/home/me/" + args[0]);
  String absPath = f.getAbsolutePath();

  if (!isInSecureDir(Paths.get(absPath))) {
    throw new IllegalArgumentException();
  }
  if (!validate(absPath)) {  // Validation
    throw new IllegalArgumentException();
  }		  
}

The application intends to restrict the user me from operating on files outside the /home/me directory. The validate() method ensures that the path name resides within this directory, but the validation can be easily circumvented. For example, the user me can create a link in their home directory /home/me that refers to a directory or file outside of the directory. The path name of the link might appear to the validate() method to reside in the /home/me and consequently pass validation, but the operation will actually be performed on the final target of the link residing outside the directory.

Note that File.getAbsolutePath() does resolve symbolic links, aliases, and short cuts on Windows and Macintosh platforms. Nevertheless, the JLS lacks any guarantee that this behavior is present on all platforms or that it will continue in future implementations.

Compliant Solution (getCanonicalPath())

This compliant solution uses the getCanonicalPath() method, introduced in Java 2, because it resolves all aliases, shortcuts, or symbolic links consistently across all platforms. Special file names such as dot dot (..) are also removed so that the input is reduced to a canonicalized form before validation is carried out. An attacker cannot use ../ sequences to break out of the specified directory when the validate() method is present.

public static void main(String[] args) throws IOException {
  File f = new File("/home/me/" + args[0]);
  String canonicalPath = f.getCanonicalPath();

  if (!isInSecureDir(Paths.get(canonicalPath))) {
    throw new IllegalArgumentException();
  }
  if (!validate(canonicalPath)) {  // Validation
    throw new IllegalArgumentException();
  }
}

The getCanonicalPath() method throws a security exception when used within applets as it reveals too much information about the host machine. The getCanonicalFile() method behaves like getCanonicalPath() but returns a new File object instead of a String.

Compliant Solution (Security Manager)

A comprehensive way of handling this issue is to grant the application the permissions to operate only on files present within the intended directory — /home/me in this example. This compliant solution specifies the absolute path of the program in its security policy file, and grants java.io.FilePermission with target /home/me and actions read and write.

grant codeBase "file:/home/programpath/" {
  permission java.io.FilePermission "/home/me", "read, write";
};

This solution requires that /home/me is a secure directory.

Noncompliant Code Example

This noncompliant code example allows the user to specify the absolute path of a file name on which to operate. The user can specify files outside the intended directory (/img in this example) by entering an argument that contains ../ sequences, and consequently violate the intended security policies of the program.

FileOutputStream fis = new FileOutputStream(new File("/img/" + args[0]));
// ...

Noncompliant Code Example

The following code examples assume that /img and /img/java are secure directories.

This noncompliant code example attempts to mitigate the issue by using the File.getCanonicalPath() method, which fully resolves the argument and constructs a canonicalized path. For example, the path /img/../etc/passwd resolves to /etc/passwd. Validation without canonicalization remains insecure because the user can specify files outside the intended directory.

File f = new File("/img/" + args[0]);
String canonicalPath = f.getCanonicalPath();		  
FileOutputStream fis = new FileOutputStream(f);
// ...

Compliant Solution

This compliant solution obtains the file name from the untrusted user input, canonicalizes it and then validates it against the intended file name. It operates on the specified file only when validation succeeds.

File f = new File("/img/" + args[0]);
String canonicalPath = f.getCanonicalPath();

if (canonicalPath.equals("/img/java/file1.txt")) {  // Validation
   // Do something
}

if (!canonicalPath.equals("/img/java/file2.txt")) {  // Validation
   // Do something
}

FileOutputStream fis = new FileOutputStream(f);		

Compliant solution (Security Manager)

A comprehensive solution is to grant the application the permissions to read only the specifically intended files or directories. Grant these permissions by to specifying the absolute path of the program in the security policy file and granting java.io.FilePermission with the canonicalized absolute path of the file or directory as the target name and with the action set to read.

// All files in /img/java can be read
grant codeBase "file:/home/programpath/" {
  permission java.io.FilePermission "/img/java", "read";
};

Risk Assessment

Using path names from untrusted sources without first canonicalizing them and then validating them can result in directory traversal and path equivalence vulnerabilities.

Related Vulnerabilities

Related Guidelines

Bibliography

            IDS03-J. Validate all data passed in through environment variables and non-default properties