Secure Downloading in ASP

The Advantages of Downloading with FileUp
The TransferFile Method
Setting Response Headers
Download and Open in the Browser
Downloading with an "Open or Save" Dialog

The Advantages of Downloading with FileUp

The files to download do not have to be in a browsable location on the server.

The path to the file only exists in the server-side code, which helps protect sensitive information from end-users.

Files can be downloaded from any location on the Web server, from a file server, or from a database.

FileUp allows you to limit the bandwidth used for downloads per connection and per server.

The behavior of a download is heavily browser-dependent. The only way to ensure that your application works as desired is to extensively test on many different browser platforms. Alternatively, you can use a client-side control such as SoftArtisans XFileto handle your downloads.

Top

The TransferFile Method

FileUp's TransferFilemethod downloads a file from server to browser. TransferFile takes the parameter FileName - the path and name of the file to download. You can set FileName to either a virtual path or a physical path:

TransferFile with a physical path
`<% FileUp.TransferFile "c:\folder\sample.doc" %>`

TransferFile with a virtual path
`<% FileUp.TransferFile server.mappath("sample.doc") %>`

The NTFS permissions on the file to be downloaded must be set to allow "Read" access to the identity under which FileUp is running.

To download from a database, use FileUp's TransferBlobmethod.

Top

Setting Response Headers

To let the browser know how to handle a download, you must include three response headers in the download script:

Content-type
The file's MIME content-type, for example, "application/msword".
Content-disposition
If the file's content-disposition is set to "inline", the file will open in the browser. Depending on browser security settings, the user may be prompted with an "open or save" dialog. The user can choose to save to the file system, or open the file directly in the browser, if the browser supports a plug-in associated with that file type.

If content-disposition is set to "attachment", the browser will open a dialog that asks whether the user wants to open or save the downloaded file. In this situation, the user can either save the file to the file system or open the file in it's native application.

The content-disposition header also includes the file name.
Content-size
To display an accurate progress indicator when downloading, the browser has to know how many bytes to expect. The content-size header provides this information. In the following examples, we use SoftArtisans FileManagerto obtain the size of the file and set it in the content-size header.

Top

Downloading Large Files

Response buffering is enabled by default in ASP 3.0 and higher. This is not an ideal situation for downloading large files as the entire file will be placed in memory before it is sent to the browser. This may result in memory spikes on the server or the appearance that the browser is hanging, while it waits for the Response from the server.

It is recommended that you disable Response buffering on the page level on those pages that use FileUp to download files. This can be done as follows:

<% @Language="VBScript" %> <% Response.Buffer = False %>

Add this line near the top of your ASP page. It must occur before any HTML or Response.Write statements. When you disable Response buffering, remove any instances of Response.Clear or Response.Flush from your code as they will cause your script to fail.

Download and Open in the Browser

A download script should not include Response.Write statements or any HTML. If the response includes anything other than the file and response headers, the downloaded file will be corrupted.

The HTTP response's content-disposition header lets the browser know whether to open the downloaded file in the browser, or it's native application. This header also tells the browser the name of the downloaded file. If content-disposition is set to "inline" - as in the following example - the file will open in the browser, provided browser security settings allow this type of action.

<
'--- Instantiate the FileUp object 
Set downloadFile = Server.CreateObject("SoftArtisans.FileUp")

'--- Set the path and file name of the file we're going to transfer
                
strFilePath = Server.MapPath("../sample.doc")
strFileName = "sample.doc"

'--- Set response headers.
'--- FileUp is responsible for reading the file and sending
                    
'--- the raw bytes down to the client through the ASP Response.
                    
'--- For the browserto handle the data properly, the context
                    
'--- of the stream of bytes needs to be established.
                    
'--- This is done with HTTP response headers.

'--- ContentType tells the browser what kind of file is coming.
'--- Application/msword is a Microsoft Word document. 
Response.ContentType = "application/msword"

'--- Content-Disposition tells the browser how to handle the file,
                    
'--- and what the name of the file is. The "inline" option tells
                    
'--- the browser to open the Word doc in the browser. 
Response.AddHeader "Content-Disposition", "inline;filename=""" & strFileName
                & """"

'--- To get an accurate progress indicator when downloading,
'--- the browser has to know how many bytes to expect.
'--- Use SoftArtisans.FileManager to obtain the byte-size of the file
'--- and set it in the Content-Size header. 
Set fm = Server.CreateObject("SoftArtisans.FileManager")
Set file = fm.GetFile(strFilePath)
Response.AddHeader "Content-Size", file.Size

'--- Download the file. 
downloadFile.TransferFile strFilePath
%>

Top

Downloading and Open in the Native Application

A download script should not include Response.Write statements or any HTML. If the response includes anything other than the file and response headers, the downloaded file will be corrupted.

The HTTP response's content-disposition header lets the browser know whether to open the downloaded file in the browser, or open the file in the file's native application. If content-disposition is set to "attachment" - as in the following example - the browser will display a dialog that asks the user to open or save the file. Choosing "open" will result in the file being opened in its native application. Choosing "save" allows the user to save the file to the file system.

This header also tells the browser the name of the downloaded file.

<%
'--- Instantiate the FileUp object. 
Set downloadFile = Server.CreateObject("SoftArtisans.FileUp")

'--- Set the path and file name of the file we're going to transfer.
                
strFilePath = Server.MapPath("../sample.doc")
strFileName = "sample.doc"

'--- Set response headers.
'--- FileUp is responsible for reading the file and sending
                    
'--- the raw bytes down to the client through the ASP Response.
                    
'--- For the browser to handle the data properly, the context
                    
'--- of the stream of bytes needs to be established.
                    
'--- This is done with HTTP response headers.
                    

'--- ContentType tells the browser what kind of file is coming.
'--- Application/x-msdownload is a special type that
                    
'--- "should" prompt the user with a save-as dialog every time. 
Response.ContentType = "application/x-msdownload"

'--- Content-Disposition tells the browser how to
                    
'--- handle the file, and what the name
                    
'--- of the file is. 
Response.AddHeader "Content-Disposition", "attachment;filename=""" & strFileName
                & """"

'--- In order to get an accurate progress indicator when downloading,
'--- the browser has to know how many bytes to expect.
'--- Use SoftArtisans FileManager to obtain the byte-size of the file
'--- and set it in the Content-Size header 
Set fm = Server.CreateObject("SoftArtisans.FileManager")
Set file = fm.GetFile(strFilePath)
Response.AddHeader "Content-Size", file.Size

'--- Download the file. 
downloadFile.TransferFile strFilePath
%>

Top