Browse Source

Prepare for 0.3.0 release

Update doc files and bump version number to 0.3.0.
Damien Goutte-Gattat 6 years ago
  1. 6
  2. 91
  3. 2


@ -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.


@ -5,22 +5,103 @@ Gfsecret is a set of tools to facilitate secret sharing according to the
[Adi Shamir’s secret sharing
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:
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.
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 \
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
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
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:
With such a configuration, _gfse-use_ will attempt to reconstruct the


@ -1,6 +1,6 @@
dnl Configure template for the gfsecret package
AC_INIT([gfsecret], [0.2.0],
AC_INIT([gfsecret], [0.3.0],