Page History

...

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

An absolute path may sometimes contain aliases, shadows, symbolic links and shortcuts as opposed to (aliases, hereafter) rather than canonical paths, which refer to the actual files or directories that these point to. These path names aliases must be fully resolved before any file validation operations are performed. For instance, resolving a symbolic link called trace may yield its actual path on the file system, such as, /home/system/trace.

The process of canonicalizing file names makes it easier to verify a path, directory, or file name by making it easier to compare names. This is because extraneous characters are eliminated during canonicalization. Validation after performing canonicalization is necessary in an alias. More than one alias can refer to a single directory or file. Further, the textual representation of an alias may yield little or no information regarding the directory or file to which it refers. Consequently, all aliases should be fully resolved or canonicalized before validation. In the absence of a security manager, aliases must be canonicalized before validation. This is necessary because untrusted user input may allow an input-output operation to escape the specified operating directory. Failure to do Violation of this guideline can result in information disclosure and malicious modification of files existing in directories other than the specified one.

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. This method does not automatically resolve symbolic links.

The application desires intends to restrict the user from operating on files outside the /tmp directory and uses a validate() method to enforce this condition. An adversary who can create symbolic links in /tmp can cause the program to pass validation checks by supplying the unresolved path. After the validation, any All file operations performed are reflected in the file pointed to by the symbolic link.

Let {{argv\[0\]}} be the string {{filename}}, where {{/tmp/filename}} is a symbolic link that points to the file {{/dirname/filename}} present on the local file system. The validation passes because the root directory of the compiled path name is still {{/tmp}}, but the operations are carried out on the file {{/dirname/filename}}.

Symbolic Note that File.getAbsolutePath() resolves all symbolic links, aliases and short cuts are fully resolved on the all known Windows and Macintosh platforms when File.getAbsolutePath() is used. Nevertheless, the JLS lacks any guarantee either that this behavior is present on all platforms or that it will continue in future implementations.

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

  if(!validate(absPath)) {  // Validation
    throw new IllegalArgumentException();
  }		  
}

Compliant Solution (getCanonicalPath)

This compliant solution uses the getCanonicalPath() method, introduced in Java 2, because it resolves the all aliases, shortcuts or symbolic links consistently, across all platforms. The value of the alias (if any) is not included in the returned value. Moreover, relative references like the double period (..) are also removed so that the input is reduced to a canonicalized form before validation is carried out. An adversary cannot use ../ sequences to break out of the specified directory when the validate() method is present.

...

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 only within the intended directory — /tmp in this example. This can be achieved by specifying compliant solution specifies the absolute path of the program in the its security policy file, and granting the grants java.io.FilePermission with the target name as /tmp and the actions as read and write. This is shown below.

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

The See guideline ENV02-J. Create a secure sandbox using a Security Manager contains more for additional information on using a security managermanagers.

Noncompliant Code Example

This noncompliant code example allows the user to specify the absolute path of a file name on which operations are required to be performed. If the user enters operate. The user can specify files outside the intended directory (/img in this example) by entering an argument that contains ../ sequences, it is possible to escape out of the /img directory and operate on a file present in another directoryand consequently violate the intended security policies of the program.

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

Noncompliant Code Example

This noncompliant code example attempts to mitigate the issue by using the File.getCanonicalPath() method. This method , which fully resolves the argument and constructs a canonicalized path. For example, the path /img/../etc/passwd resolves to /etc/passwd. This is Canonicalization without validation remains insecure because the program breaks out of the specified directory /imguser remains able to 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 target intended file name, before operating . 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

A comprehensive solution is to grant the application the permissions to read only the specifically intended files or directories. One way to grant Grant these permissions is by to specify specifying the absolute path of the program in the security policy file and to grant the 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";
};

The See guideline ENV02-J. Create a secure sandbox using a Security Manager contains more for additional information on using a security managermanagers.

Risk Assessment

Using path names from untrusted sources without canonicalizing the filenames before first canonicalizing them and then validating them can result in directory traversal attacks.

Automated Detection

...

Related Vulnerabilities

CVE-2005-0789, CVE-2008-5518

Other Languages

This guideline appears in the C Secure Coding Standard as FIO02-C. Canonicalize path names originating from untrusted sources.

This guideline appears in the C++ Secure Coding Standard as FIO02-CPP. Canonicalize path names originating from untrusted sources.

Bibliography

\[[API 2006|AA. Bibliography#API 06]\] [method getCanonicalPath()|http://java.sun.com/javase/6/docs/api/java/io/File.html#getCanonicalPath()]
\[[API 2006|AA. Bibliography#API 06]\] [method getCanonicalFile()|http://java.sun.com/javase/6/docs/api/java/io/File.html#getCanonicalFile()]
\[[Harold 1999|AA. Bibliography#Harold 99]\]
\[[MITRE 2009|AA. Bibliography#MITRE 09]\] [CWE ID 171|http://cwe.mitre.org/data/definitions/171.html] "Cleansing, Canonicalization, and Comparison Errors", [CWE ID 647|http://cwe.mitre.org/data/definitions/647.html] "Use of Non-Canonical URL Paths for Authorization Decisions"

...