From 681f5e7bb0d1225006c7c6a7ca5ec84869277692 Mon Sep 17 00:00:00 2001 From: Jens Schmidt Date: Sun, 9 Jul 2023 16:17:27 +0200 Subject: [PATCH 2/3] 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