Merge remote branch 'nadir/translations/de'
[coquelicot.git] / README
diff --git a/README b/README
index 839f497..8647479 100644 (file)
--- a/README
+++ b/README
@@ -1,24 +1,36 @@
 Coquelicot
 ==========
 
-Coquelicot is a "one-click" file sharing web application with specific
-thoughts on protecting users privacy.
+Coquelicot is a "one-click" file sharing web application with specific
+focus on protecting users' privacy.
 
-Basic principle: users can upload a file to the server, it return they
-get a unique URL which can be shared to others in order to download the
-file.
+Basic principle: users can upload a file to the server, in return they
+get a unique URL which can be shared with others in order to download
+the file.
 
-Coquelicot aims to protect, to some extents, users and system
-administrators from disclosure of the files exchanged from passive
-and not so active attackers.
+Coquelicot aims to protect, to some extent, users and system
+administrators from disclosure of the files exchanged from passive and
+not so active attackers.
 
 Features
 --------
 
- * Uploading a file is protected by a common password
+ * Support for different authentication methods
 
-   In order to prevent random Internet users to eat bandwidth and disk
-   space, uploading a file to share is protected by a common password.
+   In order to prevent random Internet users to eat bandwidth and
+   disk space, Coquelicot limits upload to authenticated users.
+   It currently ships with two authentication mechanisms:
+
+    - "simplepass": users will need to provide a global, pre-shared,
+      password;
+    - "imap": users will need to provide a login and a password,
+      those credentials will be used to authenticate against an existing
+      IMAP server.
+
+   It is possible to integrate more authentication mechanisms by
+   implementing a single method, some Javascript, and a template partial
+   to render the common fields. For more information have a look at the
+   notes below.
 
  * Mandatory expiration
 
@@ -30,9 +42,9 @@ Features
 
  * Support for one-time download
 
-   An user might want to allow exactly _one_ download of a file,
-   to more closely replace an email attachment. The file will be removed after
-   the first complete download and concurrent download are prevented.
+   An user might want to allow exactly _one_ download of a file, to more
+   closely replace an email attachment. The file will be removed after
+   the first complete download and concurrent downloads are prevented.
 
  * Upload progress bar
 
@@ -53,7 +65,7 @@ Features
 
  * Files are stored encrypted on the server
 
-   Upon upload, files are written to the disk using symmetric
+   While being uploaded, files are written to the disk using symmetric
    encryption. The encryption key is _not_ stored directly by
    Coquelicot. It is either generated randomly and given as part of the
    download URL, or specified by the uploader.
@@ -81,22 +93,18 @@ Features
 
    When a file has expired, it is removed from the server. In order
    to make it harder to retrieve its content through filesystem
-   analysis, it is filled with zeroes first.
+   analysis, it is filled with zeros first.
 
 Setup
 -----
 
 Coquelicot is written in Ruby using the Sinatra web framework.
 
-On Debian, one can fulfill its dependencies by issueing:
+On Debian, one can fulfill its dependencies by issuing:
 
     apt-get install libsinatra-ruby1.8 libopenssl-ruby1.8 \
                     libhaml-ruby1.8 liblockfile-ruby libgettext-ruby1.8 \
-                    rake
-
-Then create the translation catalog through:
-
-    rake makemo
+                    libjson-ruby1.8 rake
 
 Finally you need to figure out the best way to host a Rack application
 depending on your setup. *evil grin*
@@ -104,20 +112,57 @@ depending on your setup. *evil grin*
 Coquelicot is intended to be run on a fully encrypted system and accessible
 only through HTTPS.
 
-Test suite
-----------
+Configuration
+-------------
+
+By default Coquelicot is configured to authenticate with the
+"simplepass" mechanism and some other reasonable defaults.
+
+It is possible to overwrite these settings from a configuration file
+named `settings.yml` that will be used if it is present in the `conf`
+directory of the application.
+
+All available settings with their default values are documented in
+`conf/settings-default.yml`.
+
+Further settings example:
+
+ * `conf/settings-simplepass.yml`: shows how to change the default
+   password for the "simplepass" mechanism.
+
+ * `conf/settings-imap.yml`: necessary configuration for the "imap"
+   authentication mechanism.
+
+You can copy one of these examples to `conf/settings.yml` and adjust them
+according to your environment.
+
+Garbage collection
+------------------
+
+To cleanup files automatically when they expired, coquelicot comes with
+a cleanup script, that does the garbage collection for you. The easiest
+way is to add `ext/coquelicot_gc.rb` as a cron job that runs every 5
+minutes (or so).
+
+Test and development
+--------------------
+
+As Coquelicot uses Bundle, the first step to work on Coquelicot
+is installing the proper dependencies by issuing:
 
