Get nicer behaviour wrt. '410 Gone' and expiration
[coquelicot.git] / README
1 Coquelicot
2 ==========
3
4 Coquelicot is a "one-click" file sharing web application with specific
5 thoughts on protecting users privacy.
6
7 Basic principle: users can upload a file to the server, it return they
8 get a unique URL which can be shared to others in order to download the
9 file.
10
11 Coquelicot aims to protect, to some extents, users and system
12 administrators from disclosure of the files exchanged from passive
13 and not so active attackers.
14
15 Features
16 --------
17
18  * Uploading a file is protected by a common password
19
20    In order to prevent random Internet users to eat bandwidth and disk
21    space, uploading a file to share is protected by a common password.
22
23  * Mandatory expiration
24
25    When uploading, a time limit has to be specified. The file will be
26    unavailable once this limit has been reached.
27
28    During a configurable period of time, trying to download the file
29    will return a page saying "too late" instead of "not found".
30
31  * Upload progress bar
32
33    If the web server tracks upload progress, users having javascript
34    enabled will see a nice progress bar during the file upload.
35
36  * Downgrade nicely
37
38    The application works fine without javascript or CSS.
39
40  * Download URL are hand-writing compatible
41
42    URLs generated to download files uses the Base32 character set. This
43    set is specifically designed to overcome misread of 'l', '1', '0' and
44    'O' characters. Coquelicot will automatically convert case and
45    ambiguous characters to facilitate URL exchanges through
46    hand-writing.
47
48  * Files are stored encrypted on the server
49
50    Upon upload, files are written to the disk using symmetric
51    encryption. The encryption key is _not_ stored directly by
52    Coquelicot. It is either generated randomly and given as part of the
53    download URL, or specified by the uploader.
54
55  * Download can be protected by a password
56
57    When uploading, a password can be specified which will be used as
58    the encryption key. In order to download the file, the password
59    must be entered through in a POST'ed form, preventing the password
60    from appearing in the server logs.
61
62  * Files are stored with a random name
63
64    To prevent disclosure of the shared file name, it is stored encrypted
65    together with the file content. On the server, this encrypted file is
66    stored with a random name.
67
68  * Download URLs do not reflect stored file names
69
70    The random names given in download URLs do not map directly to file
71    names on the server. This prevent server logs from giving a direct
72    mapping to the shared files.
73
74  * File content is zero'ed before removal
75
76    When a file has expired, it is removed from the server. In order
77    to make it harder to retrieve its content through filesystem
78    analysis, it is filled with zeroes first.
79
80 Setup
81 -----
82
83 Coquelicot is written in Ruby using the Sinatra web framework.
84
85 On Debian, one can fulfill its dependencies by issueing:
86
87     apt-get install libsinatra-ruby1.8 libopenssl-ruby1.8 \
88                     libhaml-ruby1.8 liblockfile-ruby libgettext-ruby1.8 \
89                     rake
90
91 Then create the translation catalog through:
92
93     rake makemo
94
95 Finally you need to figure out the best way to host a Rack application
96 depending on your setup. *evil grin*
97
98 Test suite
99 ----------
100
101 Coquelicot test suite is written using RSpec.
102
103 On Debian, you will need those extra packages:
104
105     apt-get install librspec-ruby1.8 libhpricot-ruby1.8
106
107 You will also need the unpackaged gems "timecop" and "rack-test".
108
109 Then, running the test suite is just a matter of typing:
110
111     spec test_coquelicot.rb
112
113 Future
114 ------
115
116  * Integrate other authentication systems for uploads
117
118    A common password is a pretty limited authentication scheme.
119    One could like to also configure no password or integrate with
120    webmails or other authentication system.
121
122  * One-time download
123
124    An user might want to allow exactly _one_ download of a file,
125    to more closely replace an email attachment.
126
127  * More flexible expiration
128
129    It might be interesting to also offer a calendar for specifying
130    an exact date after which the file will be unavailable.
131
132  * Upper-bound expiration time
133
134    Malicious users could specify an arbitrary number of minutes before
135    the file is expired. This should be limited by an upper-bound.
136
137  * Hide file size (padding)
138
139    There is currently a real close mapping from original file size to
140    stored file size. Original file size will also be recorded in server
141    logs. Padding could be used to improve this situation.
142
143  * Make a Gem
144
145    Most Ruby stuff is installed using Gem, so Coquelicot should be one.
146
147  * Package for Debian
148
149    A Debian package would be nice to spread Coquelicot setups.
150
151  * Describe more setups
152
153    Describe how to setup Coquelicot with mod_passenger, Mongrel and
154    other webservers.
155
156 Storage details
157 ---------------
158
159 Files are stored in the directory specified by the 'depot_path'
160 setting.
161
162 The format is the following:
163
164     --- 
165     Coquelicot: "1.0"
166     Salt: <8 bytes stored as Base64>
167     Expire-at: <expiration time in seconds since epoch>
168     --- 
169     <encrypted data>
170
171 Encryption is done using OpenSSL. Cipher is AES-256-CBC with key and IV
172 created using the pbkdf2_hmac_sha1() implementation of PKCS5. The later
173 is fead using the former 'Salt' and the given passphrase.
174
175 Once decrypted, content has the following format:
176
177     --- 
178     Created-at: <upload time in seconds since epoch>
179     Filename: "<original file name>"
180     Content-Type: "<MIME type>"
181     Length: <file length is bytes>
182     --- 
183     <original bytes forming the file content>
184
185 Headers must be parseable using the YAML standard.
186
187 File are truncated to zero length when they are "expired".
188
189 In order to map download URLs to file name, a simple text file ".links"
190 is used. It contains a line for each file in the form:
191
192     <URL name> <file name>
193
194 Authors
195 -------
196
197 Coquelicot © 2010 potager.org <jardiniers@potager.org>
198
199 Coquelicot is distributed under the GNU Affero General Public License
200 version 3. See LICENSE for details.