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