You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
187 lines
6.5 KiB
187 lines
6.5 KiB
\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
|
|
|