-Coquelicot test suite is written using RSpec.
+    bundle install
 
-On Debian, you will need those extra packages:
+Coquelicot test suite is written using RSpec. Running the test suite is just a
+matter of typing:
 
-    apt-get install librspec-ruby1.8 libhpricot-ruby1.8
+    bundle exec rspec
 
-You will also need the unpackaged gems "timecop" and "rack-test".
+To update the translation source files, use:
 
-Then, running the test suite is just a matter of typing:
+    bundle exec rake updatepo
 
-    spec test_coquelicot.rb
+This will update `po/coquelicot.pot` and merge the new strings in the various
+`po/*/coquelicot.po` files.
 
 Migrate from Jyraphe
 --------------------
@@ -131,12 +176,6 @@ Coquelicot provides a migration script to import Jyraphe 0.5 repositories in
 Future
 ------
 
- * Integrate other authentication systems for uploads
-
-   A common password is a pretty limited authentication scheme.
-   One could like to also configure no password or integrate with
-   webmails or other authentication system.
-
  * More flexible expiration
 
    It might be interesting to also offer a calendar for specifying
@@ -178,7 +217,7 @@ The format is the following:
 
 Encryption is done using OpenSSL. Cipher is AES-256-CBC with key and IV
 created using the pbkdf2_hmac_sha1() implementation of PKCS5. The later
-is fead using the former 'Salt' and the given passphrase.
+is fed using the former 'Salt' and the given passphrase.
 
 Once decrypted, content has the following format:
 
@@ -200,10 +239,56 @@ is used. It contains a line for each file in the form:
 
     <URL name> <file name>
 
+Authentication Mechanisms
+-------------------------
+
+It is possible to authenticate users against your own common authentication
+mechanism.
+
+Such an authentication mechanism needs to provide the following 3 files,
+with the following responsabilities:
+
+ * `lib/coquelicot/auth/<METHOD>.rb`:
+
+   A class implementing the actual authentication. This class must
+   implement an `authenticate` method. It will receive the form fields
+   as usual (params). This method should either return true if upload
+   should be allowed.
+
+ * `public/javascripts/coquelicot.auth.<METHOD>.js:`
+
+    This file should define 'authentication' as an object with the following
+    methods:
+
+    - `getData()`: returns an object of all the necessary data
+      to authenticate on the app side. Keys should have the same name
+      as the input fields used to authenticate without Javascript.
+    - `focus()`: set the focus on the first authentication form field.
+    - (optional) `handleSuccess()`: arbitrary action upon successful
+      authentication. This is called after the livebox is closed.
+    - (optional) `handleReject()`: arbitrary action when access
+      get rejected. One can reset authentication fields after a failed
+      authentication.
+    - (optional) `handleFailure()`: arbitrary action when there was
+      a problem in the authentication procedure.
+
+ * `views/auth/<METHOD>.haml`:
+
+   Render the necessary form fields that will be used for authentication.
+
+   The authentication method can be set in the application settings
+   including mandatory options for this method.
+
 Authors
 -------
 
-Coquelicot © 2010 potager.org <jardiniers@potager.org>
+Coquelicot © 2010-2012 potager.org <jardiniers@potager.org>  
+           © 2011 mh / immerda.ch <mh+coquelicot@immerda.ch>
 
 Coquelicot is distributed under the GNU Affero General Public License
 version 3. See LICENSE for details.
+
+Background image (`public/images/background.jpg`) derived from:  
+"coquelicot" © 2008 Jean-Louis Zimmermann  
+Licensed under Creative Commons Attributions 2.0 Generic  
+<https://secure.flickr.com/photos/jeanlouis_zimmermann/2478019744/>