gfsecret/info/gfsecret.texi

\input texinfo
@setfilename gfsecret.info
@settitle The Gfsecret Manual
@include version.texi

@copying
This is the manual for Gfsecret (version @value{VERSION}, last updated
@value{UPDATED}).

Copyright @copyright{} 2017 Damien Goutte-Gattat

@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
Texts. A copy of the license is included in the section entitled ``GNU
Free Documentation License''.
@end quotation
@end copying

@titlepage
@title Gfsecret
@subtitle for version @value{VERSION}, @value{UPDATED}
@author Damien Goutte-Gattat (@email{dvlpt@@incenp.org})
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@contents

@ifnottex
@node Top
@top Gfsecret

This manual is for Gfsecret (version @value{VERSION}, @value{UPDATED}).
@end ifnottex

@menu
* Introduction::
* The share URI syntax::
* The Gfsecret configuration file::
* GNU Free Documentation License::
* Index::
@end menu


@node Introduction
@chapter Introduction

You may have some important files that you both don't want to lose and
don't want to fall into any other hands than yours. It may be files
containing your OpenPGP private keys, the file containing all your
online passwords, the file describing your plan for total world
domination, whatever.

Such files pose an interesting problem. Obviously, you have to backup
them to avoid losing them, but any supplementary copy gives your
adversary one more opportunity to grab your secret.

@menu
* Adi Shamir's Secret Sharing::
* Overview of Gfsecret::
@end menu


@node Adi Shamir's Secret Sharing
@section Adi Shamir's Secret Sharing

A secret sharing scheme is precisely what you need to fulfill both of
the contradictory goals.

The Adi Shamir's secret sharing scheme, devised by the famous
cryptographer Adi Shamir (the ``A'' in the RSA public cryptography
algorithm) in 1979, relies on the fact that @math{n + 1} points are
required to uniquely define a curve corresponding to a polynom of order
@math{n}.

To illustrate the scheme, let's say you want to share a secret value
@math{b} in two or more shares, so that at least two shares are needed
to reconstitute the secret. You will define a curve of the form
@math{f(x) = ax + b}, where @math{a} is a randomly chosen coefficient
and @math{b} (the secret value) is the y coordinate where the curve
intersects the Y axis.

A share is then a point on that curve, that is, a couple @math{x, f(x)}.
If you have only one point, there's no way for you to know what the
curve is, and where it intersects the Y axis, because there's an
infinity of curves passing through this point.

As soon as you have (at least) two points, however, you have all the
information that you need: there's only one straight curve passing
through two distinct points, and you can trace it, and trivially find
where it intersects the Y axis (and thus retrieve the secret value).



@node Overview of Gfsecret
@section Overview of Gfsecret

Gfsecret implements the Adi Shamir's secret sharing scheme to allow its
user to split a secret file into a given number of @emph{shares}, to
dispatch the shares onto several external storage devoces such as USB
sticks, and to temporarily reconstruct the original file when needed.

Gfsecret comprises two programs: @command{gfsec-split} splits a secret
file into shares and dispatches them, leaving behind a configuration
file describing the location of the shares; @command{fgsec-use} reads
the configuration file left by @command{gfsec-split}, attempts to fetch
the shares, and reconstructs the secret file if enough shares are
available.  If the reconstruction is successful, @command{gfsec-use}
will then execute a single command (or start a new interactive shell if
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

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
URI-like string of the form @samp{scheme://authority/path?parameters}.

The @var{scheme} part indicates the method to use to access the share.
It can be: @samp{file} for a share on the local filesystem; @samp{label}
for a share on an external volume identified by its label; @samp{uuid}
for a share on an external volume identified by its UUID; or @samp{mtp}
for a share on a MTP-compliant device identified by its serial number.

The @var{authority} part identifies the storage device. It should be
empty when using the @samp{file://} scheme (although for consistency
with other uses of that scheme by other programs, it is permitted to
specify @samp{localhost}). It represents the volume's label when using
the @samp{label://} scheme, the volume's UUID when using the
@samp{uuid://} scheme, and the device's serial number when using the
@samp{mtp://} scheme.

The @var{path} part is the pathname to the share file on the device.
The filename itself should end with a numeric extension representing the
share number (needed by @command{gfsec-use} to appropriately reconstruct
the secret). That share number is automatically determined and appended
to the original filename by @command{gfsec-split}.

Finally, the optional @var{parameters} part may contains options
expressed as @samp{key=value} pairs. Currently, valid options are
@samp{sha256}, which specifies a SHA2-256 hash that the share should
match (@command{gfsec-use} will refuse to use the share otherwise), and
@samp{share=no}, which indicates that the corresponding share actually
contains the whole secret.


@node The Gfsecret configuration file
@chapter The Gfsecret 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
@command{gfsec-split}.

It contains @samp{key=value} pairs, one per line. Blank lines are
ignored, as well as lines starting with a @samp{#} character.

@itemize
@item
The @samp{OUTFILE} key specifies the pathname to the file where the
reconstructed secret is to be stored.

@item
The @samp{MINSHARES} key indicates the lowest number of shares required
to reconstruct the secret.

@item
The @samp{URI} key contains an URI representing a share, as described
previously in @ref{The share URI syntax}.
@end itemize


@node GNU Free Documentation License
@appendix GNU Free Documentation License
@include fdl.texi


@node Index
@unnumbered Index
@printindex cp

@bye