4 Coquelicot is a "one-click" file sharing web application with a specific
5 focus on protecting users' privacy.
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
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.
18 * Support for different authentication methods
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:
24 - "simplepass": users will need to provide a global, pre-shared,
26 - "imap": users will need to provide a login and a password,
27 those credentials will be used to authenticate against an existing
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
35 * Mandatory expiration
37 When uploading, a time limit has to be specified. The file will be
38 unavailable once this limit has been reached.
40 During a configurable period of time, trying to download the file
41 will return a page saying "too late" instead of "not found".
43 * Support for one-time download
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.
51 If the web server tracks upload progress, users having javascript
52 enabled will see a nice progress bar during the file upload.
56 The application works fine without javascript or CSS.
58 * Download URL are hand-writing compatible
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
66 * Files are stored encrypted on the server
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.
73 * Download can be protected by a password
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.
80 * Files are stored with a random name
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.
86 * Download URLs do not reflect stored file names
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.
92 * File content is zero'ed before removal
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.
101 Coquelicot is written in Ruby using the Sinatra web framework.
103 On Debian, one can fulfill its dependencies by issuing:
105 apt-get install libsinatra-ruby1.8 libopenssl-ruby1.8 \
106 libhaml-ruby1.8 liblockfile-ruby libgettext-ruby1.8 \
109 Then create the translation catalog through:
113 Finally you need to figure out the best way to host a Rack application
114 depending on your setup. *evil grin*
116 Coquelicot is intended to be run on a fully encrypted system and accessible
122 By default Coquelicot is configured to authenticate with the
123 "simplepass" mechanism and some other reasonable defaults.
125 It is possible to overwrite these settings from a configuration file
126 named `settings.yml` that will be used if it is present in the `conf`
127 directory of the application.
129 All available settings with their default values are documented in
130 `conf/settings-default.yml`.
132 Further settings example:
134 * `conf/settings-simplepass.yml`: shows how to change the default
135 password for the "simplepass" mechanism.
137 * `conf/settings-imap.yml`: necessary configuration for the "imap"
138 authentication mechanism.
140 You can copy one of these examples to `conf/settings.yml` and adjust them
141 according to your environment.
146 To cleanup files automatically when they expired, coquelicot comes with
147 a cleanup script, that does the garbage collection for you. The easiest
148 way is to add `ext/coquelicot_gc.rb` as a cron job that runs every 5
154 Coquelicot test suite is written using RSpec.
156 On Debian, you will need those extra packages:
158 apt-get install librspec-ruby1.8 libhpricot-ruby1.8
160 You will also need the unpackaged gems "timecop" and "rack-test".
162 Then, running the test suite is just a matter of typing:
164 spec spec/coquelicot_spec.rb
169 Jyraphe [1] is another free software web file sharing application.
170 Coquelicot provides a migration script to import Jyraphe 0.5 repositories in
171 `tools/migrate_jyraphe.rb`.
173 [1] http://home.gna.org/jyraphe/
178 * More flexible expiration
180 It might be interesting to also offer a calendar for specifying
181 an exact date after which the file will be unavailable.
183 * Hide file size (padding)
185 There is currently a real close mapping from original file size to
186 stored file size. Original file size will also be recorded in server
187 logs. Padding could be used to improve this situation.
191 Most Ruby stuff is installed using Gem, so Coquelicot should be one.
195 A Debian package would be nice to spread Coquelicot setups.
197 * Describe more setups
199 Describe how to setup Coquelicot with mod_passenger, Mongrel and
205 Files are stored in the directory specified by the 'depot_path'
208 The format is the following:
212 Salt: <8 bytes stored as Base64>
213 Expire-at: <expiration time in seconds since epoch>
217 Encryption is done using OpenSSL. Cipher is AES-256-CBC with key and IV
218 created using the pbkdf2_hmac_sha1() implementation of PKCS5. The later
219 is fed using the former 'Salt' and the given passphrase.
221 Once decrypted, content has the following format:
224 Created-at: <upload time in seconds since epoch>
225 Filename: "<original file name>"
226 Content-Type: "<MIME type>"
227 Length: <file length is bytes>
228 One-time-only: <true|false>
230 <original bytes forming the file content>
232 Headers must be parseable using the YAML standard.
234 File are truncated to zero length when they are "expired".
236 In order to map download URLs to file name, a simple text file ".links"
237 is used. It contains a line for each file in the form:
239 <URL name> <file name>
241 Authentication Mechanisms
242 -------------------------
244 It is possible to authenticate users against your own common authentication
247 Such an authentication mechanism needs to provide the following 3 files,
248 with the following responsabilities:
250 * `lib/coquelicot/auth/<METHOD>.rb`:
252 A module implementing the actual authentication. This module must
253 implement one method called `authenticate` which will get all the
254 parameters as an argument. To simplify your interaction with the
255 field `upload_token`, that might be serialized as json, we
256 deserialize it prior to passing it to the `authenticate` method.
258 * `public/javascripts/coquelicot.auth.<METHOD>.js:`
260 We expect 2 javascript methods in that file:
262 - `authenticationData()`: returns a hash of all the necessary data
263 to authenticate on the app side.
264 - `authenticationFocus()`: set the focus on the first authentication
267 * `views/auth/<METHOD>.haml`:
269 Render the necessary form fields that will be used for authentication.
271 The authentication method can be set in the application settings
272 including mandatory options for this method.
277 Coquelicot © 2010-2012 potager.org <jardiniers@potager.org>
278 © 2011 mh / immerda.ch <mh+coquelicot@immerda.ch>
280 Coquelicot is distributed under the GNU Affero General Public License
281 version 3. See LICENSE for details.