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