gpg: Improve header text of the auto-created revocations.

* g10/revoke.c (gen_standard_revoke): Improve header text for the
file.  Add info output.
--

GnuPG-bug-id: 1724
Signed-off-by: Werner Koch <wk@gnupg.org>

3 files changed, 26 insertions, 12 deletions

diff --git a/doc/DETAILS b/doc/DETAILS
index 69c2e5b00..7d5a5a81b 100644
--- a/doc/DETAILS
+++ b/doc/DETAILS
@@ -950,11 +950,6 @@ pkd:0:1024:B665B1435F4C2 .... FF26ABB:
   All other data after this header is raw image (JPEG) data.
 
 
-* Unattended key generation
-
-   Please see the GnuPG manual for a description.
-
-
 * Layout of the TrustDB
 
   The TrustDB is built from fixed length records, where the first byte
diff --git a/doc/gpg.texi b/doc/gpg.texi
index c6731c0c7..e1835cf0d 100644
--- a/doc/gpg.texi
+++ b/doc/gpg.texi
@@ -587,7 +587,9 @@ may be used.
 @item --gen-key
 @opindex gen-key
 Generate a new key pair using the current default parameters.  This is
-the standard command to create a new key.
+the standard command to create a new key.  In addition to the key a
+revocation certificate is created and stored in the
+@file{openpgp-revocs.d} directory below the GnuPG home directory.
 
 @item --full-gen-key
 @opindex gen-key
@@ -595,13 +597,23 @@ Generate a new key pair with dialogs for all options.  This is an
 extended version of @option{--gen-key}.
 
 There is also a feature which allows you to create keys in batch
-mode. See the the manual section ``Unattended key generation'' on how
+mode. See the manual section ``Unattended key generation'' on how
 to use this.
 
 @item --gen-revoke @code{name}
 @opindex gen-revoke
-Generate a revocation certificate for the complete key. To revoke
-a subkey or a signature, use the @option{--edit} command.
+Generate a revocation certificate for the complete key.  To only revoke
+a subkey or a key signature, use the @option{--edit} command.
+
+This command merely creates the revocation certificate so that it can
+be used to revoke the key if that is ever needed.  To actually revoke
+a key the created revocation certificate needs to be merged with the
+key to revoke.  This is done by importing the revocation certificate
+using the @option{--import} command.  Then the revoked key needs to be
+published, which is best done by sending the key to a keyserver
+(command @option{--send-key}) and by exporting (@option{--export}) it
+to a file which is then send to frequent communication partners.
+
 
 @item --desig-revoke @code{name}
 @opindex desig-revoke
diff --git a/g10/revoke.c b/g10/revoke.c
index ba87f3546..a8f765856 100644
--- a/g10/revoke.c
+++ b/g10/revoke.c
@@ -564,14 +564,18 @@ gen_standard_revoke (PKT_public_key *psk, const char *cache_nonce)
               (int)len, tmpstr);
   xfree (tmpstr);
 
-  es_fprintf (memfp, "%s\n\n%s\n\n:",
+  es_fprintf (memfp, "%s\n\n%s\n\n%s\n\n:",
+     _("A revocation certificate is a kind of \"kill switch\" to publicly\n"
+       "declare that a key shall not anymore be used.  It is not possible\n"
+       "to retract such a revocation certificate once it has been published."),
      _("Use it to revoke this key in case of a compromise or loss of\n"
        "the secret key.  However, if the secret key is still accessible,\n"
        "it is better to generate a new revocation certificate and give\n"
-       "a reason for the revocation."),
+       "a reason for the revocation.  For details see the description of\n"
+       "of the gpg command \"--gen-revoke\" in the GnuPG manual."),
      _("To avoid an accidental use of this file, a colon has been inserted\n"
        "before the 5 dashes below.  Remove this colon with a text editor\n"
-       "before making use of this revocation certificate."));
+       "before importing and publishing this revocation certificate."));
 
   es_putc (0, memfp);
 
@@ -583,6 +587,9 @@ gen_standard_revoke (PKT_public_key *psk, const char *cache_nonce)
   reason.code = 0x00; /* No particular reason.  */
   reason.desc = NULL;
   rc = create_revocation (fname, &reason, psk, NULL, leadin, 3, cache_nonce);
+  if (!rc && !opt.quiet)
+    log_info (_("revocation certificate stored as '%s.rev'\n"), fname);
+
   xfree (leadin);
   xfree (fname);