Mention `userpass` authentication method in README
[coquelicot.git] / README
1 About “Coquelicot”
2 ==================
3
4 [Coquelicot] — /kɔ.kli.ko/ —  is a "one-click" file sharing web application
5 with a 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 extent, users and system
12 administrators from disclosure of the files exchanged from passive and
13 not so active attackers.
14
15 [Coquelicot]: https://coquelicot.potager.org/
16
17 Features
18 --------
19
20  * Support for different authentication methods
21
22    In order to prevent random Internet users to eat bandwidth and
23    disk space, Coquelicot limits upload to authenticated users.
24    It currently ships with three authentication mechanisms:
25
26     - "simplepass": uploading users need to provide a global,
27       pre-shared, password;
28     - "userpass": users will need to provide a login and a
29       pre-shared password stored in a local configuration file;
30     - "imap": users will need to provide a login and a password,
31       that are used to authenticate against an existing IMAP server.
32     - "ldap": users will need to provide a uid and a password,
33       that are used to authenticate against an existing LDAP server.
34
35    It is possible to integrate more authentication mechanisms by
36    implementing a single method, some JavaScript, and a partial template
37    to render the common fields. For more information have a look at the
38    notes below.
39
40  * Mandatory expiration
41
42    When uploading, a time limit has to be specified. The file will be
43    unavailable once this much time has passed.
44
45    During a configurable period of time, trying to download the file
46    will return a page saying "too late" instead of "not found".
47
48  * Support for one-time download
49
50    A user might want to allow exactly _one_ download of a file, to more
51    closely replace an email attachment. The file will be removed after
52    the first complete download and concurrent downloads are prevented.
53
54  * Upload progress bar
55
56    Users having JavaScript enabled will see a nice progress bar during
57    the file upload.
58
59  * Downgrade nicely
60
61    The application works fine without JavaScript or CSS.
62
63  * Download URL can be written on paper
64
65    URLs generated to download files uses the Base32 character set. This
66    set is specifically designed to overcome misread of 'l', '1', '0' and
67    'O' characters. Coquelicot will automatically convert case and
68    ambiguous characters to facilitate URL exchanges using pieces of
69    paper.
70
71  * Files are stored encrypted on the server
72
73    While being uploaded, files are written to the disk using symmetric
74    encryption. The encryption key is _not_ stored directly by
75    Coquelicot. It is either generated randomly and given as part of the
76    download URL, or specified by the uploader.
77
78  * Download can be protected by a password
79
80    When uploading, a password can be specified which will then be used
81    to encrypt the file. For subsequent downloads, the password
82    must be entered through in a POST'ed form. This prevents the password
83    from appearing in most server logs.
84
85  * Files are stored with a random name
86
87    To prevent disclosure of the shared file name, it is stored encrypted
88    together with the file content. On the server, this encrypted file is
89    stored with a random name.
90
91  * Download URLs do not reflect stored file names
92
93    The random names given in download URLs do not map directly to file
94    names on the server. This prevent server logs from giving a direct
95    mapping to the shared files. This creates another difficulty to
96    link users to files through forensic techniques.
97
98  * File content is zero'ed before removal
99
100    When a file has expired, it is removed from the server. In order
101    to make it harder to retrieve its content through filesystem
102    analysis, it is filled with zeros first.
103
104 Reporting bugs
105 --------------
106
107 Please report bugs or suggest new features on the users and developers [mailing
108 list].
109
110 [mailing list]: https://listes.potager.org/listinfo/coquelicot
111
112 Authors
113 -------
114
115     Coquelicot © 2010-2016 potager.org <jardiniers@potager.org>
116                © 2014-2016 Rowan Thorpe <rowan@rowanthorpe.com>
117                © 2010-2012 Jake Santee <jake@nadir.org>
118                © 2012 Silvio Rhatto <rhatto@riseup.net>
119                © 2011 mh / immerda.ch  <mh+coquelicot@immerda.ch>
120
121 Coquelicot is distributed under the [GNU Affero General Public License]
122 version 3 or (at your option) any later version.
123
124 Background image (`public/images/background.jpg`) derived from:  
125 [“coquelicot” picture] © 2008 Jean-Louis Zimmermann  
126 Licensed under [Creative Commons Attributions 2.0 Generic]  
127
128 *jQuery* is © 2011 John Resig. Licensed under the [MIT license].  
129 *jquery.uploadProgress* is © 2008 Piotr Sarnacki. Licensed under the
130 [MIT license].  
131 *lightboxFu* is © 2008 Piotr Sarnacki. Licensed under the [MIT license].
132
133 [“coquelicot” picture]: https://secure.flickr.com/photos/jeanlouis_zimmermann/2478019744/
134 [GNU Affero General Public License]: http://www.gnu.org/licenses/agpl.txt
135 [Creative Commons Attributions 2.0 Generic]: https://creativecommons.org/licenses/by/2.0/deed
136 [MIT license]: http://www.opensource.org/licenses/mit-license.php