Add configuration mechanism
[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  * 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                     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 Test suite
144 ----------
145
146 Coquelicot test suite is written using RSpec.
147
148 On Debian, you will need those extra packages:
149
150     apt-get install librspec-ruby1.8 libhpricot-ruby1.8
151
152 You will also need the unpackaged gems "timecop" and "rack-test".
153
154 Then, running the test suite is just a matter of typing:
155
156     spec test_coquelicot.rb
157
158 Migrate from Jyraphe
159 --------------------
160
161 Jyraphe [1] is another free software web file sharing application.
162 Coquelicot provides a migration script to import Jyraphe 0.5 repositories in
163 `tools/migrate_jyraphe.rb`.
164
165 [1] http://home.gna.org/jyraphe/
166
167 Future
168 ------
169
170  * More flexible expiration
171
172    It might be interesting to also offer a calendar for specifying
173    an exact date after which the file will be unavailable.
174
175  * Hide file size (padding)
176
177    There is currently a real close mapping from original file size to
178    stored file size. Original file size will also be recorded in server
179    logs. Padding could be used to improve this situation.
180
181  * Make a Gem
182
183    Most Ruby stuff is installed using Gem, so Coquelicot should be one.
184
185  * Package for Debian
186
187    A Debian package would be nice to spread Coquelicot setups.
188
189  * Describe more setups
190
191    Describe how to setup Coquelicot with mod_passenger, Mongrel and
192    other webservers.
193
194 Storage details
195 ---------------
196
197 Files are stored in the directory specified by the 'depot_path'
198 setting.
199
200 The format is the following:
201
202     --- 
203     Coquelicot: "1.0"
204     Salt: <8 bytes stored as Base64>
205     Expire-at: <expiration time in seconds since epoch>
206     --- 
207     <encrypted data>
208
209 Encryption is done using OpenSSL. Cipher is AES-256-CBC with key and IV
210 created using the pbkdf2_hmac_sha1() implementation of PKCS5. The later
211 is fed using the former 'Salt' and the given passphrase.
212
213 Once decrypted, content has the following format:
214
215     --- 
216     Created-at: <upload time in seconds since epoch>
217     Filename: "<original file name>"
218     Content-Type: "<MIME type>"
219     Length: <file length is bytes>
220     One-time-only: <true|false>
221     --- 
222     <original bytes forming the file content>
223
224 Headers must be parseable using the YAML standard.
225
226 File are truncated to zero length when they are "expired".
227
228 In order to map download URLs to file name, a simple text file ".links"
229 is used. It contains a line for each file in the form:
230
231     <URL name> <file name>
232
233 Authentication Mechanisms
234 -------------------------
235
236 It is possible to authenticate users against your own common authentication
237 mechanism.
238
239 Such an authentication mechanism needs to provide the following 3 files:
240     
241 * lib/coquelicot/auth/METHOD.rb
242 * public/javascripts/coquelicot.auth.METHOD.js
243 * views/auth/METHOD.haml
244     
245 Their responsibilities are as followed:
246     
247 lib/coquelicot/auth/METHOD.rb:
248     
249 A module implementing the actual authentication. This module must
250 implement one method called `authenticate` which will get all the
251 parameters as an argument. To simplify your interaction with the field 
252 `upload_token`, that might be serialized as json, we deserialize it prior
253 to passing it to the `authenticate` method.
254     
255 public/javascripts/coquelicot.auth.METHOD.js:
256     
257 We expect 2 javascript methods in that file:
258     
259 * authenticationData(): Return a hash of all the necessary data to
260                         authenticate on the app side.
261 * authenticationFocus(): Set the focus on the first authentication form
262                          field
263     
264 views/auth/METHOD.haml:
265     
266 Render the necessary form fields that will be used for authentication.
267     
268 The authentication method can be set in the application settings
269 including mandatory options for this method.
270
271 Authors
272 -------
273
274 Coquelicot © 2010 potager.org <jardiniers@potager.org>
275 mh © 2011 immerda.ch <mh+coquelicot@immerda.ch>
276
277 Coquelicot is distributed under the GNU Affero General Public License
278 version 3. See LICENSE for details.