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