From: Jens Schmidt via "Bug reports for GNU Emacs, the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>
To: Eli Zaretskii <eliz@gnu.org>
Cc: 64154@debbugs.gnu.org
Subject: bug#64154: Some additions to the EasyPG Assistant's manual
Date: Sun, 9 Jul 2023 16:41:05 +0200 [thread overview]
Message-ID: <b1fa6fcc-ad3d-64cb-c4d2-df6ca7602e13@vodafonemail.de> (raw)
In-Reply-To: <83sf9x9vgp.fsf@gnu.org>
[-- Attachment #1: Type: text/plain, Size: 975 bytes --]
On 2023-07-09 13:26, Eli Zaretskii wrote:
> There's no need to fix everything (although you get bonus points for
> doing so), it is enough not to add such problems in new text.
Turned out that most references were mine, anyway, so little bonus. I
changed them to "GnuPG Agent" where the "abstract agent" more likely is
being referred to and to @command{gpg-agent} where the "concrete
command" is meant. (The GnuPG manual is, um, extremely inconsistent in
naming this thing, so nothing to be learnt from it.)
Other than that I followed your proposals, new patch attached.
There is this one open question regarding a completely different manual
("Emacs auth-source") from one of my previous mails, though:
> Finally, I noticed that section "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: 15152 bytes --]
From 0d3d5fc6afc25fefd7f48f5b7f520637a8670f7a Mon Sep 17 00:00:00 2001
From: Jens Schmidt <jschmidt4gnu@vodafonemail.de>
Date: Sun, 9 Jul 2023 16:17:27 +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.
(GnuPG Pinentry): Add new node.
(Caching Passphrases): Describe mandatory gpg-agent usage for GnuPG
2.0 and later.
(Overview, Encrypting/decrypting gpg files, GnuPG version compatibility)
(Caching Passphrases, Bug Reports): Fix references, terminology,
mark-up, and index entries. (Bug#64154)
---
doc/misc/epa.texi | 216 +++++++++++++++++++++++++++++++++++++---------
1 file changed, 175 insertions(+), 41 deletions(-)
diff --git a/doc/misc/epa.texi b/doc/misc/epa.texi
index edfe37de816..917fd588593 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 a reference manual.
EasyPG Assistant commands are prefixed by @samp{epa-}. For example,
@@ -410,6 +428,44 @@ 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 to an encrypted file 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 GnuPG Agent caches your passphrase for file reads at
+least for some time, but not for buffer saves. @xref{Caching
+Passphrases}, for more information.
+
+@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 will use 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 GnuPG 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} (@pxref{Unique File Names, ,
+Generating Unique File Names, elisp, GNU Emacs Lisp Reference
+Manual}). 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}.
@@ -446,11 +502,11 @@ Encrypting/decrypting gpg files
Control whether or not to pop up the key selection dialog.
@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.
@vindex epa-file-encrypt-to
+For frequently visited files, it might be a good idea to tell Emacs
+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.
For example, if you want an Elisp file to be encrypted with a
public key associated with an email address @samp{ueno@@unixuser.org},
@@ -478,6 +534,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 be used. Instead, consider using the GnuPG 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 +568,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
@@ -519,23 +587,91 @@ GnuPG version compatibility
@item
GnuPG 2.1 uses a fixed address for the Unix domain socket used to
-communicate with gpg-agent. The @code{GPG_AGENT_INFO} environment
-variable, which is used by GnuPG 2.0 and 1.4, is ignored. That means,
-if your system has both GnuPG 2.1 and 1.4, the gpg command from GnuPG
-1.4 is not able to use gpg-agent provided by 2.1 (at least out of box).
+communicate with @command{gpg-agent}. The @code{GPG_AGENT_INFO}
+environment variable, which is used by GnuPG 2.0 and 1.4, is ignored.
+That means, if your system has both GnuPG 2.1 and 1.4, the gpg command
+from GnuPG 1.4 is not able to use @command{gpg-agent} provided by 2.1
+(at least out of box).
@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 @command{pinentry-tty} to fancy graphical dialogs for various
+desktop environments, like @command{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 @dfn{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
+@vindex allow-loopback-pinentry
+Ensure that option @code{allow-loopback-pinentry} is configured for
+@command{gpg-agent}, which should be the default. @xref{Agent
+Options, , Option Summary, gnupg, Using the GNU Privacy Guard}.
+
+@item
+@vindex epg-pinentry-mode
+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 @command{pinentry-emacs} or
+@command{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.
+
+@ignore
+In case somebody requests these:
+
+Use Emacs for all GnuPG requests:
+
+Make @command{pinentry-emacs} the default Pinentry by means of your
+operating system. Install package @file{pinentry.el} from GNU ELPA
+and execute @kbd{M-x pinentry-start} to start the Emacs Pinentry
+service. @emph{All} GnuPG passphrase requests should then result in a
+minibuffer prompt in the running Emacs. If Emacs or the Emacs
+Pinentry service are not running, passphrase requests fail.
+
+Use Emacs for all GnuPG requests with other Pinentry as fallback:
+
+Ensure the other Pinentry supports Emacs; @command{pinentry-curses}
+does, for example. Configure @command{gpg-agent} option
+@code{allow-emacs-pinentry}. Set environment variable
+@code{INSIDE_EMACS} for the calling process. Install package
+@file{pinentry.el}. Now if Emacs is running and @kbd{M-x
+pinentry-start} has been executed, all GnuPG passphrase requests
+should result in a minibuffer prompt in the running Emacs. If Emacs
+or the Emacs Pinentry service are not running, GnuPG uses the other
+Pinentry instead.
+@end ignore
+
@node Caching Passphrases
@chapter Caching Passphrases
@cindex caching passphrases
@@ -545,35 +681,33 @@ 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
+GnuPG Agent. As an additional constraint, use of the GnuPG 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?
+@item Do you want to use GnuPG Agent?
@end enumerate
Here are configurations depending on your answers:
@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 GnuPG Agent.
+@item Yes @tab No @tab Must @tab Set up GnuPG 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 GnuPG Agent.
+@item No @tab No @tab No @tab You can't, without GnuPG 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 GnuPG 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 +720,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
next prev parent reply other threads:[~2023-07-09 14:41 UTC|newest]
Thread overview: 33+ messages / expand[flat|nested] mbox.gz Atom feed top
[not found] <dcb43cbb-61aa-417a-7da0-1b86223038ef@vodafonemail.de>
[not found] ` <83wn02r0s7.fsf@gnu.org>
2023-06-18 17:32 ` bug#64154: Fwd: Some additions to the EasyPG Assistant's manual Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors
2023-06-29 21:10 ` bug#64154: 29.0.92; Provide additional details on GnuPG and EPA usage in epa.texi Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors
2023-06-30 5:54 ` Eli Zaretskii
2023-06-30 19:13 ` Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors
2023-06-30 19:32 ` Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors
2023-06-30 20:54 ` Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors
2023-07-01 6:01 ` Eli Zaretskii
2023-07-01 11:13 ` Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors
2023-07-01 11:57 ` Eli Zaretskii
2023-07-01 16:56 ` Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors
2023-07-01 17:19 ` Eli Zaretskii
2023-07-01 17:56 ` Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors
2023-07-01 18:49 ` Eli Zaretskii
2023-07-01 20:20 ` Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors
2023-07-02 4:59 ` Eli Zaretskii
2023-07-02 7:13 ` Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors
2023-07-02 8:18 ` Eli Zaretskii
2023-07-02 11:54 ` Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors
2023-07-02 12:16 ` Eli Zaretskii
2023-07-02 11:55 ` Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors
2023-07-02 12:18 ` Eli Zaretskii
2023-07-01 5:37 ` Eli Zaretskii
2023-07-02 2:15 ` Richard Stallman
2023-07-02 7:34 ` Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors
2023-07-08 20:31 ` 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
2023-07-09 7:24 ` Eli Zaretskii
2023-07-09 10:18 ` Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors
2023-07-09 11:26 ` Eli Zaretskii
2023-07-09 14:41 ` Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors [this message]
2023-07-11 11:02 ` Eli Zaretskii
2023-07-11 20:24 ` Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors
2023-07-13 7:52 ` Eli Zaretskii
2023-07-13 18:46 ` Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.gnu.org/software/emacs/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=b1fa6fcc-ad3d-64cb-c4d2-df6ca7602e13@vodafonemail.de \
--to=bug-gnu-emacs@gnu.org \
--cc=64154@debbugs.gnu.org \
--cc=eliz@gnu.org \
--cc=jschmidt4gnu@vodafonemail.de \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).