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  * Support for different authentication methods
  18
  19    It is possible to integrate your own authentication mechanisms. Such a
  20    mechanism, needs to implement a single method and provide some JS, as well
  21    as some template partial to render the common fields. For more information
  22    have a look at the notes below.
  23
  24  * Simplepass mechanism: Uploading a file is protected by a common password
  25
  26    In order to prevent random Internet users to eat bandwidth and disk
  27    space, uploading a file for sharing is protected by a common
  28    password.
  29
  30  * Mandatory expiration
  31
  32    When uploading, a time limit has to be specified. The file will be
  33    unavailable once this limit has been reached.
  34
  35    During a configurable period of time, trying to download the file
  36    will return a page saying "too late" instead of "not found".
  37
  38  * Support for one-time download
  39
  40    An user might want to allow exactly _one_ download of a file,
  41    to more closely replace an email attachment. The file will be removed after
  42    the first complete download and concurrent download are prevented.
  43
  44  * Upload progress bar
  45
  46    If the web server tracks upload progress, users having javascript
  47    enabled will see a nice progress bar during the file upload.
  48
  49  * Downgrade nicely
  50
  51    The application works fine without javascript or CSS.
  52
  53  * Download URL are hand-writing compatible
  54
  55    URLs generated to download files uses the Base32 character set. This
  56    set is specifically designed to overcome misread of 'l', '1', '0' and
  57    'O' characters. Coquelicot will automatically convert case and
  58    ambiguous characters to facilitate URL exchanges through
  59    hand-writing.
  60
  61  * Files are stored encrypted on the server
  62
  63    While being uploaded, files are written to the disk using symmetric
  64    encryption. The encryption key is _not_ stored directly by
  65    Coquelicot. It is either generated randomly and given as part of the
  66    download URL, or specified by the uploader.
  67
  68  * Download can be protected by a password
  69
  70    When uploading, a password can be specified which will be used as
  71    the encryption key. In order to download the file, the password
  72    must be entered through in a POST'ed form, preventing the password
  73    from appearing in the server logs.
  74
  75  * Files are stored with a random name
  76
  77    To prevent disclosure of the shared file name, it is stored encrypted
  78    together with the file content. On the server, this encrypted file is
  79    stored with a random name.
  80
  81  * Download URLs do not reflect stored file names
  82
  83    The random names given in download URLs do not map directly to file
  84    names on the server. This prevent server logs from giving a direct
  85    mapping to the shared files.
  86
  87  * File content is zero'ed before removal
  88
  89    When a file has expired, it is removed from the server. In order
  90    to make it harder to retrieve its content through filesystem
  91    analysis, it is filled with zeros first.
  92
  93 Setup
  94 -----
  95
  96 Coquelicot is written in Ruby using the Sinatra web framework.
  97
  98 On Debian, one can fulfill its dependencies by issuing:
  99
 100     apt-get install libsinatra-ruby1.8 libopenssl-ruby1.8 \
 101                     libhaml-ruby1.8 liblockfile-ruby libgettext-ruby1.8 \
 102                     rake
 103
 104 Then create the translation catalog through:
 105
 106     rake makemo
 107
 108 Finally you need to figure out the best way to host a Rack application
 109 depending on your setup. *evil grin*
 110
 111 Coquelicot is intended to be run on a fully encrypted system and accessible
 112 only through HTTPS.
 113
 114 Test suite
 115 ----------
 116
 117 Coquelicot test suite is written using RSpec.
 118
 119 On Debian, you will need those extra packages:
 120
 121     apt-get install librspec-ruby1.8 libhpricot-ruby1.8
 122
 123 You will also need the unpackaged gems "timecop" and "rack-test".
 124
 125 Then, running the test suite is just a matter of typing:
 126
 127     spec test_coquelicot.rb
 128
 129 Migrate from Jyraphe
 130 --------------------
 131
 132 Jyraphe [1] is another free software web file sharing application.
 133 Coquelicot provides a migration script to import Jyraphe 0.5 repositories in
 134 `tools/migrate_jyraphe.rb`.
 135
 136 [1] http://home.gna.org/jyraphe/
 137
 138 Future
 139 ------
 140
 141  * Read settings from a configuration file.
 142
 143    Currently settings, such as the authentication mechanism and its options
 144    need to be specified within the application. Coquelicot should load its
 145    settings from a configuration file.
 146
 147  * More flexible expiration
 148
 149    It might be interesting to also offer a calendar for specifying
 150    an exact date after which the file will be unavailable.
 151
 152  * Hide file size (padding)
 153
 154    There is currently a real close mapping from original file size to
 155    stored file size. Original file size will also be recorded in server
 156    logs. Padding could be used to improve this situation.
 157
 158  * Make a Gem
 159
 160    Most Ruby stuff is installed using Gem, so Coquelicot should be one.
 161
 162  * Package for Debian
 163
 164    A Debian package would be nice to spread Coquelicot setups.
 165
 166  * Describe more setups
 167
 168    Describe how to setup Coquelicot with mod_passenger, Mongrel and
 169    other webservers.
 170
 171 Storage details
 172 ---------------
 173
 174 Files are stored in the directory specified by the 'depot_path'
 175 setting.
 176
 177 The format is the following:
 178
 179     ---
 180     Coquelicot: "1.0"
 181     Salt: <8 bytes stored as Base64>
 182     Expire-at: <expiration time in seconds since epoch>
 183     ---
 184     <encrypted data>
 185
 186 Encryption is done using OpenSSL. Cipher is AES-256-CBC with key and IV
 187 created using the pbkdf2_hmac_sha1() implementation of PKCS5. The later
 188 is fed using the former 'Salt' and the given passphrase.
 189
 190 Once decrypted, content has the following format:
 191
 192     ---
 193     Created-at: <upload time in seconds since epoch>
 194     Filename: "<original file name>"
 195     Content-Type: "<MIME type>"
 196     Length: <file length is bytes>
 197     One-time-only: <true|false>
 198     ---
 199     <original bytes forming the file content>
 200
 201 Headers must be parseable using the YAML standard.
 202
 203 File are truncated to zero length when they are "expired".
 204
 205 In order to map download URLs to file name, a simple text file ".links"
 206 is used. It contains a line for each file in the form:
 207
 208     <URL name> <file name>
 209
 210 Authentication Mechanisms
 211 -------------------------
 212
 213 It is possible to authenticate users against your own common authentication
 214 mechanism.
 215
 216 Such an authentication mechanism needs to provide the following 3 files:
 217
 218 * lib/coquelicot/auth/METHOD.rb
 219 * public/javascripts/coquelicot.auth.METHOD.js
 220 * views/auth/METHOD.haml
 221
 222 Their responsibilities are as followed:
 223
 224 lib/coquelicot/auth/METHOD.rb:
 225
 226 A module implementing the actual authentication. This module must
 227 implement one method called `authenticate` which will get all the
 228 parameters as an argument. To simplify your interaction with the field
 229 `upload_token`, that might be serialized as json, we deserialize it prior
 230 to passing it to the `authenticate` method.
 231
 232 public/javascripts/coquelicot.auth.METHOD.js:
 233
 234 We expect 2 javascript methods in that file:
 235
 236 * authenticationData(): Return a hash of all the necessary data to
 237                         authenticate on the app side.
 238 * authenticationFocus(): Set the focus on the first authentication form
 239                          field
 240
 241 views/auth/METHOD.haml:
 242
 243 Render the necessary form fields that will be used for authentication.
 244
 245 The authentication method can be set in the application settings
 246 including mandatory options for this method.
 247
 248 Authors
 249 -------
 250
 251 Coquelicot © 2010 potager.org <jardiniers@potager.org>
 252
 253 Coquelicot is distributed under the GNU Affero General Public License
 254 version 3. See LICENSE for details.