Browse Source

Update info manual.

develop
Damien Goutte-Gattat 4 years ago
parent
commit
2e5fbf13ef
  1. 76
      info/gfsecret.texi

76
info/gfsecret.texi

@ -177,6 +177,11 @@ 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.
The option @option{-d} (@option{--destroy-cmd}) may be used to specify
a command that @command{gfsec-split} will call to delete the secret
once it has been splitted. The same command will also be called by
@command{gfsec-use} to delete the secret when it is no longer needed.
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
@ -328,6 +333,18 @@ 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}).
Instead of writing the reconstructed secret to a file,
@command{gfsec-use} may also call an user-specified command and send the
secret to its standard input. The command to call is either specified
through the @option{-r} (@option{--restore-cmd}) option, or read from
the configuration file.
Similarly, an user-specified command may be run to delete the secret
when it is no longer needed (unless the @option{--keep} option has been
used). That command is either specified through the @option{-d}
(@option{--destroy-cmd}) option, or read from the configuration file.
@menu
* The Gfsecret Configuration File::
@end menu
@ -352,6 +369,14 @@ written. When the configuration file is generated by
@command{gfsec-split}, this defaults to the location of the original
file.
@item RESTORE
This is the command to run once the secret has been reconstructed. The
secret data will be sent to that command's standard input.
@item DESTROY
This is the command to run to delete the secret when it is no longer
needed.
@item MINSHARES
This is the threshold, indicating the lowest number of shares required
to reconstruct the secret.
@ -383,15 +408,15 @@ keys), and thus wants to keep it offline most of the time.
Note that the following is only possible when using GnuPG 2.1 (or
greater).
The first thing Alice has to do is to obtain the @emph{keygrip} of her
master key:
First, Alice has to obtain both the @emph{fingerprint} and the
@emph{keygrip} of her primary (master) key:
@example
$ gpg2 --list-secret-keys --with-keygrip
/home/alice/.gnupg/pubring.kbx
------------------------------
sec rsa4096 2016-12-25 [SC] [expires: 2019-12-25]
DFF9C8A3FE6663F9DD157E16F5C95C96DD4C784D
@emph{DFF9C8A3FE6663F9DD157E16F5C95C96DD4C784D}
Keygrip = @emph{47921AA1A41065B89D2790C3EAD88922063E8AA8}
uid [ultimate] Alice Smith <alice@@example.org>
ssb rsa2048 2016-12-25 [E] [expires: 2017-12-25]
@ -400,9 +425,15 @@ ssb rsa2048 2016-12-25 [S] [expires: 2017-12-25]
Keygrip = 6BA62F5EFDB16B8F1D7407E12466166FE90424B8
@end example
The master key has the keygrip @code{47921A[...]3E8AA8}. This means
(with GnuPG 2.1) that it is stored in the file
@file{~/.gnupg/private-keys-v1.d/47921A[...]3E8AA8.key}.
Alice then asks GnuPG to export the primary private key. Note the
@emph{!} sign after the fingerprint, instructing GnuPG to export the
specified key only (without it, the subkeys would be exported along with
the primary key):
@example
$ gpg2 -o master.key --export-secret-keys \
DFF9C8A3FE6663F9DD157E16F5C95C96DD4C784D\!
@end example
Alice plugs in her removable storage devices and calls
@command{gfsec-split} with the @option{-l} option:
@ -419,18 +450,18 @@ the available devices. She thus calls @command{gfsec-split} again as
follows:
@example
$ gfsec-split -c master \
/home/alice/.gnupg/private-keys-v1.d/47921A[...]3EA88A.key \
$ gfsec-split -c master -o "" \
--restore-cmd "gpg2 --import -" \
--destroy-cmd "gpg-connect-agent 'DELETE_KEY --force 47921AA1A41065B89D2790C3EAD88922063E8AA8' /bye \
/home/alice/master.key \
file:///home/alice/.local/share/gfsecret/master-key \
label://USBKEY/master-key \
mtp://RF2GB6X704P/Documents/master-key
@end example
Here, Alice explicitly sets the name of the configuration file to
generate (with the @option{-c} option). The default behavior of
@command{gfsec-split} would have created a configuration file named with
the 40 characters of the keygrip, which would have been especially
impractical.
Note the @option{--restore-cmd} and @option{--destroy-cmd} options,
which specify the commands that will be called to restore and destroy
again the private key, respectively.
If the command succeeded, Alice can check with GnuPG that her master key
is indeed no longer available:
@ -449,6 +480,25 @@ ssb rsa2048 2016-12-25 [S] [expires: 2017-12-25]
Note the @code{#} symbol following the @code{sec} keyword: it indicates
that the corresponding private key is not available.
Starting from version 0.4.3, the Gfsecret package comes with a shell
script called @command{gfsec-split-gpg} which facilitates the above
procedure. It dispenses Alice from having to find the fingerprint and
the keygrip of her key and to export it from the GnuPG keyring. All she
has to do is to run the following command:
@example
$ gfsec-split-use -c master -u alice \
file:///home/alice/.local/share/gfsecret/master-key \
label://USBKEY/master-key \
mtp://RF2GB6X704P/Documents/master-key
About to split the following key:
User ID: Alice Smith <alice@@example.org>
Fingerprint: DFF9C8A3FE6663F9DD157E16F5C95C96DD4C784D
Keygrip: 47921AA1A41065B89D2790C3EAD88922063E8AA8
Proceed (y/N):
@end example
Later on, Alice obtains Bob's public key and wants to certify it. For
that, she needs her master private key. In order to reconstruct it, she
calls @command{gfsec-use} with the name of the configuration file she

Loading…
Cancel
Save