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