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