Browse Source

Improve the Texinfo manual

This is an almost complete rewrite.
Damien Goutte-Gattat 5 years ago
  1. 224


@ -39,8 +39,9 @@ This manual is for Gfsecret (version @value{VERSION}, @value{UPDATED}).
* Introduction::
* The share URI syntax::
* The Gfsecret configuration file::
* The Share URI Syntax::
* Splitting a Secret::
* Using a Splitted Secret::
* GNU Free Documentation License::
* Index::
@end menu
@ -115,8 +116,8 @@ the user didn't specify any command), and remove the reconstructed
secret once that command terminates.
@node The share URI syntax
@chapter The share URI syntax
@node The Share URI Syntax
@chapter The Share URI Syntax
Both @command{gfsec-split} and @command{gfsec-use} use the concept of a
@emph{share URI} to describe and represent shares. A share URI is an
@ -150,29 +151,210 @@ match (@command{gfsec-use} will refuse to use the share otherwise), and
contains the whole secret.
@node The Gfsecret configuration file
@chapter The Gfsecret configuration file
@node Splitting a Secret
@chapter Splitting a Secret
The @command{gfsec-split} tool is used to split a secret file into
The program must be given the pathname of the file to split as its first
positional argument. The location of the shares to create can either be
specified as @emph{share URIs} (@ref{The Share URI Syntax}) as
subsequent positional arguments on the command line (@ref{Specifying
Share URIs on the Command Line}), or be given through an interactive
menu (@ref{Interactive Selection of Shares}).
The threshold, that is, the minimal number of shares needed to
reconstruct the original file, is specified with the option @option{-n}
(@option{--threshold}). The default threshold is 2. The total number of
shares must of course be greater than or equal to that threshold, and
@command{gfsec-split} will fail otherwise (obviously you cannot split a
secret in two shares and require three shares to reconstruct it).
By default, if the split is successful, @command{gfsec-split} will
delete the original secret file once the shares have been dispatched to
their final location. Use the option @option{-k} (@option{--keep}) to
leave the original file intact.
A configuration file, needed by @command{gfsec-use} to reconstruct the
splitted file, will be automatically generated in the directory
@file{$XDG_CONFIG_HOME/gfsecret/@var{basename}.conf}, where
@var{basename} is the basename of the original file (without any
directory part and file extension). For example, when called to split a
file @file{/home/alice/Documents/mysecret.dat}, @command{gfsec-split} will
generate a configuration file in
@file{/home/alice/.config/gfsecret/mysecret.conf} (assuming the default
value for the @var{XDG_CONFIG_HOME} environment variable). Use the
option @option{-c} (@option{--config}) to write the configuration file
The @command{gfsec-use} program needs a configuration file to reconstruct a
secret from a list of shares. This file is automatically generated by
* Specifying Share URIs on the Command Line::
* Interactive Selection of Shares::
@end menu
@node Specifying Share URIs on the Command Line
@section Specifying Share URIs on the Command Line
The first method to tell @command{gfsec-split} where to put the shares
is to give it @emph{share URIs} (@ref{The Share URI Syntax}) on the
command line, as follows:
$ gfsec-split @var{secretfile} @var{uri1} @var{uri2} @var{uri3}
@end example
Before actually splitting the secret, you may invoke
@command{gfsec-split} with the option @option{-l}
(@option{--list-supports}) to get a list of available storage devices so
that you can construct the needed share URIs:
$ gfsec-split -l
file:/// Local filesystem
label://USBSTICK/ External volume with label 'USBSTICK'
mtp://RF2GB6X704P/ Samsung Galaxy A3
@end example
With those informations, you may then proceed to the actual split. Here,
assuming you want to put a share on each one of the available devices:
$ gfsec-split @var{secretfile} \
file:///home/alice/.shares/mysecret \
label://USBSTICK/mysecret \
@end example
(Note that shares do not need to have the same filename.)
With this example, @command{gfsec-split} with split @var{secretfile} in
three shares and store the first one in Alice's home directory, the
second one in the USB mass storage device called @emph{USBSTICK}, and
the third one on the Samsung Galaxy A3 smartphone with serial number
@emph{RF2GB6X704P}. External volumes will be automatically mounted if
needed (in that case they will also be unmounted at the end).
Note that @command{gfsec-split} will not create parent directories,
which must exist beforehand.
@node Interactive Selection of Shares
@section Interactive Selection of Shares
To avoid manually specifying the share URIs, use the @option{-i}
(@option{--interactive}). You will then be presented with an interactive
menu with the available devices:
$ gfsec-split -i @var{secretfile}
Select a support for share #1:
(1) Local filesystem
(2) External volume with label 'USBSTICK'
(3) Samsung Galaxy A3
(x) Done
Your choice?
@end example
Select the device on which you want to put the first share, then enter
the pathname to use on that device when prompted (again, be aware that
no parent directories will be created).
Repeat for all the shares you want to create, then select @kbd{x} when
you are done. @command{gfsec-split} will then show you a summary of what
you have selected, and ask for your confirmation:
The following shares will be created:
Proceed (y/N)?
@end example
Note that you can use both the command line and the interactive menu in
the same invocation of @command{gfsec-split}. The shares that you
describe on the command line will be added to the one you select in the
@node Using a Splitted Secret
@chapter Using a Splitted Secret
The @command{gfsec-use} program allows its user to temporarily
reconstruct a previously splitted file.
It reads a configuration file (automatically generated by the
@command{gfsec-split} program, although a configuration file can also be
crafted by hand) which gives, in particular, the location of the shares
(@ref{The Gfsecret Configuration File}).
Configuration files are normally stored in
@file{$XDG_CONFIG_HOME/gfsecret}, and @command{gfsec-use} reads by
default the file @file{XDG_CONFIG_HOME/gfsecret/default.conf}. The
option @option{-c} (@option{--config}) allows to specify another file:
$ gfsec-use -c @var{myconfig}
@end example
If the file @var{myconfig} exists, it is used as the configuration file;
otherwise, @command{gfsec-use} looks for a file named
@file{@var{myconfig}.conf} in the directory
Once the splitted file has been reconstructed (if enough shares are
available), @command{gfsec-use} will either spawn a new shell, or
execute any program specified at the end of the command line. When the
shell, or the user-specified program, terminates, the reconstructed file
is deleted again.
The @option{-k} (@option{--keep}) prevents @command{gfsec-use} from
deleting the reconstructed file. As a special case, if this option is
used and there is no user-specified command to execute,
@command{gfsec-use} will not spawn a new shell, but exits as soon as the
file is reconstructed.
The reconstructed file is normally written at the location of the
original file (or any other location specified by the @option{OUTFILE}
key in the configuration file). It may be written elsewhere by using the
@option{-o} (@option{--output}).
* The Gfsecret Configuration File::
@end menu
@node The Gfsecret Configuration File
@section The Gfsecret Configuration File
A configuration file contains all the informations needed by
@command{gfsec-use} to reconstruct a splitted file.
Those informations are stored as @code{key=value} pairs, with one such a
pair per line. Blank lines are ignored, as well as lines starting with a
@code{#} character.
It contains @samp{key=value} pairs, one per line. Blank lines are
ignored, as well as lines starting with a @samp{#} character.
The following table lists the allowed keys and their signification:
The @samp{OUTFILE} key specifies the pathname to the file where the
reconstructed secret is to be stored.
@table @code
This is the pathname to the file where the reconstructed secret is to be
written. When the configuration file is generated by
@command{gfsec-split}, this defaults to the location of the original
The @samp{MINSHARES} key indicates the lowest number of shares required
This is the threshold, indicating the lowest number of shares required
to reconstruct the secret.
The @samp{URI} key contains an URI representing a share, as described
previously in @ref{The share URI syntax}.
@end itemize
@item URI
This is an URI representing one of the shares, as described previously in
@ref{The Share URI Syntax}.
@end table
@node GNU Free Documentation License