From 02e05e28e7d2bb26b0995861bacde42d89a22990 Mon Sep 17 00:00:00 2001 From: Werner Koch Date: Wed, 22 Jul 2009 10:24:46 +0000 Subject: [PATCH] Give hints on files to backup. --- doc/ChangeLog | 5 +++++ doc/gpg-agent.texi | 41 ++++++++++++++++++++++------------------ doc/gpg.texi | 47 ++++++++++++++++++++++++++++++++-------------- doc/gpgsm.texi | 9 ++++++--- doc/sysnotes.texi | 24 ----------------------- 5 files changed, 67 insertions(+), 59 deletions(-) diff --git a/doc/ChangeLog b/doc/ChangeLog index f42972293..0ae1e188d 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,3 +1,8 @@ +2009-07-22 Werner Koch + + * gpg.texi (GPG Configuration Options): Tell what files to backup. + * sysnotes.texi: Remove some warning notes for W32. + 2009-07-20 Werner Koch * gpg.texi (Operational GPG Commands): Add a note for --send-keys. diff --git a/doc/gpg-agent.texi b/doc/gpg-agent.texi index 27946c025..437d20f67 100644 --- a/doc/gpg-agent.texi +++ b/doc/gpg-agent.texi @@ -514,16 +514,19 @@ agent. By default they may all be found in the current home directory two dashes may not be entered and the option may not be abbreviated. This file is also read after a @code{SIGHUP} however only a few options will actually have an effect. This default name may be - changed on the command line (@pxref{option --options}). + changed on the command line (@pxref{option --options}). + You should backup this file. @item trustlist.txt - This is the list of trusted keys. Comment lines, indicated by a leading - hash mark, as well as empty lines are ignored. To mark a key as trusted - you need to enter its fingerprint followed by a space and a capital - letter @code{S}. Colons may optionally be used to separate the bytes of - a fingerprint; this allows to cut and paste the fingerprint from a key - listing output. If the line is prefixed with a @code{!} the key is - explicitly marked as not trusted. + This is the list of trusted keys. You should backup this file. + + Comment lines, indicated by a leading hash mark, as well as empty + lines are ignored. To mark a key as trusted you need to enter its + fingerprint followed by a space and a capital letter @code{S}. Colons + may optionally be used to separate the bytes of a fingerprint; this + allows to cut and paste the fingerprint from a key listing output. If + the line is prefixed with a @code{!} the key is explicitly marked as + not trusted. Here is an example where two keys are marked as ultimately trusted and one as not trusted: @@ -574,15 +577,16 @@ fails, try again using the chain validation model. @item sshcontrol This file is used when support for the secure shell agent protocol has -been enabled (@pxref{option --enable-ssh-support}). Only keys present -in this file are used in the SSH protocol. The @command{ssh-add} tool -may be used to add new entries to this file; you may also add them -manually. Comment lines, indicated by a leading hash mark, as well as -empty lines are ignored. An entry starts with optional whitespace, -followed by the keygrip of the key given as 40 hex digits, optionally -followed by the caching TTL in seconds and another optional field for -arbitrary flags. A non-zero TTL overrides the global default as -set by @option{--default-cache-ttl-ssh}. +been enabled (@pxref{option --enable-ssh-support}). Only keys present in +this file are used in the SSH protocol. You should backup this file. + +The @command{ssh-add} tool may be used to add new entries to this file; +you may also add them manually. Comment lines, indicated by a leading +hash mark, as well as empty lines are ignored. An entry starts with +optional whitespace, followed by the keygrip of the key given as 40 hex +digits, optionally followed by the caching TTL in seconds and another +optional field for arbitrary flags. A non-zero TTL overrides the global +default as set by @option{--default-cache-ttl-ssh}. The keygrip may be prefixed with a @code{!} to disable an entry entry. @@ -599,7 +603,8 @@ implicitly added to this list; i.e. there is no need to list them. This is the directory where gpg-agent stores the private keys. Each key is stored in a file with the name made up of the keygrip and the - suffix @file{key}. + suffix @file{key}. You should backup all files in this directory + and take great care to keep this backup closed away. @end table diff --git a/doc/gpg.texi b/doc/gpg.texi index 6c5ceda0f..6fdc2470a 100644 --- a/doc/gpg.texi +++ b/doc/gpg.texi @@ -485,16 +485,34 @@ For use with cron jobs, this command can be used together with a check is needed. To force a run even in batch mode add the option @option{--yes}. +@anchor{option --export-ownertrust} @item --export-ownertrust @opindex export-ownertrust Send the ownertrust values to STDOUT. This is useful for backup purposes as these values are the only ones which can't be re-created from a -corrupted trust DB. +corrupted trustdb. Example: +@c man:.RS +@example + @gpgname{} --export-ownertrust > otrust.txt +@end example +@c man:.RE + @item --import-ownertrust @opindex import-ownertrust Update the trustdb with the ownertrust values stored in @code{files} (or -STDIN if not given); existing values will be overwritten. +STDIN if not given); existing values will be overwritten. In case of a +severely damaged trustdb and if you have a recent backup of the +ownertrust values (e.g. in the file @file{otrust.txt}, you may re-create +the trustdb using these commands: +@c man:.RS +@example + cd ~/.gnupg + rm trustdb.gpg + @gpgname{} --import-ownertrust < otrust.txt +@end example +@c man:.RE + @item --rebuild-keydb-caches @opindex rebuild-keydb-caches @@ -2614,12 +2632,12 @@ current home directory (@pxref{option --homedir}). @table @file @item gpg.conf -@cindex gpgsm.conf +@cindex gpg.conf This is the standard configuration file read by @command{@gpgname} on startup. It may contain any valid long option; the leading two dashes may not be entered and the option may not be abbreviated. This default -name may be changed on the command line (@pxref{option - --options}). +name may be changed on the command line (@pxref{option --options}). +You should backup this file. @end table @@ -2639,31 +2657,32 @@ files; They all live in in the current home directory (@pxref{option @table @file @item ~/.gnupg/secring.gpg -The secret keyring. +The secret keyring. You should backup this file. @item ~/.gnupg/secring.gpg.lock -and the lock file +The lock file for teh secret keyring. @item ~/.gnupg/pubring.gpg -The public keyring +The public keyring. You should backup this file. @item ~/.gnupg/pubring.gpg.lock -and the lock file +The lock file for the public keyring. @item ~/.gnupg/trustdb.gpg -The trust database +The trust database. There is no need to backup this file; it is better +to backup the ownertrust values (@pxref{option --export-ownertrust}). @item ~/.gnupg/trustdb.gpg.lock -and the lock file +The lock file for the trust database. @item ~/.gnupg/random_seed -used to preserve the internal random pool +A file used to preserve the state of theinternal random pool. @item /usr[/local]/share/gnupg/options.skel -Skeleton options file +The skeleton options file. @item /usr[/local]/lib/gnupg/ -Default location for extensions +Default location for extensions. @end table diff --git a/doc/gpgsm.texi b/doc/gpgsm.texi index c107bf04d..18e075def 100644 --- a/doc/gpgsm.texi +++ b/doc/gpgsm.texi @@ -734,7 +734,8 @@ This is the standard configuration file read by @command{gpgsm} on startup. It may contain any valid long option; the leading two dashes may not be entered and the option may not be abbreviated. This default name may be changed on the command line (@pxref{option - --options}). + --options}). You should backup this file. + @item policies.txt @cindex policies.txt @@ -743,7 +744,8 @@ object identifiers of the policies line by line. Empty lines and lines starting with a hash mark are ignored. Policies missing in this file and not marked as critical in the certificate will print only a warning; certificates with policies marked as critical and not listed -in this file will fail the signature verification. +in this file will fail the signature verification. You should backup +this file. For example, to allow only the policy 2.289.9.9, the file should look like this: @@ -831,7 +833,8 @@ they all live in in the current home directory (@pxref{option @cindex pubring.kbx This a database file storing the certificates as well as meta information. For debugging purposes the tool @command{kbxutil} may be -used to show the internal structure of this file. +used to show the internal structure of this file. You should backup +this file. @item random_seed @cindex random_seed diff --git a/doc/sysnotes.texi b/doc/sysnotes.texi index d36c81b2f..56a0db816 100644 --- a/doc/sysnotes.texi +++ b/doc/sysnotes.texi @@ -60,30 +60,10 @@ API (called here @emph{W32}) will be supported to some extend. @node W32 Notes @section Microsoft Windows Notes -The port to Microsoft Windows based OSes is pretty new and has some -limitations we might remove over time. Note, that we have not yet done -any security audit and you should not use any valuable private key. In -particular, @strong{using it on a box with more than one user, might -lead to a key compromise}. - -@strong{It is quite possible that the current version does not even -build.} - @noindent Current limitations are: @itemize -@item -The @code{LISTKEYS} Assuan command of @command{gpgsm} is not supported. -Using the command line options @option{--list-keys} or -@option{--list-secret-keys} does however work. - -@item -No support for CRL checks. By default the option -@option{--disable-crl-checks} has been turned on and the log will show -an appropriate warning message. The reason for this is that the -separate CRL checking daemin (@command{dirmngr}) has not been ported to -W32. @item @command{gpgconf} does not create backup files, so in case of trouble @@ -97,10 +77,6 @@ possible. The periodical smartcard status checking done by @command{scdaemon} is not yet supported. -@item -Detached running of the gpg-agent is not directly supported. It needs -to be started in a console and left alone then. - @end itemize