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