bdfu 1.0.3

# bdfu: a “brain dead”-simple file upload server

[](https://travis-ci.org/rjw57/bdfu)

BDFU is designed to solve the single problem of letting one or more users upload files to some server in an authenticated manner. Specifically, the following simplifications are made:

• The users may not choose the filename of the uploaded file; each file is named with a [UUID](http://en.wikipedia.org/wiki/Universally_unique_identifier).

• Users may not access the files once uploaded. Allowing users read-access to the uploaded files is an orthogonal problem.

• Users are authenticated with finite-lifetime [JWT](http://jwt.io/) tokens which may be issued manually or automatically.

• The server requires nothing more than Python and a CGI-capable web-server although is available as a [WSGI](http://en.wikipedia.org/wiki/Web_Server_Gateway_Interface) application for greater performance.

## Installation

Installation is done via pip or easy_install:

`console $ pip install bdfu `

The development version may be installed directly from this repository:

`console $ pip install -e git+https://github.com/rjw57/bdfu#egg=bdfu `

## Configuration

There is an [example configuration](examples/simple-server.cfg) shipped with the source code to bdfu. A simplified version is below:

`python # Save this as simple-server.cfg JWT_SECRET_KEY = 'supersecret' STORAGE_DIR = '/tmp/bdfu-storage-example' `

The configuration file is itself a Python script and so one may calculate the values of any of these options.

In production, one can tell BDFU about this file by setting the environment variable BDFU_SETTINGS to the absolute path of the configuration file.

## Getting started

Firstly, run the example server with the example configuration:

`console $ bdfu server /path/to/simple-server.cfg `

This will cause the server to run on http://localhost:8080/. Now, generate a token for the “sally” user:

`console $ bdfu gen-token sally supersecret >token-sally.txt `

This token is, by default, set to expire one minute after generation. The expiry time can be set via the --expires-in option to bdfu gen-token.

Try uploading a 1K file of random data:

`console $ dd if=/dev/urandom of=test-file.bin bs=1024 count=1 $ bdfu upload http://localhost:8080/ `cat token-sally.txt` test-file.bin ecbfb21578ad49548472d955b38ac65b `

The string output by the bdfu upload is a unique ID for that file. The file is uploaded to $STORAGE_DIR/$USER/$FILE_ID which we can check:

`console $ ls /tmp/bdfu-storage-example/sally/ ecbfb21578ad49548472d955b38ac65b $ diff -qs /tmp/bdfu-storage-example/sally/ecbfb21578ad49548472d955b38ac65b test-file.bin Files /tmp/bdfu-storage-example/sally/ecbfb21578ad49548472d955b38ac65b and test-file.bin are identical `

## Token generation

In addition to the bdfu gen-token command, there is a [standalone example](examples/make-token.py) shipped with the source. Token generation can be performed by anyone in possession of the server secret. Tokens are standard [JWT](http://jwt.io) tokens. Indeed, one can paste the tokens generated by bdfu gen-token into the JWT website to see their structure yourself.

Tokens may either be generated manually by server administrators and given to users or they may be generated automatically by some gateway in possession of the secret. For example, a particular institution may wrap a token-generator in a web application which is protected by an existing identity provider. Similarly administrators are free to choose the expiry time for the tokens on a per-user basis using whichever policy they see fit.

## Server Deployment

### WSGI

The BDFU web application is exposed as a standard WSGI application suitable for running via mod_wsgi in Apache or similar. There is a [standalone server](examples/simple-server.py) example shipped with the source code.

The application requires that the HTTP Authorization header be passed on by the web server. This may not be the default configuration of your server. For example, the Apache web server will require the following directive:

` WSGIPassAuthorization On `

### CGI

There is an example [CGI wrapper script](examples/cgi-bin/bdfu) shipped with the source.

The application requires that the HTTP Authorization header be passed on by the web server to the CGI script. This may not be the default configuration of your server. For example, the Apache web server will require the following directives:

` RewriteEngine on RewriteCond %{HTTP:Authorization} ^(.*) RewriteRule .* - [e=HTTP_AUTHORIZATION:%1] `

## Security considerations

As a “brain dead” solution, BDFU aims to be very simple in its security model; anyone with access to the server secret can generate tokens and must be trusted. For example, no attempt is made to sanitise usernames with respect to path separators, etc. A foolish server administrator is free to create a user called ../../../../etc/passwd if they wish. BDFU assumes the server administrator knows what they’re doing.

In general, BDFU aims to be secure up to the point where the token has been validated but assumes that the claims within the token have not been generated by an adversary.