.TH GFSEC-USE 1 2017-07-23 "gfsecret 0.4.6" "Gfsecret Manual"

.SH NAME
gfsec-use \- Make use of a shared secret

.SH SYNOPSIS
.SY gfsec-use
.RB [ \-h | --help ]
.RB [ \-v | --version ]
.RB [ \-c | --config
.IR file ]
.RB [ \-k | --keep ]
.RB [ \-o | --output
.IR file ]
.RB [ \-r | --restore-cmd
.IR command ]
.RB [ \-d | --destroy-cmd
.IR command ]
.RB [ command... ]
.YS

.SH DESCRIPTION
.PP
.B gfsec-use
reconstructs a secret file that has been previously
split using a tool like
.BR gfsplit (1)
or the accompanying program
.BR gfsec-split (1).
.PP
A user-specified command (or a shell) is spawn once
the secret has been reconstructed, and the secret
file is deleted when the command terminates.

.SH OPTIONS
.TP
.BR -h ", " --help
Display the help message.
.TP
.BR -v ", " --version
Display the version message.
.TP
.BR -c ", " --config " " \fIfile\fR
Specify a configuration file. If the specified
file does not exist, a .conf extension is appended
to the filename and a corresponding file is searched
in $XDG_CONFIG_HOME/gfsecret. When that option is
not used, a default configuration
$XDG_CONFIG_HOME/gfsecret/default.conf is assumed.
.TP
.BR -k ", " --keep
Do not delete the reconstructed file upon termination
of the specified command.
.TP
.BR -o ", " --output " " \fIfile\fR
Write the reconstructed secret in the specified
file. This overrides the OUTFILE parameter in the
configuration file.
.TP
.BR -r ", " --restore-cmd " " \fIcommand\fR
Execute the specified command instead of writing
the reconstructed secret to a file. The secret is
sent to the command's standard input.
.TP
.BR -d ", " --destroy-cmd " " \fIcommand\fR
Execute the specified command instead of deleting
the reconstructed secret file upon termination.

.SH CONFIGURATION FILE
.PP
A configuration file describes one secret file to reconstruct.
Blank lines and lines starting with a # character are ignored.
.PP
The following directives can be used:
.TP
OUTFILE=\fIfile\fR
Specify the file to write the reconstructed secret into.
.TP
RESTORE=\fIcommand\fR
Specify the command to execute once the secret has been
reconstructed.
.TP
DESTROY=\fIcommand\fR
Specify the command to execute to destroy the secret upon
termination.
.TP
MINSHARES=\fIn\fR
Specify the minimal number of shares needed to reconstruct
the secret. The default if unspecified is 2.
.TP
URI=\fIuri\fR
Specify an URI indicating where to find a share.

.PP
Supported URI schemes are:
.TP
file:///
Indicates a file on the local filesystem.
.TP
uuid://\fIuuid\fR/
Indicates a file on the external volume identified
by the specified UUID.
.TP
label://\fIlabel\fR/
Indicates a file on the external volume identified
by the specified label.
.TP
mtp://\fIserial\fR/
Indicates a file on the MTP device identified by the
specified serial number.

.PP
Whatever the scheme, the file part of the URI must end
with an extension indicating the share number, as
generated by
.BR gfsplit (1).

.PP
The URI may include a \fIshare=no\fR parameter,
indicating that the corresponding file contains the
whole secret and not only a share (in that case, the
previous remark about the share number in the extension
does not apply).

.PP
Another parameter is \fIsha256\fR, which specifies the
expected SHA-256 hash value of the share data. If such a
parameter is specified, a share will only be used if the
data matches the expected hash value.

.PP
The
.BR gfsec-split (1)
program, used to split a file into shares, will automatically
generate a suitable configuration file allowing to reconstruct
the original file.

.SH EXAMPLE CONFIGURATION FILE
.PP
.nf
OUTFILE=/home/alice/mysecret
MINSHARES=2
URI=file:///home/alice/.local/share/gfsecret/mysecret.024
URI=label://USBSTICK/mysecret.070?sha256=\fIhex_hash\fR
URI=mtp://RF2GB6X704P/Documents/mysecret.139
.fi

.SH REPORTING BUGS
.PP
Report bugs to
.MT devel@incenp.org
Damien Goutte-Gattat
.ME .

.SH SEE ALSO
.BR gfsec-split (1),
.BR gfsplit (1),
.BR gfcombine (1),
.BR libgfshare (3),
.BR gfshare (7)

.SH COPYRIGHT
.ad l
.PP
Copyright \(co 2017 Damien Goutte-Gattat
.PP
This program is released under the GNU General Public License.
See the COPYING file in the source distribution or
.UR http://www.gnu.org/licenses/gpl.html
.UE .