Jetty Logo
Contact the core Jetty developers at www.webtide.com

private support for your internal/customer projects ... custom extensions and distributions ... versioned snapshots for indefinite support ... scalability guidance for your apps and Ajax/Comet projects ... development services from 1 day to full product delivery

DRAFT

This page contains content that we have migrated from Jetty 7 or Jetty 8 documentation into the correct format, but we have not yet audited it for technical accuracy in with Jetty 9. Be aware that examples or information contained on this page may be incorrect. Please check back soon as we continue improving the documentation, or submit corrections yourself to this page through Github. Thank you.

Aliased Files and Symbolic links

Good Security Practise
Alias detection
Serving Aliases and Symbolic Links

Web applciations will often server static content from the file system provided by the operating system running underneatth the JVM. However because file systems often implement multiple aliased names for the same file, then security constraints and other servlet URI space mappings my inadvertantly be bypassed by aliases.

I key example of this is case insensitivety and 8.3 names implemented by the Windows File system. If a file within a webapplication called /mysecretfile.txt is protected by a security constraint on the URI /mysecretfile.txt, then a request to /MySecretFile.TXT will not match the URI constraint because URIs are case sensitive, but the windows file system will report that a file does exist at that name and it will be served despite the security constraint. Less well known than case insensitivity is that windows files systems also support 8.3 filenames for compatibility with legacy programs. Thus a request to a URI like /MYSECR~1.TXT will again not match the security constraint, but will be reported as an existing file by the file system and served.

There are many examples of aliases, not just on windows:

In addition, it is not just URI security constraints that can be bypassed. For example the mapping of the URI pattern *.jsp to the JSP Servlet may be bypassed by an a request to an alias like /foobar.jsp%00, thus rather than execute the JSP, the source code of the JSP is returned by the file system.

Good Security Practise

Part of the problem with aliases is that the standard webapplication security model is to allow all requests except the ones that are specifically denied by security constraints. A best practise for security is to deny all requests and to permit only those that are specifically identified as allowable. While it is possible to design web application security constraints in this style, it can be difficult in all circumstances and it is not the default. Thus it is important for Jetty to be able to detect and deny requests to aliased static content.

Alias detection

It is impossible for Jetty to know of all the aliases that may be implemented by the file system running beneath it, thus it does not attempt to make any specific checks for any know aliases. Instead jetty detects aliases by using the canonical path of a file. If a file resource handled by jetty has a canonical name that differs from the name used to request the resource, then Jetty determines that the resource is an aliased request and it will not be returned by the ServletContext.getResource(String) method (or similar) and thus will not be served as static content nor used as the basis of a JSP.

This if Jetty is running on a windows operation system, then a file called /MySecret.TXT will have a cannonical name that exactly matches that case. So while a request to /mysecret.txt or /MYSECR~1.TXT will result in a File Resource that matches the file, the different canonical name will indicate that those requests are aliases and they will not be served as static content and instead a 404 response returned.

Unfortunately this approach denies all aliases, including symbolic links, which can be useful in assembling complex web applications.

Serving Aliases and Symbolic Links

Not all aliases are bad nor should be seen as attempts to subvert security constratints. Specifically symbolic links can be very useful when assembling complex web applications, yet by default Jetty will not serve them. Thus Jetty contexts support an extensible AliasCheck mechanism to allow aliases resources to be inspected an conditionally served. In this way, "good" aliases can be detected and served. Jetty provides several utility implementations of the AliasCheck interface as nested classes with ContextHandler:

ApproveAliases

Approve all aliases (USE WITH CAUTION!).

ApproveSameSuffixAliases

Approve Aliases with same suffix. Eg. a symbolic link from /foobar.html to /somewhere/wibble.html would be approved because both the resource and alias end with ".html".

ApprovePathPrefixAliases

Approve Aliases with a path prefix. Eg. a symbolic link from /dirA/foobar.html to /dirB/foobar.html would be approved because both the resource and alias end with "/foobar.html".

An application is free to implement its own Alias checking. Alias Checkers can be installed in a context via the following XML used in a context deployer file or WEB-INF/jetty-web.xml:

  ...

  <!-- Allow directory symbolic links  -->
  <Call name="addAliasCheck">
    <Arg>
      <New class="org.eclipse.jetty.server.handler.ContextHandler$ApprovePathPrefixAliases"/>
    </Arg>
  </Call>
  <!-- Allow file symbolic links  -->
  <Call name="addAliasCheck">
    <Arg>
      <New class="org.eclipse.jetty.server.handler.ContextHandler$ApproveSameSuffixAliases"/>
    </Arg>
  </Call>
      

See an error or something missing? Contribute to this documentation at Github!