Metadata-Version: 1.0
Name: bdfu
Version: 1.0.3
Summary: A "brain dead"-simple file upload server
Home-page: UNKNOWN
Author: UNKNOWN
Author-email: UNKNOWN
License: UNKNOWN
Description: # bdfu: a "brain dead"-simple file upload server
        
        [![Build Status](https://travis-ci.org/rjw57/bdfu.svg?branch=master)](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.
        
        
Platform: UNKNOWN
