Some additions to the EasyPG Assistant's manual

Some additions to the EasyPG Assistant's manual

[Jens Schmidt]

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

Hi,

I have been setting up GnuPG for Emacs/EPA lately for transparent file
encryption and decryption, and done so for the first time.  I've
condensed my experiences in some additions to the EPA texi file, see 
attached patch.  Of course, such experiences are highly personal, but at 
least on Stackoverflow others have been struggling with the same issues 
as I did ...

This patch still needs some brushing up, and some splitting up probably
as well.  It is based on emacs-29.

Just wanted to check whether the additions are by and large OK the way
they are.

WDYT?

[-- Attachment #2: epa.texi.patch --]
[-- Type: text/x-patch, Size: 7914 bytes --]

diff --git a/doc/misc/epa.texi b/doc/misc/epa.texi
index 6f63a3d7ba0..f416e9eb667 100644
--- a/doc/misc/epa.texi
+++ b/doc/misc/epa.texi
@@ -61,6 +61,7 @@ Top
 * Quick start::
 * Commands::
 * GnuPG version compatibility::
+* GnuPG Pinentry::
 * Caching Passphrases::
 * Bug Reports::
 * GNU Free Documentation License::  The license for this documentation.
@@ -72,7 +73,8 @@ Top
 @node Overview
 @chapter Overview
 
-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.
@@ -86,6 +88,16 @@ Overview
 @node Quick start
 @chapter Quick start
 
+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}.
+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 @url{https://gnupg.org/documentation/guides.html, the GnuPG user
+guides}, provides an introduction to GnuPG use and configuration.
+
 EasyPG Assistant commands are prefixed by @samp{epa-}.  For example,
 
 @itemize @bullet
@@ -368,6 +380,39 @@ 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 new 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},
+see below.
+
+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.
+
+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 encryption is performed with your
+public key, no passphrase is prompted for the buffer save, but you
+will be prompted for your passphrase for file reads every now and
+then, depending on the gpg-agent cache configuration.
+
+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 to be encrypted or decrypted.  It
+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}.
 
@@ -436,6 +481,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
@@ -461,8 +511,8 @@ Querying a key server
 @node GnuPG version compatibility
 @chapter GnuPG version compatibility
 
-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
+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.
 
@@ -490,17 +540,71 @@ GnuPG version compatibility
 graphical prompt.
 @end itemize
 
