Package: emacs;
Reported by: Jens Schmidt <jschmidt4gnu <at> vodafonemail.de>
Date: Sun, 18 Jun 2023 17:30:02 UTC
Severity: normal
Tags: patch
Found in version 29.0.92
Done: Jens Schmidt <jschmidt4gnu <at> vodafonemail.de>
Bug is archived. No further changes may be made.
Message #8 received at 64154 <at> debbugs.gnu.org (full text, mbox):
From: Jens Schmidt <jschmidt4gnu <at> vodafonemail.de> To: 64154 <at> debbugs.gnu.org Subject: Fwd: Some additions to the EasyPG Assistant's manual Date: Sun, 18 Jun 2023 19:32:29 +0200
-------- Forwarded Message --------
Subject: Re: Some additions to the EasyPG Assistant's manual
Date: Sat, 17 Jun 2023 10:44:08 +0300
From: Eli Zaretskii <eliz <at> gnu.org>
To: Jens Schmidt <jschmidt4gnu <at> vodafonemail.de>
CC: emacs-devel <at> gnu.org
> Date: Sun, 11 Jun 2023 20:00:12 +0200
> From: Jens Schmidt <jschmidt4gnu <at> 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 <at> 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.
GNU bug tracking system
Copyright (C) 1999 Darren O. Benham,
1997,2003 nCipher Corporation Ltd,
1994-97 Ian Jackson.