README

   1 Coquelicot
   2 ==========
   3
   4 Coquelicot is a "one-click" file sharing web application with specific
   5 thoughts on protecting users privacy.
   6
   7 Basic principle: users can upload a file to the server, it return they
   8 get a unique URL which can be shared to others in order to download the
   9 file.
  10
  11 Coquelicot aims to protect, to some extents, users and system
  12 administrators from disclosure of the files exchanged from passive
  13 and not so active attackers.
  14
  15 Features
  16 --------
  17
  18  * Uploading a file is protected by a common password
  19
  20    In order to prevent random Internet users to eat bandwidth and disk
  21    space, uploading a file to share is protected by a common password.
  22
  23  * Mandatory expiration
  24
  25    When uploading, a time limit has to be specified. The file will be
  26    unavailable once this limit has been reached.
  27
  28    During a configurable period of time, trying to download the file
  29    will return a page saying "too late" instead of "not found".
  30
  31  * Support for one-time download
  32
  33    An user might want to allow exactly _one_ download of a file,
  34    to more closely replace an email attachment.
  35
  36  * Upload progress bar
  37
  38    If the web server tracks upload progress, users having javascript
  39    enabled will see a nice progress bar during the file upload.
  40
  41  * Downgrade nicely
  42
  43    The application works fine without javascript or CSS.
  44
  45  * Download URL are hand-writing compatible
  46
  47    URLs generated to download files uses the Base32 character set. This
  48    set is specifically designed to overcome misread of 'l', '1', '0' and
  49    'O' characters. Coquelicot will automatically convert case and
  50    ambiguous characters to facilitate URL exchanges through
  51    hand-writing.
  52
  53  * Files are stored encrypted on the server
  54
  55    Upon upload, files are written to the disk using symmetric
  56    encryption. The encryption key is _not_ stored directly by
  57    Coquelicot. It is either generated randomly and given as part of the
  58    download URL, or specified by the uploader.
  59
  60  * Download can be protected by a password
  61
  62    When uploading, a password can be specified which will be used as
  63    the encryption key. In order to download the file, the password
  64    must be entered through in a POST'ed form, preventing the password
  65    from appearing in the server logs.
  66
  67  * Files are stored with a random name
  68
  69    To prevent disclosure of the shared file name, it is stored encrypted
  70    together with the file content. On the server, this encrypted file is
  71    stored with a random name.
  72
  73  * Download URLs do not reflect stored file names
  74
  75    The random names given in download URLs do not map directly to file
  76    names on the server. This prevent server logs from giving a direct
  77    mapping to the shared files.
  78
  79  * File content is zero'ed before removal
  80
  81    When a file has expired, it is removed from the server. In order
  82    to make it harder to retrieve its content through filesystem
  83    analysis, it is filled with zeroes first.
  84
  85 Setup
  86 -----
  87
  88 Coquelicot is written in Ruby using the Sinatra web framework.
  89
  90 On Debian, one can fulfill its dependencies by issueing:
  91
  92     apt-get install libsinatra-ruby1.8 libopenssl-ruby1.8 \
  93                     libhaml-ruby1.8 liblockfile-ruby libgettext-ruby1.8 \
  94                     rake
  95
  96 Then create the translation catalog through:
  97
  98     rake makemo
  99
 100 Finally you need to figure out the best way to host a Rack application
 101 depending on your setup. *evil grin*
 102
 103 Test suite
 104 ----------
 105
 106 Coquelicot test suite is written using RSpec.
 107
 108 On Debian, you will need those extra packages:
 109
 110     apt-get install librspec-ruby1.8 libhpricot-ruby1.8
 111
 112 You will also need the unpackaged gems "timecop" and "rack-test".
 113
 114 Then, running the test suite is just a matter of typing:
 115
 116     spec test_coquelicot.rb
 117
 118 Future
 119 ------
 120
 121  * Integrate other authentication systems for uploads
 122
 123    A common password is a pretty limited authentication scheme.
 124    One could like to also configure no password or integrate with
 125    webmails or other authentication system.
 126
 127  * More flexible expiration
 128
 129    It might be interesting to also offer a calendar for specifying
 130    an exact date after which the file will be unavailable.
 131
 132  * Upper-bound expiration time
 133
 134    Malicious users could specify an arbitrary number of minutes before
 135    the file is expired. This should be limited by an upper-bound.
 136
 137  * Hide file size (padding)
 138
 139    There is currently a real close mapping from original file size to
 140    stored file size. Original file size will also be recorded in server
 141    logs. Padding could be used to improve this situation.
 142
 143  * Make a Gem
 144
 145    Most Ruby stuff is installed using Gem, so Coquelicot should be one.
 146
 147  * Package for Debian
 148
 149    A Debian package would be nice to spread Coquelicot setups.
 150
 151  * Describe more setups
 152
 153    Describe how to setup Coquelicot with mod_passenger, Mongrel and
 154    other webservers.
 155
 156 Storage details
 157 ---------------
 158
 159 Files are stored in the directory specified by the 'depot_path'
 160 setting.
 161
 162 The format is the following:
 163
 164     ---
 165     Coquelicot: "1.0"
 166     Salt: <8 bytes stored as Base64>
 167     Expire-at: <expiration time in seconds since epoch>
 168     ---
 169     <encrypted data>
 170
 171 Encryption is done using OpenSSL. Cipher is AES-256-CBC with key and IV
 172 created using the pbkdf2_hmac_sha1() implementation of PKCS5. The later
 173 is fead using the former 'Salt' and the given passphrase.
 174
 175 Once decrypted, content has the following format:
 176
 177     ---
 178     Created-at: <upload time in seconds since epoch>
 179     Filename: "<original file name>"
 180     Content-Type: "<MIME type>"
 181     Length: <file length is bytes>
 182     One-time-only: <true|false>
 183     ---
 184     <original bytes forming the file content>
 185
 186 Headers must be parseable using the YAML standard.
 187
 188 File are truncated to zero length when they are "expired".
 189
 190 In order to map download URLs to file name, a simple text file ".links"
 191 is used. It contains a line for each file in the form:
 192
 193     <URL name> <file name>
 194
 195 Authors
 196 -------
 197
 198 Coquelicot © 2010 potager.org <jardiniers@potager.org>
 199
 200 Coquelicot is distributed under the GNU Affero General Public License
 201 version 3. See LICENSE for details.