bug#64154: Some additions to the EasyPG Assistant's manual

[Jens Schmidt via "Bug reports for GNU Emacs, the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>]

[-- Attachment #1: Type: text/plain, Size: 2428 bytes --]

So after setting up the concept index, here comes what I originally
intended to add to epa.texi.  Plus my comments on you first review
(https://debbugs.gnu.org/cgi/bugreport.cgi?bug=64154#8) where I have
additional questions.  Unless otherwise stated I followed your
recommendations, however.

On 2023-06-17  09:44, Eli Zaretskii wrote:

>> +You can use EasyPG Assistant without any Emacs or GnuPG configuration
>> +whatsoever, for example to encrypt and decrypt files automatically
>> +with symmetric encryption, @xref{Encrypting/decrypting gpg files}.
>                                ^^^^^
> You want "see @ref" here, not @xref.  The latter is only pertinent at
> the beginning of a sentence, because it produces a capitalized "See".

Understood.  Actually, I copied the habit of the original authors there.
I fixed my own inappropriate @xrefs plus theirs.

>> +@xref{Key management} for a description of the format of that
>> buffer.
>                        ^
> Comma missing there.  Some old version of Texinfo need it.

I changed these as you have proposed.  But TBH I find that comma rather
disturbing.  This might be a non-native speaker's view, but isn't then

   "See @ref{Key management} for a description ...

easier to read *and* clearer in the texi file?  Or, IOW, do we *have* to
use @xref at the beginning of sentences because it has some other nice
properties?  Same question for @pxref?

>> +You can streamline this recipient selection step by customizing
>> +variables @code{epa-file-encrypt-to} and @code{epa-file-select-keys},
>> +see below.
> 
> Instead of "see below", please add a cross-reference to the node where
> these variables are documented.

Actually, here "see below" refers to the same node.  I use now "...
described further below in this section" to clarify that.

>> +As of June 2023, there are three active branches of GnuPG: 2.4,
>> +2.2, and 1.4.  All those branches should work flawlessly with Emacs
>>   with basic use-cases.  They have, however, some incompatible
>>   characteristics, which might be visible when used from Emacs.
> 
> Given the known issues with GnuPG 2.4.1, do we need to say something
> about that here?

Done that.

Finally, I noticed that node "GnuPG and EasyPG Assistant
Configuration(auth)" duplicates some of the information in section
"Caching Passphrases(epa)", which means that these will be out of sync
as soon as my changes have landed.  WDYT about that?

[-- Attachment #2: 0002-Add-basic-usage-information-and-fix-references.patch --]
[-- Type: text/x-patch, Size: 13886 bytes --]

From a789918509e5292b8e883012a1b4a03d740506a9 Mon Sep 17 00:00:00 2001
From: Jens Schmidt <jschmidt4gnu@vodafonemail.de>
Date: Sat, 8 Jul 2023 22:19:45 +0200
Subject: [PATCH] Add basic usage information and fix references

* doc/misc/epa.texi (Top): Add menu entry for new node GnuPG Pinentry.
(Quick Start): Add information on and reference to basic GnuPG
configuration.
(Encrypting/decrypting gpg files): Add usage information.
(GnuPG version compatibility): Update version information.  Change
footnote referring to loopback pinentry to reference to new node GnuPG
pinentry.
(GnuPG Pinentry): Add new node.
(Caching Passphrases): Describe mandatory gpg-agent usage for GnuPG
2.0 and later.
(Overview, Encrypting/decrypting gpg files, Caching Passphrases)
(Bug Reports): Fix references.  (Bug#64154)
---
 doc/misc/epa.texi | 195 +++++++++++++++++++++++++++++++++++++---------
 1 file changed, 160 insertions(+), 35 deletions(-)

diff --git a/doc/misc/epa.texi b/doc/misc/epa.texi
index edfe37de816..94e7447c927 100644
--- a/doc/misc/epa.texi
+++ b/doc/misc/epa.texi
@@ -70,6 +70,7 @@ Top
 * Quick start::
 * Commands::
 * GnuPG version compatibility::
+* GnuPG Pinentry::
 * Caching Passphrases::
 * Bug Reports::
 * GNU Free Documentation License::  The license for this documentation.
@@ -83,7 +84,8 @@ Overview
 @chapter Overview
 @cindex features of easypg assistant
 
-EasyPG Assistant provides the following features.
+EasyPG Assistant is an Emacs frontend application to @acronym{GnuPG,
+GNU Privacy Guard} that provides the following features:
 
 @itemize @bullet
 @item Key management.
@@ -97,6 +99,22 @@ Overview
 @node Quick start
 @chapter Quick Start
 @cindex introduction to easypg assistant
+@cindex gnupg documentation
+@cindex documentation on gnupg
+@cindex configuration of gnupg
+@cindex introduction to gnupg
+
+You can use EasyPG Assistant without any Emacs or GnuPG configuration
+whatsoever, for example to encrypt and decrypt files automatically
+with symmetric encryption, see @ref{Encrypting/decrypting gpg files}.
+However, to use the full set of EasyPG Assistant's functions you
+should have at least some minimum GnuPG configuration in place.
+
+John Michael Ashley's GNU Privacy Handbook, available online as part
+of @uref{https://gnupg.org/documentation/guides.html, the GnuPG user
+guides}, provides an introduction to GnuPG use and configuration.  In
+contrast to that, the GnuPG manual (@pxref{Top, , Top, gnupg, Using
+the GNU Privacy Guard}) is more of of a reference manual.
 
 EasyPG Assistant commands are prefixed by @samp{epa-}.  For example,
 
@@ -410,6 +428,42 @@ Encrypting/decrypting gpg files
 Similarly, when you save the buffer to a @file{foo.gpg} file,
 encrypted data is written.
 
+When you save a buffer, say, to file @file{foo.gpg} for the first
+time, EasyPG Assistant presents you a list of keys in a buffer
+@file{*Keys*} where you can select recipients for encryption.
+@xref{Key management}, for a description of the format of that buffer.
+You can streamline this recipient selection step by customizing
+variables @code{epa-file-encrypt-to} and @code{epa-file-select-keys}
+described further below in this section.
+
+@cindex symmetric encryption, passphrase entry for
+If you do not select any recipient during this step, EasyPG Assistant
+uses symmetric encryption.  As a consequence, you have to enter the
+passphrase twice for every buffer save and every so often for file
+reads, since the gpg-agent caches your passphrase for file reads at
+least for some time, but not for buffer saves.
+
+@cindex public key encryption, passphrase entry for
+If you have created your own keypair@footnote{For encryption and
+decryption of files you do not intend to share, you do not have to use
+an email address as recipient during creation of the keypair.  You can
+also use some free-form string that gives information on the use of
+the keypair, like @code{backup} or @code{account database}.}, you can
+select that as recipient, and EasyPG Assistant uses public key
+encryption for that file.  Since GnuPG performs encryption with your
+public key, it does not prompt for a passphrase for the buffer save,
+but it will prompt for your passphrase for file reads every now and
+then, depending on the gpg-agent cache configuration.
+
+@cindex tempory files created by easypg assistant
+To encrypt and decrypt files as described above EasyPG Assistant under
+certain circumstances uses intermediate tempory files that contain the
+plain-text contents of the files it processes.  EasyPG Assistant
+creates them below the directory returned by function
+@code{temporary-file-directory}.  If you want to be sure not to leave
+any plain-text traces, use an encrypted file systems at least for that
+directory.
+
 The file name pattern for encrypted files can be controlled by
 @code{epa-file-name-regexp}.
 
@@ -447,9 +501,9 @@ Encrypting/decrypting gpg files
 @end defvar
 
 For frequently visited files, it might be a good idea to tell Emacs
-which encryption method should be used through @xref{File Variables, ,
-, emacs, the Emacs Manual}.  Use the @code{epa-file-encrypt-to} local
-variable for this.
+which encryption method should be used through file variables
+(@pxref{File Variables, , Local Variables in Files, emacs, The Emacs
+Editor}).  Use the @code{epa-file-encrypt-to} local variable for this.
 @vindex epa-file-encrypt-to
 
 For example, if you want an Elisp file to be encrypted with a
@@ -478,6 +532,11 @@ Encrypting/decrypting gpg files
 @defvar epa-file-cache-passphrase-for-symmetric-encryption
 If non-@code{nil}, cache passphrase for symmetric encryption.  The
 default value is @code{nil}.
+
+For security reasons, this option is turned off by default and not
+recommended to use.  Instead, consider using the gpg-agent, which in
+many cases can do the same job, and does it in a safer way.
+@xref{Caching Passphrases}, for more information.
 @end defvar
 
 @defvar epa-file-inhibit-auto-save
@@ -507,10 +566,17 @@ GnuPG version compatibility
 @cindex version compatibility with gnupg
 @cindex compatibility with gnupg
 
-As of February 2016, there are three active branches of GnuPG: 2.1,
-2.0, and 1.4.  All those branches should work flawlessly with Emacs
-with basic use-cases.  They have, however, some incompatible
-characteristics, which might be visible when used from Emacs.
+As of June 2023, there are three active branches of GnuPG: 2.4, 2.2,
+and 1.4.  GnuPG versions 2.4.1 and later suffer from
+@uref{https://dev.gnupg.org/T6481, GnuPG bug T6481} and are hardly
+usable with Emacs.  There is a patch for that bug available at least
+for GnuPG version 2.4.1, which your operating system or distribution
+might provide already.  GnuPG 1.4 is considered a legacy version.
+
+Besides that, all of those branches mentioned above should work
+flawlessly with Emacs with basic use-cases.  They have, however, some
+incompatible characteristics, which might be visible when used from
+Emacs.
 
 @itemize
 @item
@@ -526,16 +592,77 @@ GnuPG version compatibility
 
 @item
 GnuPG 2.1 (2.1.5 or later) has a mechanism to direct the Pinentry
-password prompt to the Emacs minibuffer@footnote{To enable this
-feature, add @samp{allow-emacs-pinentry} to
-@file{~/.gnupg/gpg-agent.conf} and let gpg-agent reload the
-configuration, with: @samp{gpgconf --reload gpg-agent}}, which would
-be useful when you use Emacs remotely or from a text-only terminal.
-That feature is not available in other versions, and more
-specifically, with 2.0 (as of 2.0.29), there is no way to avoid the
-graphical prompt.
+password prompt to the Emacs minibuffer.  @xref{GnuPG Pinentry}.
 @end itemize
 
+@node GnuPG Pinentry
+@chapter GnuPG Pinentry
+@cindex gnupg pinentry
+@cindex pinentry provided by gnupg
+
+An important component of the GnuPG suite is the Pinentry, which
+allows for secure entry of passphrases requested by GnuPG.  GnuPG
+delivers various different programs as Pinentry, ranging from bland
+TTY-only @samp{pinentry-tty} to fancy graphical dialogs for various
+desktop environments, like @samp{pinentry-gnome3}.  Your operating
+system usually determines which of these is used by default.
+
+Note that the selection of a concrete Pinentry program determines only
+@emph{how} GnuPG queries for passphrases and not @emph{how often}.
+For the latter question see @ref{Caching Passphrases}.
+
+@cindex pinentry, emacs as
+With some configuration Emacs can also play the role of a Pinentry.
+The most natural choice, available with GnuPG 2.1.5 and later, is to
+use Emacs itself as Pinentry for requests that are triggered by Emacs.
+For example, if you open a file whose name ends with @file{.gpg} using
+automatic decryption, you most likely also want to enter the
+passphrase for that request in Emacs.
+
+@cindex loopback pinentry
+This so called loopback Pinentry has the added benefit that it works
+also when you use Emacs remotely or from a text-only terminal.  To
+enable it:
+
+@enumerate
+@item
+Ensure that option @code{allow-loopback-pinentry} is configured for
+gpg-agent, which should be the default.
+
+@item
+Customize variable @code{epg-pinentry-mode} to @code{loopback} in
+Emacs.
+@end enumerate
+
+There are other options available to use Emacs as Pinentry, you might
+come across a Pinentry called @code{pinentry-emacs} or gpg-agent
+option @code{allow-emacs-pinentry}.  However, these are considered
+insecure or semi-obsolete and might not be supported by your operating
+system or distribution.  For example, Debian GNU/Linux supports only
+the loopback Pinentry described above.
+
+@c In case somebody requests these:
+@c
+@c Use Emacs for all GnuPG requests:
+@c
+@c Make pinentry-emacs the default Pinentry by means of your operating
+@c system.  Install package pinentry.el from GNU ELPA and execute M-x
+@c pinentry-start to start the Emacs Pinentry service.  *All* GnuPG
+@c passphrase requests should then result in a minibuffer prompt in
+@c the running Emacs.  If Emacs or the Emacs Pinentry service are not
+@c running, passphrase requests fail.
+@c
+@c Use Emacs for all GnuPG requests with other Pinentry as fallback:
+@c
+@c Ensure the other Pinentry supports Emacs prompt.  pinentry-curses
+@c does, for example.  Configure option allow-emacs-pinentry in
+@c gpg-agent.conf.  Set environment variable INSIDE_EMACS for the
+@c calling process.  Install package pinentry.el.  Now if Emacs is
+@c running and M-x pinentry-start has been executed, all GnuPG
+@c passphrase requests should result in a minibuffer prompt in the
+@c running Emacs.  If Emacs or the Emacs Pinentry service are not
+@c running, GnuPG uses the other Pinentry instead.
+
 @node Caching Passphrases
 @chapter Caching Passphrases
 @cindex caching passphrases
@@ -545,15 +672,15 @@ Caching Passphrases
 Typing passphrases is a troublesome task if you frequently open and
 close the same file.  GnuPG and EasyPG Assistant provide mechanisms to
 remember your passphrases for a limited time.  Using these, you only
-need to re-enter the passphrase occasionally.
-However, the configuration is a bit
-confusing since it depends on your GnuPG installation@xref{GnuPG
-version compatibility}, encryption method (symmetric or public key),
-and whether or not you want to use gpg-agent.  Here are some
-questions:
+need to re-enter the passphrase occasionally.  However, the
+configuration is a bit confusing since it depends on your GnuPG
+installation (@pxref{GnuPG version compatibility}), encryption method
+(symmetric or public key), and whether or not you want to use
+gpg-agent.  As an additional constraint, use of the gpg-agent is
+mandatory for GnuPG 2.0 and later.  Here are some questions:
 
 @enumerate
-@item Do you use GnuPG version 2.1 or 2.0 instead of GnuPG version 1.4?
+@item Do you use GnuPG version 2.0 or later instead of GnuPG version 1.4?
 @item Do you use symmetric encryption rather than public key encryption?
 @item Do you want to use gpg-agent?
 @end enumerate
@@ -562,18 +689,16 @@ Caching Passphrases
 
 @multitable {111} {222} {333} {configuration configuration configuration}
 @item @b{1} @tab @b{2} @tab @b{3} @tab Configuration
-@item Yes @tab Yes @tab Yes @tab Set up gpg-agent.
-@item Yes @tab Yes @tab No @tab You can't, without gpg-agent.
-@item Yes @tab No @tab Yes @tab Set up gpg-agent.
-@item Yes @tab No @tab No @tab You can't, without gpg-agent.
-@item No @tab Yes @tab Yes @tab Set up elisp passphrase cache.
-@item No @tab Yes @tab No @tab Set up elisp passphrase cache.
-@item No @tab No @tab Yes @tab Set up gpg-agent.
-@item No @tab No @tab No @tab You can't, without gpg-agent.
+@item Yes   @tab Yes   @tab Must  @tab Set up gpg-agent.
+@item Yes   @tab No    @tab Must  @tab Set up gpg-agent.
+@item No    @tab Yes   @tab Yes   @tab Set up elisp passphrase cache.
+@item No    @tab Yes   @tab No    @tab Set up elisp passphrase cache.
+@item No    @tab No    @tab Yes   @tab Set up gpg-agent.
+@item No    @tab No    @tab No    @tab You can't, without gpg-agent.
 @end multitable
 
-To set up gpg-agent, follow the instruction in GnuPG manual.
-@pxref{Invoking GPG-AGENT, , Invoking GPG-AGENT, gnupg}.
+To set up gpg-agent, follow the instruction in @ref{Invoking
+GPG-AGENT, , , gnupg, Using the GNU Privacy Guard}.
 
 To set up elisp passphrase cache, set
 @code{epa-file-cache-passphrase-for-symmetric-encryption}.
@@ -586,8 +711,8 @@ Bug Reports
 
 Bugs and problems with EasyPG Assistant are actively worked on by the
 Emacs development team.  Feature requests and suggestions are also
-more than welcome.  Use @kbd{M-x report-emacs-bug}, @pxref{Bugs, ,
-Bugs, emacs, Reporting Bugs}.
+more than welcome.  Use @kbd{M-x report-emacs-bug}, see @ref{Bugs, ,
+Reporting Bugs, emacs, The Emacs Editor}.
 
 When submitting a bug report, please try to describe in excruciating
 detail the steps required to reproduce the problem.  Also try to
-- 
2.30.2