Streaming Secure Files Efficiently With ColdFusion And MOD XSendFile

ColdFusion is truly the cat's pajamas. But, it only works on CFM and CFC pages. This typically isn't a problem; but, when it comes to adding access-permissions around non-ColdFusion files, we can find ourselves in a less-than-optimal situation. While it has been shown that ColdFusion can stream binary files without a significant memory hit, we still have the issue of threads - streaming a file using ColdFusion and the CFContent tag ties up a ColdFusion thread for the duration of the file transfer. Ideally, we'd like to be able to perform a security check in ColdFusion and then pass the file-transfer burden off to the underlying operating system. Luckily, MOD XSendFile does exactly this.

XSendFile is an Apache module that allows ColdFusion (and other application platforms) to delegate file transfer actions back to Apache. It does this through the use of an HTTP Header. After ColdFusion has processed an incoming request, the XSendFile module will examine the outgoing HTTP headers; if the "x-sendfile" header exists, Apache overwrites the outgoing request with the file defined in the "x-sendfile" header.

NOTE: While XSendFile is an Apache module, there are ways that you can run Apache configurations in IIS (ex. Helicon Ape).

To demonstrate how MOD XSendFile works, I've set up a super simple, mock store on my local Apache server. In this store, users can exchange credits in return for access to secure photos. These photos reside outside the web root; as such, we need to use ColdFusion to determine access rights on a per-photo basis and then to pass the non-public photo paths back to Apache for binary streaming.

To get this to work, I had to install the XSendFile module in Apache, load the module, and then enable it for one of my virtual hosts:

Once the XSendFile module is installed, it has to be explicitly enabled. In the above Apache configuration, the following command turns XSendFile on for a given directory:

This will allow XSendFile to access files anywhere in or below the contextual directory. The problem with that is that I am defining this within my web root; and, for obvious security purposes, I am storing the photos outside of the web root. As such, I then have to specify that XSendFile can access files that reside outside of the web root; specifically, that it can access files in my private "images" directory:

NOTE: In previous versions of XSendFile, this same action used to be accomplished with XSendFileAllowAbove. This directive no longer exists and has been replaced with XSendFilePath.

In the end, this is what my directory structure looked like:

• ./site/www/
• ./site/www/thumbs/
• ./site/images/

As you can see, the "www" is our public website. Notice that the thumbnails are stored in a public, web-accessible directory - thumbs. There's no need to secure those. The large photos, on the other hand, are our primary assets and are stored outside the web root in the parallel, "images," directory.

Now that we have XSendFile installed and configured, let's take a look at the ColdFusion code. I'm going to move through this code rather quickly since 90% of it isn't really relative to the XSendFile Apache module - it's just there to provide context.

Application.cfc

When a user's session gets initialized, they get two properties - balance and purchases. The balance is their store credit and the purchases is an ID-based collection of photos for which they have paid.

The main page of the application handles the photo-list and purchase-processing. The user selects a photo and, if they have enough credits, the photo is added to their list of purchases and the user is forwarded to the purchase page.

Index.cfm

Once the user had made the purchase of a photo, they are forwarded to the purchase page. The purchase page doesn't actually stream the binary file to the client; rather, it acts as an intermediary landing page that gives the user some informational feedback. It's one of those "your download will begin shortly" pages.

Purchase.cfm

This page then forwards the user onto the actual download page which is where we finally get to deal with code that relates to XSendFile. Notice that ColdFusion isn't actually reading in or streaming out any file.

Download.cfm

Before it does anything else, this ColdFusion page checks to see if the user has actually purchased the photo. Remember, that's really the reason we are here - to figure out how to create a secure-access layer in ColdFusion in which we can perform user-specific security checks. But, once the permissions have been evaluated, ColdFusion simply defines a new HTTP header, "x-sendfile." The value stored in this header is the absolute file path of the secure file that we are streaming. Once ColdFusion finishes the request, the XSendFile Apache module then examines the outgoing HTTP headers and streams the given file back to the client.

NOTE: The X-SendFile header never reaches the client. Once the XSendFile module evaluates the outgoing HTTP headers, it strips the X-SendFile entry and streams the file at the defined path.

I have to say, MOD XSendFile is pretty darn awesome. Admittedly, I like to keep my application as modular as possible; that is, I like to keep as much as the application configuration inside the application itself. But, when you see the kind of power and functionality that can be provided by things like XSendFile and URL Rewriting, it definitely makes you a lot more open-minded. XSendFile makes it a breeze to provide ColdFusion-powered secure file access without putting an undue burden on the finite collection of ColdFusion threads.

You Might Also Be Interested In: