GFSEC-USE(1)

NAME
gfsec-use - Make use of a shared secret

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

DESCRIPTION

gfsec-use reconstructs a secret file that has been previously split using a tool like gfsplit(1) or the accompanying program gfsec-split(1).

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.

OPTIONS

-h, --help
    Display the help message.

-v, --version
    Display the version message.

-c, --config file
    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.

-k, --keep
    Do not delete the reconstructed file upon termination of the specified command.

-o, --output file
    Write the reconstructed secret in the specified file. This overrides the OUTFILE parameter in the configuration file.

-r, --restore-cmd command
    Execute the specified command instead of writing the reconstructed secret to a file. The secret is sent to the command's standard input.

-d, --destroy-cmd command
    Execute the specified command instead of deleting the reconstructed secret file upon termination.

CONFIGURATION FILE

A configuration file describes one secret file to reconstruct. Blank lines and lines starting with a # character are ignored.

The following directives can be used:

OUTFILE=file
    Specify the file to write the reconstructed secret into.

RESTORE=command
    Specify the command to execute once the secret has been reconstructed.

DESTROY=command
    Specify the command to execute to destroy the secret upon termination.

MINSHARES=n
    Specify the minimal number of shares needed to reconstruct the secret. The default if unspecified is 2.

URI=uri
    Specify an URI indicating where to find a share.

Supported URI schemes are:

file:///
    Indicates a file on the local filesystem.

uuid://uuid/
    Indicates a file on the external volume identified by the specified UUID.

label://label/
    Indicates a file on the external volume identified by the specified label.

mtp://serial/
    Indicates a file on the MTP device identified by the specified serial number.

http://host/
    Indicates a file on a web server identified by its hostname.

https://host/
    Same as the previous one, but the web server is to be accessed through a secure connection.

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

The URI may include a share=no 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).

Another parameter is sha256, 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.

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

EXAMPLE CONFIGURATION FILE

OUTFILE=/home/alice/mysecret
MINSHARES=2
URI=file:///home/alice/.local/share/gfsecret/mysecret.024
URI=label://USBSTICK/mysecret.070?sha256=hex_hash
URI=mtp://RF2GB6X704P/Documents/mysecret.139

REPORTING BUGS

Report bugs to Damien Goutte-Gattat (devel@incenp.org).

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

COPYRIGHT

Copyright © 2017,2021 Damien Goutte-Gattat

This program is released under the GNU General Public License. See the COPYING file in the source distribution or http://www.gnu.org/licenses/gpl.html.