move Coquelicot::Depot to its own file
[coquelicot.git] / 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 Then create the translation catalog through:
110
111     rake makemo
112
113 Finally you need to figure out the best way to host a Rack application
114 depending on your setup. *evil grin*
115
116 Coquelicot is intended to be run on a fully encrypted system and accessible
117 only through HTTPS.
118
119 Configuration
120 -------------
121
122 By default Coquelicot is configured to authenticate with the
123 "simplepass" mechanism and some other reasonable defaults.
124
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.
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
135    password for the "simplepass" mechanism.
136
137  * `conf/settings-imap.yml`: necessary configuration for the "imap"
138    authentication mechanism.
139
140 You can copy one of these examples to `conf/settings.yml` and adjust them
141 according to your environment.
142
143 Garbage collection
144 ------------------
145
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
149 minutes (or so).
150
151 Test and development
152 --------------------
153
154 As Coquelicot uses Bundle, the first step to work on Coquelicot
155 is installing the proper dependencies by issuing:
156
157     bundle install
158
159 Coquelicot test suite is written using RSpec. Running the test suite is just a
160 matter of typing:
161
162     bundle exec rspec
163
164 To update the translation source files, use:
165
166     bundle exec rake updatepo
167
168 This will update `po/coquelicot.pot` and merge the new strings in the various
169 `po/*/coquelicot.po` files.
170
171 Migrate from Jyraphe
172 --------------------
173
174 Jyraphe [1] is another free software web file sharing application.
175 Coquelicot provides a migration script to import Jyraphe 0.5 repositories in
176 `tools/migrate_jyraphe.rb`.
177
178 [1] http://home.gna.org/jyraphe/
179
180 Future
181 ------
182
183  * More flexible expiration
184
185    It might be interesting to also offer a calendar for specifying
186    an exact date after which the file will be unavailable.
187
188  * Hide file size (padding)
189
190    There is currently a real close mapping from original file size to
191    stored file size. Original file size will also be recorded in server
192    logs. Padding could be used to improve this situation.
193
194  * Make a Gem
195
196    Most Ruby stuff is installed using Gem, so Coquelicot should be one.
197
198  * Package for Debian
199
200    A Debian package would be nice to spread Coquelicot setups.
201
202  * Describe more setups
203
204    Describe how to setup Coquelicot with mod_passenger, Mongrel and
205    other webservers.
206
207 Storage details
208 ---------------
209
210 Files are stored in the directory specified by the 'depot_path'
211 setting.
212
213 The format is the following:
214
215     --- 
216     Coquelicot: "1.0"
217     Salt: <8 bytes stored as Base64>
218     Expire-at: <expiration time in seconds since epoch>
219     --- 
220     <encrypted data>
221
222 Encryption is done using OpenSSL. Cipher is AES-256-CBC with key and IV
223 created using the pbkdf2_hmac_sha1() implementation of PKCS5. The later
224 is fed using the former 'Salt' and the given passphrase.
225
226 Once decrypted, content has the following format:
227
228     --- 
229     Created-at: <upload time in seconds since epoch>
230     Filename: "<original file name>"
231     Content-Type: "<MIME type>"
232     Length: <file length is bytes>
233     One-time-only: <true|false>
234     --- 
235     <original bytes forming the file content>
236
237 Headers must be parseable using the YAML standard.
238
239 File are truncated to zero length when they are "expired".
240
241 In order to map download URLs to file name, a simple text file ".links"
242 is used. It contains a line for each file in the form:
243
244     <URL name> <file name>
245
246 Authentication Mechanisms
247 -------------------------
248
249 It is possible to authenticate users against your own common authentication
250 mechanism.
251
252 Such an authentication mechanism needs to provide the following 3 files,
253 with the following responsabilities:
254
255  * `lib/coquelicot/auth/<METHOD>.rb`:
256
257    A class implementing the actual authentication. This class must
258    implement one method called `authenticate` which will get all the
259    parameters as an argument. To simplify your interaction with the
260    field `upload_token`, that might be serialized as json, we
261    deserialize it prior to passing it to the `authenticate` method.
262
263  * `public/javascripts/coquelicot.auth.<METHOD>.js:`
264
265     We expect 2 javascript methods in that file:
266
267     - `authenticationData()`: returns a hash of all the necessary data
268       to authenticate on the app side.
269     - `authenticationFocus()`: set the focus on the first authentication
270       form field.
271
272  * `views/auth/<METHOD>.haml`:
273
274    Render the necessary form fields that will be used for authentication.
275
276    The authentication method can be set in the application settings
277    including mandatory options for this method.
278
279 Authors
280 -------
281
282 Coquelicot © 2010-2012 potager.org <jardiniers@potager.org>
283            © 2011 mh / immerda.ch <mh+coquelicot@immerda.ch>
284
285 Coquelicot is distributed under the GNU Affero General Public License
286 version 3. See LICENSE for details.