Prepare for 0.3.0 release

Update doc files and bump version number to 0.3.0.

NEWS

@@ -1,3 +1,9 @@
+Changes in gfsecret 0.3.0
+
+    * Improve error messages.
+    * Add the gfsec-split program.
+
+
 Changes in gfsecret 0.2.0
 
     * Check share data against SHA-256 hash.

README.md

@@ -5,22 +5,103 @@ Gfsecret is a set of tools to facilitate secret sharing according to the
 [Adi Shamir’s secret sharing
 scheme](http://dl.acm.org/citation.cfm?id=359176).
 
+Two tools are provided: _gfsec-split_ will split a file into several
+shares, and _gfsec-use_ will reconstruct the original file from some of
+the shares.
+
+
+Share URIs
+----------
+Both tools use the concept of a _share URI_, which is a way of
+describing a share with a URI-like syntax. The _gfsec-split_ program
+uses them to know where to dispatch the generated shares, and
+_gfsec-use_ uses them to know where to search for shares in order to
+reconstruct the original file.
+
+A share URI has the following form:
+
+    scheme://authority/path?parameters
+
+The _scheme_ part indicates the method to use to access the share, and
+can be `file` (to access a share on the local filesystem), `label` (to
+access a share on an external volume identified by its label), `uuid`
+(to access a share on an external volume identified by its UUID), or
+`mtp` (to access a share on a MTP-compliant device identified by its
+serial number).
+
+The `authority` part identifies the storage device. It's the volume's
+label when using the `label://` scheme, its UUID when using the
+`uuid://` scheme, and the device's serial number when using the `mtp://`
+scheme. In the `file://` scheme, that part should be empty.
+
+The _path_ part is the pathname to the share file on the device.
+
+Finally, the _parameters_ part, which is optional, may specify options
+as `key=value` pairs. Currently, valid options are `sha256`, which
+specifies a SHA2-256 hash that the share should match, and `share=no`,
+which indicates that the corresponding share is not actually a share but
+contains the whole secret.
+
+
+gfsec-split
+-----------
+The _gfsec-split_ program allows to split a file into _M_ shares,
+dispatch them at distinct locations (including external storage
+devices), then delete the original file.
+
+The program takes the path to the file to split as its single positional
+argument. Use the `-s` option to specify a share to create using the URI
+syntax described above (use one `-s` option for each share).
+
+Consider the following example:
+
+    gfsec-split -n 2 \
+      -s file:///home/alice/.local/share/gfsecret/mysecret \
+      -s label://USBSTICK/mysecret \
+      -s mtp://RF2GB6X704P/Documents/mysecret \
+      /home/alice/mysecret
+
+This will split the file `/home/alice/mysecret` into three shares: one
+in Alice's home directory on the local filesystem, one on a USB storage
+device with the label `USBSTICK`, and one on a MTP-compliant device with
+the serial number `RF2GB6X704P`. Two shares will be needed to
+reconstruct the original file, which means in this case that one of the
+two removable devices will have to be present.
+
+Note that the shares need not to have the same basename than the
+original file.
+
+Once the file is splitted, _gfsec-split_ will delete the original file
+(unless you used the `-k` option), and will create a configuration file
+in `$XDG_CONFIG_HOME/gfsecret/mysecret` (or at any location specified by
+the `-c` option) which could later be used by _gfsec-use_.
+
+If you move the shares around after they have been generated, you should
+take care of updating that configuration file, otherwise _gfsec-use_
+will be unable to fetch the shares.
+
+As a convenience, before splitting you may call _gfsec-split_ with the
+single `-l` option to list the available external volumes and their
+identifiers.
+
 
 gfsec-use
 ---------
 The _gfsec-use_ program allows to temporarily reconstruct a splitted
-file from shares that have been dispersed on several external devices
-(USB sticks and/or MTP-compliant devices like some smartphones or audio
-players).
+file from shares that have been dispersed on several external devices.
 
 The program needs a configuration file (by default,
 `$XDG_CONFIG_HOME/gfsecret/default.conf`) which describes the shared
-secret. Here is a sample configuration:
+secret. If the original file has been splitted using the _gfsec-split_
+program, the configuration file will have been automatically generated.
+
+For example, here is the configuration file that could have been
+generated by the example above:
 
     OUTFILE=/home/alice/mysecret
     MINSHARES=2
     URI=file:///home/alice/.local/share/gfsecret/mysecret.024
-    URI=label://MYSTICK/mysecretfile.070
+    URI=label://MYSTICK/mysecret.070
     URI=mtp://RF2GB6X704P/Documents/mysecret.139
 
 With such a configuration, _gfse-use_ will attempt to reconstruct the

configure.ac

@@ -1,6 +1,6 @@
 dnl Configure template for the gfsecret package
 
-AC_INIT([gfsecret], [0.2.0],
+AC_INIT([gfsecret], [0.3.0],
         [dgouttegattat@incenp.org])
 AC_CONFIG_SRCDIR([configure.ac])
 AC_CONFIG_MACRO_DIR([m4])