Coquelicot ========== Coquelicot is a "one-click" file sharing web application with a specific focus on protecting users' privacy. Basic principle: users can upload a file to the server, in return they get a unique URL which can be shared with others in order to download the file. Coquelicot aims to protect, to some extent, users and system administrators from disclosure of the files exchanged from passive and not so active attackers. Features -------- * Support for different authentication methods In order to prevent random Internet users to eat bandwidth and disk space, Coquelicot limits upload to authenticated users. It currently ships with two authentication mechanisms: - "simplepass": users will need to provide a global, pre-shared, password; - "imap": users will need to provide a login and a password, those credentials will be used to authenticate against an existing IMAP server. It is possible to integrate more authentication mechanisms by implementing a single method, some Javascript, and a template partial to render the common fields. For more information have a look at the notes below. * Mandatory expiration When uploading, a time limit has to be specified. The file will be unavailable once this limit has been reached. During a configurable period of time, trying to download the file will return a page saying "too late" instead of "not found". * Support for one-time download An user might want to allow exactly _one_ download of a file, to more closely replace an email attachment. The file will be removed after the first complete download and concurrent downloads are prevented. * Upload progress bar If the web server tracks upload progress, users having javascript enabled will see a nice progress bar during the file upload. * Downgrade nicely The application works fine without javascript or CSS. * Download URL are hand-writing compatible URLs generated to download files uses the Base32 character set. This set is specifically designed to overcome misread of 'l', '1', '0' and 'O' characters. Coquelicot will automatically convert case and ambiguous characters to facilitate URL exchanges through hand-writing. * Files are stored encrypted on the server While being uploaded, files are written to the disk using symmetric encryption. The encryption key is _not_ stored directly by Coquelicot. It is either generated randomly and given as part of the download URL, or specified by the uploader. * Download can be protected by a password When uploading, a password can be specified which will be used as the encryption key. In order to download the file, the password must be entered through in a POST'ed form, preventing the password from appearing in the server logs. * Files are stored with a random name To prevent disclosure of the shared file name, it is stored encrypted together with the file content. On the server, this encrypted file is stored with a random name. * Download URLs do not reflect stored file names The random names given in download URLs do not map directly to file names on the server. This prevent server logs from giving a direct mapping to the shared files. * File content is zero'ed before removal When a file has expired, it is removed from the server. In order to make it harder to retrieve its content through filesystem analysis, it is filled with zeros first. Setup ----- Coquelicot is written in Ruby using the Sinatra web framework. On Debian, one can fulfill its dependencies by issuing: apt-get install libsinatra-ruby1.8 libopenssl-ruby1.8 \ libhaml-ruby1.8 liblockfile-ruby libgettext-ruby1.8 \ libjson-ruby1.8 rake Finally you need to figure out the best way to host a Rack application depending on your setup. *evil grin* Coquelicot is intended to be run on a fully encrypted system and accessible only through HTTPS. Configuration ------------- By default Coquelicot is configured to authenticate with the "simplepass" mechanism and some other reasonable defaults. It is possible to overwrite these settings from a configuration file named `settings.yml` that will be used if it is present in the `conf` directory of the application. All available settings with their default values are documented in `conf/settings-default.yml`. Further settings example: * `conf/settings-simplepass.yml`: shows how to change the default password for the "simplepass" mechanism. * `conf/settings-imap.yml`: necessary configuration for the "imap" authentication mechanism. You can copy one of these examples to `conf/settings.yml` and adjust them according to your environment. Garbage collection ------------------ To cleanup files automatically when they expired, coquelicot comes with a cleanup script, that does the garbage collection for you. The easiest way is to add `ext/coquelicot_gc.rb` as a cron job that runs every 5 minutes (or so). Test and development -------------------- As Coquelicot uses Bundle, the first step to work on Coquelicot is installing the proper dependencies by issuing: bundle install Coquelicot test suite is written using RSpec. Running the test suite is just a matter of typing: bundle exec rspec To update the translation source files, use: bundle exec rake updatepo This will update `po/coquelicot.pot` and merge the new strings in the various `po/*/coquelicot.po` files. Migrate from Jyraphe -------------------- Jyraphe [1] is another free software web file sharing application. Coquelicot provides a migration script to import Jyraphe 0.5 repositories in `tools/migrate_jyraphe.rb`. [1] http://home.gna.org/jyraphe/ Future ------ * More flexible expiration It might be interesting to also offer a calendar for specifying an exact date after which the file will be unavailable. * Hide file size (padding) There is currently a real close mapping from original file size to stored file size. Original file size will also be recorded in server logs. Padding could be used to improve this situation. * Make a Gem Most Ruby stuff is installed using Gem, so Coquelicot should be one. * Package for Debian A Debian package would be nice to spread Coquelicot setups. * Describe more setups Describe how to setup Coquelicot with mod_passenger, Mongrel and other webservers. Storage details --------------- Files are stored in the directory specified by the 'depot_path' setting. The format is the following: --- Coquelicot: "1.0" Salt: <8 bytes stored as Base64> Expire-at: --- Encryption is done using OpenSSL. Cipher is AES-256-CBC with key and IV created using the pbkdf2_hmac_sha1() implementation of PKCS5. The later is fed using the former 'Salt' and the given passphrase. Once decrypted, content has the following format: --- Created-at: Filename: "" Content-Type: "" Length: One-time-only: --- Headers must be parseable using the YAML standard. File are truncated to zero length when they are "expired". In order to map download URLs to file name, a simple text file ".links" is used. It contains a line for each file in the form: Authentication Mechanisms ------------------------- It is possible to authenticate users against your own common authentication mechanism. Such an authentication mechanism needs to provide the following 3 files, with the following responsabilities: * `lib/coquelicot/auth/.rb`: A class implementing the actual authentication. This class must implement an `authenticate` method. It will receive the form fields as usual (params). This method should either return true if upload should be allowed. * `public/javascripts/coquelicot.auth..js:` This file should define 'authentication' as an object with the following methods: - `getData()`: returns an object of all the necessary data to authenticate on the app side. Keys should have the same name as the input fields used to authenticate without Javascript. - `focus()`: set the focus on the first authentication form field. - (optional) `handleSuccess()`: arbitrary action upon successful authentication. This is called after the livebox is closed. - (optional) `handleReject()`: arbitrary action when access get rejected. One can reset authentication fields after a failed authentication. - (optional) `handleFailure()`: arbitrary action when there was a problem in the authentication procedure. * `views/auth/.haml`: Render the necessary form fields that will be used for authentication. The authentication method can be set in the application settings including mandatory options for this method. Authors ------- Coquelicot © 2010-2012 potager.org © 2011 mh / immerda.ch Coquelicot is distributed under the GNU Affero General Public License version 3. See LICENSE for details. Background image (`public/images/background.jpg`) derived from: "coquelicot" © 2008 Jean-Louis Zimmermann Licensed under Creative Commons Attributions 2.0 Generic