README

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