Page History

Wiki MarkupAccording to the Java API \ [[API 06|AA. Java References#API 06]\], class {{API 2006] for class java.io.File}}:

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 in order 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 Absolute or relative path names may sometimes contain aliasescontain file links such as symbolic (soft) links, hard links, shortcuts, shadows, symbolic links and shortcuts as opposed to canonical paths, which refer to actual files or directories that these point to. These path names aliases, and junctions. These file links must be fully resolved before any file validation operations are performed. For instance, resolving example, the final target of a symbolic link called trace may yield its actual path on the file system, such as, 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, a wide variety of operating system–specific and file system–specific naming conventions make validation difficult.

Canonicalizing 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 the absence of a security manager because untrusted user input may allow an input-output operation to escape the specified operating directory. Failure to do this can result in information disclosure and malicious modification of files existing in directories other than the specified onevalidate a path name. More than one path name can refer to a single directory or file. Further, the textual representation of a 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.

Validation may be necessary, for example, when attempting to restrict user access to files within a particular directory or to otherwise make security decisions based on the name of a file name or path name. Frequently, these restrictions can be circumvented by an attacker by exploiting 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 vulnerability occurs when an attacker provides a different but equivalent name for a resource to bypass security checks.

Canonicalization contains an inherent race window between the time the program obtains the canonical path name and the time it opens the file. While the canonical path name is being validated, the file system may have been modified and the canonical path name may no longer reference the original valid file. Fortunately, this race condition can be easily mitigated. The canonical path name can be used to determine whether the referenced file name is in a secure directory (see FIO00-J. Do not operate on files in shared directories for more information). 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 recommendation 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. This method does not automatically resolve symbolic links.

The application desires 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 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 links, aliases and short cuts are fully resolved on the Windows and Macintosh platforms when File.getAbsolutePath() is used.

allows the user to specify the path of an image file to open. By prepending /img/ to the directory, this code enforces a policy that only files in this directory should be opened. The program also uses the isInSecureDir() method defined in FIO00-J. Do not operate on files in shared directories. 

However, the user can still specify a file outside the intended directory by entering an argument that contains ../ sequences.  An attacker can also create a link in the /img directory that refers to a directory or file outside of that directory. The path name of the link might appear to reside in the /img directory and consequently pass validation, but the operation will actually be performed on the final target of the link, which can reside outside the intended directory.

File file

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

  if(!validate(absPathif (!isInSecureDir(file)) {  // Validation
    throw new IllegalArgumentException();
}
FileOutputStream fis }		= new 
}

Compliant Solution

FileOutputStream(file);
// ...

Noncompliant Code Example (getCanonicalPath())

This noncompliant code example attempts to mitigate the issue by using the File.This compliant solution uses the getCanonicalPath() method, introduced in Java 2, because it resolves the 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 (which fully resolves the argument and constructs a canonicalized path. 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 adversary 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("/tmp/" + args[0]);
  String canonicalPath = f.getCanonicalPath();
 
  if(!validate(canonicalPath)) {  // Validation
    throw new IllegalArgumentException();
  }
}

The  For example, the path /img/../etc/passwd resolves to /etc/passwd. The getCanonicalPath() method throws a security exception when used within in applets as because 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

A comprehensive way of handling this issue is to grant the application the permissions to operate on files present only within /tmp. This can be achieved by specifying the absolute path of the program in the security policy file and granting the 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 guideline ENV30-J. Create a secure sandbox using a Security Manager contains more information on using a security manager.

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 an argument that contains ../ sequences, it is possible to escape out of the /img directory and operate on a file present in another directoryUnfortunately, the canonicalization is performed after the validation, which renders the validation ineffective.

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

Noncompliant Code Example

This noncompliant code example tries to mitigate the issue by using the File.getCanonicalPath() method. This method fully resolves the argument and constructs a canonicalized path. For example, the path /img/../etc/passwd resolves to /etc/passwd. This is insecure because the program breaks out of the specified directory /img.

File f = new File("/img/" + args[0]);if (!isInSecureDir(file)) {
  throw new IllegalArgumentException();
}
String canonicalPath = ffile.getCanonicalPath();		  
FileOutputStream fis = new FileOutputStream(fcanonicalPath);
// ...

Compliant

...

Solution (getCanonicalPath())

This compliant solution obtains the canonicalized file name from the untrusted user input, canonicalizes it, and then validates it against the target file name, before operating on the filea list of benign path names. It operates on the specified file only when validation succeeds, that is, only if the file is one of the two valid files file1.txt or file2.txt in /img/java.

File ffile = new File("/img/" + args[0]);
if (!isInSecureDir(file)) {
  throw new IllegalArgumentException();
}
String canonicalPath = ffile.getCanonicalPath();

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

if(!canonicalPath.equals("/img/java/file2.txt")) {
   // Validation
Invalid file;  // Do somethinghandle error
}

FileOutputStreamFileInputStream fis = new FileOutputStreamFileInputStream(f);		

Compliant

...

Solution (Security Manager)

A comprehensive way of handling to handle this issue is to grant the application the permissions to read operate only the specific files or directory. This can be achieved by specifying on files present within the intended directory—the /img directory in this example. This 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 the absolute path of the file or directory target /img/java and the read action as read.
This is shown belowsolution requires that the /img directory is a secure directory, as described in FIO00-J. Do not operate on files in shared directories.

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

The guideline ENV30-J. Create a secure sandbox using a Security Manager contains more information on using a security manager.

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 attacksand path equivalence vulnerabilities.

Automated Detection

...

TODO

Related Vulnerabilities

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

Other Languages

...

Tool	Version	Checker	Description
The Checker Framework	Include Page The Checker Framework_V The Checker Framework_V	Tainting Checker	Trust and security errors (see Chapter 8)
Coverity	7.5	BAD_EQ PATH_MANIPULATION	Implemented
Fortify	1.0	Path_Manipulation	Implemented
Parasoft Jtest	Include Page Parasoft_V Parasoft_V	CERT.FIO16.CDBV	Canonicalize data before validation

Related Vulnerabilities

CVE-2005-0789 describes a directory traversal vulnerability in LimeWire 3.9.6 through 4.6.0 that allows remote attackers to read arbitrary files via a .. (dot dot) in a magnet request.

CVE-2008-5518 describes multiple directory traversal vulnerabilities in the web administration console in Apache Geronimo Application Server 2.1 through 2.1.3 on Windows that allow remote attackers to upload files to arbitrary directories.

Related Guidelines

...

...

...

...

...

Android Implementation Details

This rule is applicable in principle to Android. Please refer to the Android-specific instance of this rule: DRD08-J. Always canonicalize a URL received by a content provider.

Bibliography

...

Image Added Image Added Image Added

References

\[[API 06|AA. Java References#API 06]\] [method getCanonicalPath()|http://java.sun.com/javase/6/docs/api/java/io/File.html#getCanonicalPath()]
\[[API 06|AA. Java References#API 06]\] [method getCanonicalFile()|http://java.sun.com/javase/6/docs/api/java/io/File.html#getCanonicalFile()]
\[[Harold 99|AA. Java References#Harold 99]\]
\[[MITRE 09|AA. Java References#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"

09. Input Output (FIO)      09. Input Output (FIO)      FIO01-J. Do not let Runtime.exec() fail or block indefinitely