+
+@node GnuPG Pinentry
+@chapter GnuPG Pinentry
+
+An important component of the GnuPG suite is the Pinentry, which
+allows for secure entry of passphrases requests by GnuPG.  GnuPG
+delivers various different programs as Pinentry, ranging from bland
+TTY-only @samp{pinentry-tty} to fancy graphical dialogues for various
+desktop environments, like @samp{pinentry-gnome3}.  Your operating
+system usually determines which of these is used by default.
+
+With some configuration Emacs can also play the role of a Pinentry.
+There are three different scenarios possible@footnote{Not all
+operating systems and distributions support all of the above
+scenarios.  As of June 2023 Debian GNU/Linux, for example, supports
+only the first of them due to security concerns.}:
+
+@enumerate
+@item Use Emacs only for GnuPG requests that are triggered by Emacs itself,
+@item use Emacs for all GnuPG requests, or
+@item use Emacs for all GnuPG requests with other Pinentry as fallback.
+@end enumerate
+
+FIXME: Brush the following paragraphs up.
+
+1.: Ensure allow-loopback-pinentry is is configured for the GPG agent,
+which should be the default.  Configure epg-pinentry-mode to
+`loopback.
+
+2.: Make pinentry-emacs the default pinentry by means of your
+operating system.  Install package pinentry from GNU ELPA and execute
+M-x pinentry-start to start the Pinentry service.  All GnuPG
+passphrase requests should result in a minibuffer prompt in the
+running Emacs.  If Emacs or pinentry service are not running,
+passphrase requests fail.
+
+3.: Ensure other Pinentry supports Emacs prompt.  pinentry-curses
+does, for example.  Configure option allow-emacs-pinentry in
+gpg-agent.conf.  Set environment variable INSIDE_EMACS for the calling
+process.  Install package pinentry.  Now if Emacs is running and
+pinentry-start has been exeucted, all GnuPG passphrase requests should
+result in a minibuffer prompt in the running Emacs.  If Emacs or
+Pinentry service are not running, GnuPG uses the regular Pinentry
+instead.
+
+First alternative can be configured in addition to onw of the others:
+Requests triggered from within Emacs (like opening a gpg-encrypted
+file) are handled through loopback pinentry, Requests outside of emacs
+through pinentry feature.
+
+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 @xref{Caching Passphrases}.
+
 @node Caching Passphrases
 @chapter 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
+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 (which is mandatory for GnuPG 2.0 and later).  Here are some
 questions:
 
 @enumerate

Re: Some additions to the EasyPG Assistant's manual

[Eli Zaretskii]

> Date: Sun, 11 Jun 2023 20:00:12 +0200
> From: Jens Schmidt <jschmidt4gnu@vodafonemail.de>
> 
> Hi,
> 
> I have been setting up GnuPG for Emacs/EPA lately for transparent file
> encryption and decryption, and done so for the first time.  I've
> condensed my experiences in some additions to the EPA texi file, see 
> attached patch.  Of course, such experiences are highly personal, but at 
> least on Stackoverflow others have been struggling with the same issues 
> as I did ...
> 
> This patch still needs some brushing up, and some splitting up probably
> as well.  It is based on emacs-29.

Please in the future post patches via "M-x report-emacs-bug".

> +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".

> +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 new buffer
> +@file{*Keys*} where you can select recipients for encryption.

I don't think "new" is right here: Emacs generally reuses buffers that
already exist.  I'd drop "new" there.

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

> +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.

> +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
                                                 ^
A comma is missing there.

> +also use some free-form string that gives information on the use of
> +the keypair, like @code{backup} or @code{account database}.} you can
                                                               ^
Another comma missing there.

> +encryption for that file.  Since encryption is performed with your
> +public key, no passphrase is prompted for the buffer save, but you
> +will be prompted for your passphrase for file reads every now and
> +then, depending on the gpg-agent cache configuration.

Passive voice alert!

> +@xref{Caching Passphrases} for more information.
                             ^
Comma after the closing brace is missing.

> +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?

> +@node GnuPG Pinentry
> +@chapter GnuPG Pinentry

Pleased add an index entry for the subject of this chapter.  In
general, it is a good idea to have an index entry for each
chapter/section/subsection naming is main subject.

> +@enumerate
> +@item Use Emacs only for GnuPG requests that are triggered by Emacs itself,
> +@item use Emacs for all GnuPG requests, or
> +@item use Emacs for all GnuPG requests with other Pinentry as fallback.

The capitalization if these items is inconsistent.

> +FIXME: Brush the following paragraphs up.

??

> +1.: Ensure allow-loopback-pinentry is is configured for the GPG agent,
> +which should be the default.  Configure epg-pinentry-mode to
> +`loopback.
> +
> +2.: Make pinentry-emacs the default pinentry by means of your
> +operating system.  Install package pinentry from GNU ELPA and execute
> +M-x pinentry-start to start the Pinentry service.  All GnuPG
> +passphrase requests should result in a minibuffer prompt in the
> +running Emacs.  If Emacs or pinentry service are not running,
> +passphrase requests fail.
> +
> +3.: Ensure other Pinentry supports Emacs prompt.  pinentry-curses
> +does, for example.  Configure option allow-emacs-pinentry in
> +gpg-agent.conf.  Set environment variable INSIDE_EMACS for the calling
> +process.  Install package pinentry.  Now if Emacs is running and
> +pinentry-start has been exeucted, all GnuPG passphrase requests should
> +result in a minibuffer prompt in the running Emacs.  If Emacs or
> +Pinentry service are not running, GnuPG uses the regular Pinentry
> +instead.
> +
> +First alternative can be configured in addition to onw of the others:
> +Requests triggered from within Emacs (like opening a gpg-encrypted
> +file) are handled through loopback pinentry, Requests outside of emacs
> +through pinentry feature.
> +
> +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 @xref{Caching Passphrases}.

This doesn't seem to be finalized?

> +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
                ^^^^^
Here, a @pxref in parentheses is TRT.

Thanks.

Re: Some additions to the EasyPG Assistant's manual

[Jens Schmidt]

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

> Please in the future post patches via "M-x report-emacs-bug".

Will do, even for this issue.  Actually, I only wanted to know whether
my additions are welcome in the EPA manual at all.  I take your detailed
review as "yes" and will process it as a new bug.

Thanks for your effort with this and all of my other recent
contributions - feeling at home here right from the start!

Re: Some additions to the EasyPG Assistant's manual

[Eli Zaretskii]

> Date: Sun, 18 Jun 2023 11:00:46 +0200
> Cc: emacs-devel@gnu.org
> From: Jens Schmidt <jschmidt4gnu@vodafonemail.de>
> 
> On 2023-06-17  09:44, Eli Zaretskii wrote:
> 
> > Please in the future post patches via "M-x report-emacs-bug".
> 
> Will do, even for this issue.  Actually, I only wanted to know whether
> my additions are welcome in the EPA manual at all.  I take your detailed
> review as "yes" and will process it as a new bug.

Yes, please do, and thanks.