Browse Source

Add an "Examples" chapter to the manual

This chapter should contain real use cases for Gfsecret. For now,
it describes the use of Gfsecret for keeping a GnuPG primary key
offline, because that was my primary motivation for this project.
Damien Goutte-Gattat 5 years ago
  1. 133


@ -42,6 +42,7 @@ This manual is for Gfsecret (version @value{VERSION}, @value{UPDATED}).
* The Share URI Syntax::
* Splitting a Secret::
* Using a Splitted Secret::
* Examples::
* GNU Free Documentation License::
* Index::
@end menu
@ -357,6 +358,138 @@ This is an URI representing one of the shares, as described previously in
@end table
@node Examples
@chapter Examples
This chapter describes some precise use cases for Gfsecret.
* Keeping a GnuPG Master Key Offline::
@end menu
@node Keeping a GnuPG Master Key Offline
@section Keeping a GnuPG Master Key Offline
In this example, Alice has a GnuPG keyring containing a @emph{master
key} and two subkeys: one for signing and one for encryption. Alice only
needs her master key on rare occasions (mainly to certify other people's
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
The first thing Alice has to do is to obtain the @emph{keygrip} of her
master key:
$ gpg2 --list-secret-keys --with-keygrip
sec rsa4096 2016-12-25 [SC] [expires: 2019-12-25]
Keygrip = @emph{47921AA1A41065B89D2790C3EAD88922063E8AA8}
uid [ultimate] Alice Smith <>
ssb rsa2048 2016-12-25 [E] [expires: 2017-12-25]
Keygrip = 543E2A5037F6C5B8C655255CA76DCF5FB0D9C9C0
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
Alice plugs in her removable storage devices and calls
@command{gfsec-split} with the @option{-l} option:
$ gfsec-split -l
file:/// Local filesystem
label://USBKEY/ External volume with label 'USBKEY'
mtp://RF2GB6X704P/ Samsung Galaxy A3
@end example
Alice wants now to split her master key in three shares, one for each of
the available devices. She thus calls @command{gfsec-split} again as
$ gfsec-split \
-c /home/alice/.config/gfsecret/master.conf \
/home/alice/.gnupg/private-keys-v1.d/47921A[...]3EA88A.key \
file:///home/alice/.local/share/gfsecret/master-key \
label://USBKEY/master-key \
@end example
Here, Alice explicitly sets the name of the configuration file to
generate (with the @option{-c}). 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
If the command succeeded, Alice can check with GnuPG that her master key
is indeed no longer available:
$ gpg2 --list-secret-keys
sec# rsa4096 2016-12-25 [SC] [expires: 2019-12-25]
uid [ultimate] Alice Smith <>
ssb rsa2048 2016-12-25 [E] [expires: 2017-12-25]
ssb rsa2048 2016-12-25 [S] [expires: 2017-12-25]
@end example
Note the @code{#} symbol following the @code{sec} keyword: it indicates
that the corresponding private key is not available.
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
specified above:
$ gfsec-use -c master
Found share data in file:///home/alice/.local/share/gfsecret/master-key.070
gfsec-use: Cannot reconstitute the secret: Not enough shares available
@end example
The reconstruction attempt failed because @command{gfsec-use} found only
the share stored on the local filesystem. Alice then plugs in one of her
two removable devices and run the same command again:
$ gfsec-use -c master
Found share data in file:///home/alice/.local/share/gfsecret/master-key.070
Found share data in label://USBKEY/master-key.134
@end example
This time, the reconstruction was successful, and Alice is dropped into
a new shell in which she can do everything she needs to do with her
private key. Once she is done, she can quit that shell, and her
reconstructed key will be deleted again:
gfsec> ^D
Removing secret.
@end example
Instead of spawning a shell, Alice could also have directly invoked the
key editor of GnuPG from @command{gfsec-use}'s command line:
$ gfsec-use -c master -- gpg2 --edit-key
@end example
(Note the @code{--}: it is needed to make sure @command{gfsec-use} will
not try to parse options that belongs to @command{gpg2}, such as
@option{--edit-key} in this example.)
@node GNU Free Documentation License
@appendix GNU Free Documentation License
@include fdl.texi