1 \input texinfo @c -*- mode: texinfo -*-
3 @setfilename ../../info/epa.info
4 @settitle EasyPG Assistant User's Manual
11 This file describes EasyPG Assistant @value{VERSION}.
13 Copyright @copyright{} 2007--2018 Free Software Foundation, Inc.
16 Permission is granted to copy, distribute and/or modify this document
17 under the terms of the GNU Free Documentation License, Version 1.3 or
18 any later version published by the Free Software Foundation; with no
19 Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,''
20 and with the Back-Cover Texts as in (a) below. A copy of the license
21 is included in the section entitled ``GNU Free Documentation License''.
23 (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
24 modify this GNU manual.''
28 @dircategory Emacs misc features
30 * EasyPG Assistant: (epa). An Emacs user interface to GNU Privacy Guard.
34 @title EasyPG Assistant
39 @vskip 0pt plus 1filll
45 @node Top, Overview, (dir), (dir)
46 @top EasyPG Assistant user's manual
48 EasyPG Assistant is an Emacs user interface to GNU Privacy Guard
49 (GnuPG, @pxref{Top, , Top, gnupg, Using the GNU Privacy Guard}).
51 EasyPG Assistant is a part of the package called EasyPG, an all-in-one
52 GnuPG interface for Emacs. EasyPG also contains the library interface
53 called EasyPG Library.
63 * Caching Passphrases::
64 * GnuPG version compatibility::
66 * GNU Free Documentation License:: The license for this documentation.
72 @node Overview, Quick start, Top, Top
75 EasyPG Assistant provides the following features.
79 @item Cryptographic operations on regions.
80 @item Cryptographic operations on files.
81 @item Dired integration.
82 @item Mail-mode integration.
83 @item Automatic encryption/decryption of *.gpg files.
86 @node Quick start, Commands, Overview, Top
89 EasyPG Assistant commands are prefixed by @samp{epa-}. For example,
92 @item To browse your keyring, type @kbd{M-x epa-list-keys}
94 @item To create a cleartext signature of the region, type @kbd{M-x epa-sign-region}
96 @item To encrypt a file, type @kbd{M-x epa-encrypt-file}
99 EasyPG Assistant provides several cryptographic features which can be
100 integrated into other Emacs functionalities. For example, automatic
101 encryption/decryption of @file{*.gpg} files.
103 @node Commands, GnuPG version compatibility, Quick start, Top
106 This chapter introduces various commands for typical use cases.
110 * Cryptographic operations on regions::
111 * Cryptographic operations on files::
112 * Dired integration::
113 * Mail-mode integration::
114 * Encrypting/decrypting gpg files::
117 @node Key management, Cryptographic operations on regions, Commands, Commands
118 @section Key management
119 Probably the first step of using EasyPG Assistant is to browse your
120 keyring. @kbd{M-x epa-list-keys} is corresponding to @samp{gpg
121 --list-keys} from the command line.
123 @deffn Command epa-list-keys name mode
124 Show all keys matched with @var{name} from the public keyring.
128 The output looks as follows.
131 u A5B6B2D4B15813FE Daiki Ueno <ueno@@unixuser.org>
135 A character on the leftmost column indicates the trust level of the
136 key. If it is @samp{u}, the key is marked as ultimately trusted. The
137 second column is the key ID, and the rest is the user ID.
139 You can move over entries by @key{TAB}. If you type @key{RET} or
140 click button1 on an entry, you will see more detailed information
141 about the key you selected.
144 u Daiki Ueno <ueno@@unixuser.org>
145 u A5B6B2D4B15813FE 1024bits DSA
148 Capabilities: sign certify
149 Fingerprint: 8003 7CD0 0F1A 9400 03CA 50AA A5B6 B2D4 B158 13FE
150 u 4447461B2A9BEA2D 2048bits ELGAMAL_E
153 Capabilities: encrypt
154 Fingerprint: 9003 D76B 73B7 4A8A E588 10AF 4447 461B 2A9B EA2D
158 To browse your private keyring, use @kbd{M-x epa-list-secret-keys}.
160 @deffn Command epa-list-secret-keys name
161 Show all keys matched with @var{name} from the private keyring.
165 In @file{*Keys*} buffer, several commands are available. The common
166 use case is to export some keys to a file. To do that, type @kbd{m}
167 to select keys, type @kbd{o}, and then supply the filename.
169 Below are other commands related to key management. Some of them take
170 a file as input/output, and others take the current region.
172 @deffn Command epa-insert-keys keys
173 Insert selected @var{keys} after the point. It will let you select
174 keys before insertion. By default, it will encode keys in the OpenPGP
178 @deffn Command epa-import-keys file
179 Import keys from @var{file} to your keyring.
182 @deffn Command epa-import-keys-region start end
183 Import keys from the current region between @var{start} and @var{end}
187 @deffn Command epa-import-armor-in-region start end
188 Import keys in the OpenPGP armor format in the current region between
189 @var{start} and @var{end}. The difference from
190 @code{epa-import-keys-region} is that
191 @code{epa-import-armor-in-region} searches armors in the region and
192 applies @code{epa-import-keys-region} to each of them.
195 @deffn Command epa-delete-keys allow-secret
196 Delete selected keys. If @var{allow-secret} is non-@code{nil}, it
197 also delete the secret keys.
200 @node Cryptographic operations on regions, Cryptographic operations on files, Key management, Commands
201 @section Cryptographic operations on regions
203 @deffn Command epa-decrypt-region start end
204 Decrypt the current region between @var{start} and @var{end}. It
205 replaces the region with the decrypted text.
208 @deffn Command epa-decrypt-armor-in-region start end
209 Decrypt OpenPGP armors in the current region between @var{start} and
210 @var{end}. The difference from @code{epa-decrypt-region} is that
211 @code{epa-decrypt-armor-in-region} searches armors in the region
212 and applies @code{epa-decrypt-region} to each of them. That is, this
213 command does not alter the original text around armors.
216 @deffn Command epa-verify-region start end
217 Verify the current region between @var{start} and @var{end}. It sends
218 the verification result to the minibuffer or a popup window. It
219 replaces the region with the signed text.
222 @deffn Command epa-verify-cleartext-in-region
223 Verify OpenPGP cleartext blocks in the current region between
224 @var{start} and @var{end}. The difference from
225 @code{epa-verify-region} is that @code{epa-verify-cleartext-in-region}
226 searches OpenPGP cleartext blocks in the region and applies
227 @code{epa-verify-region} to each of them. That is, this command does
228 not alter the original text around OpenPGP cleartext blocks.
231 @deffn Command epa-sign-region start end signers type
232 Sign the current region between @var{start} and @var{end}. By
233 default, it creates a cleartext signature. If a prefix argument is
234 given, it will let you select signing keys, and then a signature
238 @deffn Command epa-encrypt-region start end recipients sign signers
239 Encrypt the current region between @var{start} and @var{end}. It will
240 let you select recipients. If a prefix argument is given, it will
241 also ask you whether or not to sign the text before encryption and if
242 you answered yes, it will let you select the signing keys.
245 @node Cryptographic operations on files, Dired integration, Cryptographic operations on regions, Commands
246 @section Cryptographic operations on files
248 @deffn Command epa-decrypt-file file &optional output
249 Decrypt @var{file}. If you do not specify the name @var{output} to
250 use for the decrypted file, this function prompts for the value to use.
253 @deffn Command epa-verify-file file
257 @deffn Command epa-sign-file file signers type
258 Sign @var{file}. If a prefix argument is given, it will let you
259 select signing keys, and then a signature type.
262 @deffn Command epa-encrypt-file file recipients
263 Encrypt @var{file}. It will let you select recipients.
266 @node Dired integration, Mail-mode integration, Cryptographic operations on files, Commands
267 @section Dired integration
269 EasyPG Assistant extends Dired Mode for GNU Emacs to allow users to
270 easily do cryptographic operations on files. For example,
275 : e (or M-x epa-dired-do-encrypt)
276 (select recipients by 'm' and click [OK])
280 The following keys are assigned.
285 @findex epa-dired-do-decrypt
286 Decrypt marked files.
290 @findex epa-dired-do-verify
295 @findex epa-dired-do-sign
300 @findex epa-dired-do-encrypt
301 Encrypt marked files.
305 @node Mail-mode integration, Encrypting/decrypting gpg files, Dired integration, Commands
306 @section Mail-mode integration
308 EasyPG Assistant provides a minor mode @code{epa-mail-mode} to help
309 user compose inline OpenPGP messages. Inline OpenPGP is a traditional
310 style of sending signed/encrypted emails by embedding raw OpenPGP
311 blobs inside a message body, not using modern MIME format.
313 NOTE: Inline OpenPGP is not recommended and you should consider to use
315 @uref{http://josefsson.org/inline-openpgp-considered-harmful.html,
316 Inline OpenPGP in E-mail is bad@comma{} Mm'kay?}.
319 Once @code{epa-mail-mode} is enabled, the following keys are assigned.
320 You can do it by @kbd{C-u 1 M-x epa-mail-mode} or through the Customize
321 interface. Try @kbd{M-x customize-variable epa-global-mail-mode}.
324 @item C-c C-e C-d and C-c C-e d
325 @kindex @kbd{C-c C-e C-d}
326 @kindex @kbd{C-c C-e d}
327 @findex epa-mail-decrypt
328 Decrypt OpenPGP armors in the current buffer.
330 @item C-c C-e C-v and C-c C-e v
331 @kindex @kbd{C-c C-e C-v}
332 @kindex @kbd{C-c C-e v}
333 @findex epa-mail-verify
334 Verify OpenPGP cleartext signed messages in the current buffer.
336 @item C-c C-e C-s and C-c C-e s
337 @kindex @kbd{C-c C-e C-s}
338 @kindex @kbd{C-c C-e s}
339 @findex epa-mail-sign
340 Compose a signed message from the current buffer.
342 @item C-c C-e C-e and C-c C-e e
343 @kindex @kbd{C-c C-e C-e}
344 @kindex @kbd{C-c C-e e}
345 @findex epa-mail-encrypt
346 @vindex epa-mail-aliases
347 Compose an encrypted message from the current buffer.
348 By default it tries to build the recipient list from @samp{to},
349 @samp{cc}, and @samp{bcc} fields of the mail header. To include your
350 key in the recipient list, use @samp{encrypt-to} option in
351 @file{~/.gnupg/gpg.conf}. This function translates recipient
352 addresses using the @code{epa-mail-aliases} list. You can also
353 use that option to ignore specific recipients for encryption purposes.
357 @node Encrypting/decrypting gpg files, , Mail-mode integration, Commands
358 @section Encrypting/decrypting gpg files
359 By default, every file whose name ends with @file{.gpg} will be
360 treated as encrypted. That is, when you open such a file, the
361 decrypted text is inserted in the buffer rather than encrypted one.
362 Similarly, when you save the buffer to a @file{foo.gpg} file,
363 encrypted data is written.
365 The file name pattern for encrypted files can be controlled by
366 @var{epa-file-name-regexp}.
368 @defvar epa-file-name-regexp
369 Regexp which matches filenames treated as encrypted.
372 You can disable this behavior with @kbd{M-x epa-file-disable}, and
373 then get it back with @kbd{M-x epa-file-enable}.
375 @deffn Command epa-file-disable
376 Disable automatic encryption/decryption of *.gpg files.
379 @deffn Command epa-file-enable
380 Enable automatic encryption/decryption of *.gpg files.
384 By default, @code{epa-file} will try to use symmetric encryption, aka
385 password-based encryption. If you want to use public key encryption
386 instead, do @kbd{M-x epa-file-select-keys}, which pops up the key
389 @deffn Command epa-file-select-keys
390 Select recipient keys to encrypt the currently visiting file with
391 public key encryption.
394 You can also change the default behavior with the variable
395 @var{epa-file-select-keys}.
397 @defvar epa-file-select-keys
398 Control whether or not to pop up the key selection dialog.
401 For frequently visited files, it might be a good idea to tell Emacs
402 which encryption method should be used through @xref{File Variables, ,
403 , emacs, the Emacs Manual}. Use the @code{epa-file-encrypt-to} local
405 @vindex epa-file-encrypt-to
407 For example, if you want an Elisp file to be encrypted with a
408 public key associated with an email address @samp{ueno@@unixuser.org},
409 add the following line to the beginning of the file.
413 ;; -*- epa-file-encrypt-to: ("ueno@@unixuser.org") -*-
417 Instead, if you want the file always (regardless of the value of the
418 @code{epa-file-select-keys} variable) encrypted with symmetric
419 encryption, change the line as follows.
423 ;; -*- epa-file-encrypt-to: nil -*-
427 Other variables which control the automatic encryption/decryption
430 @defvar epa-file-cache-passphrase-for-symmetric-encryption
431 If non-@code{nil}, cache passphrase for symmetric encryption. The
432 default value is @code{nil}.
435 @defvar epa-file-inhibit-auto-save
436 If non-@code{nil}, disable auto-saving when opening an encrypted file.
437 The default value is @code{t}.
440 @node GnuPG version compatibility, Caching Passphrases, Commands, Top
441 @chapter GnuPG version compatibility
443 As of February 2016, there are three active branches of GnuPG: 2.1,
444 2.0, and 1.4. All those branches should work flawlessly with Emacs
445 with basic use-cases. They have, however, some incompatible
446 characteristics, which might be visible when used from Emacs.
450 The key store format used by GnuPG 2.1 is incompatible with 1.4. That
451 means, a key created with GnuPG 2.1 is not visible with 1.4.
454 GnuPG 2.1 uses a fixed address for the Unix domain socket used to
455 communicate with gpg-agent. The @code{GPG_AGENT_INFO} environment
456 variable, which is used by GnuPG 2.0 and 1.4, is ignored. That means,
457 if your system has both GnuPG 2.1 and 1.4, the gpg command from GnuPG
458 1.4 is not able to use gpg-agent provided by 2.1 (at least out of box).
461 GnuPG 2.1 (2.1.5 or later) has a mechanism to direct the Pinentry
462 password prompt to the Emacs minibuffer@footnote{To enable this
463 feature, add @samp{allow-emacs-pinentry} to
464 @file{~/.gnupg/gpg-agent.conf} and let gpg-agent reload the
465 configuration, with: @samp{gpgconf --reload gpg-agent}}, which would
466 be useful when you use Emacs remotely or from a text-only terminal.
467 That feature is not available in other versions, and more
468 specifically, with 2.0 (as of 2.0.29), there is no way to avoid the
472 @node Caching Passphrases, Bug Reports, GnuPG version compatibility, Top
473 @chapter Caching Passphrases
475 Typing passphrases is a troublesome task if you frequently open and
476 close the same file. GnuPG and EasyPG Assistant provide mechanisms to
477 remember your passphrases for a limited time. Using these, you only
478 need to re-enter the passphrase occasionally.
479 However, the configuration is a bit
480 confusing since it depends on your GnuPG installation@xref{GnuPG
481 version compatibility}, encryption method (symmetric or public key),
482 and whether or not you want to use gpg-agent. Here are some
486 @item Do you use GnuPG version 2.1 or 2.0 instead of GnuPG version 1.4?
487 @item Do you use symmetric encryption rather than public key encryption?
488 @item Do you want to use gpg-agent?
491 Here are configurations depending on your answers:
493 @multitable {111} {222} {333} {configuration configuration configuration}
494 @item @b{1} @tab @b{2} @tab @b{3} @tab Configuration
495 @item Yes @tab Yes @tab Yes @tab Set up gpg-agent.
496 @item Yes @tab Yes @tab No @tab You can't, without gpg-agent.
497 @item Yes @tab No @tab Yes @tab Set up gpg-agent.
498 @item Yes @tab No @tab No @tab You can't, without gpg-agent.
499 @item No @tab Yes @tab Yes @tab Set up elisp passphrase cache.
500 @item No @tab Yes @tab No @tab Set up elisp passphrase cache.
501 @item No @tab No @tab Yes @tab Set up gpg-agent.
502 @item No @tab No @tab No @tab You can't, without gpg-agent.
505 To set up gpg-agent, follow the instruction in GnuPG manual.
506 @pxref{Invoking GPG-AGENT, , Invoking GPG-AGENT, gnupg}.
508 To set up elisp passphrase cache, set
509 @code{epa-file-cache-passphrase-for-symmetric-encryption}.
510 @xref{Encrypting/decrypting gpg files}.
512 @node Bug Reports, GNU Free Documentation License, Caching Passphrases, Top
515 Bugs and problems with EasyPG Assistant are actively worked on by the
516 Emacs development team. Feature requests and suggestions are also
517 more than welcome. Use @kbd{M-x report-emacs-bug}, @pxref{Bugs, ,
518 Bugs, emacs, Reporting Bugs}.
520 When submitting a bug report, please try to describe in excruciating
521 detail the steps required to reproduce the problem. Also try to
522 collect necessary information to fix the bug, such as:
525 @item the GnuPG version. Send the output of @samp{gpg --version}.
526 @item the GnuPG configuration. Send the contents of @file{~/.gnupg/gpg.conf}.
529 Before reporting the bug, you should set @code{epg-debug} in the
530 @file{~/.emacs} file and repeat the bug. Then, include the contents
531 of the @file{ *epg-debug*} buffer. Note that the first letter of the
532 buffer name is a whitespace.
534 @node GNU Free Documentation License, Key Index, Bug Reports, Top
535 @appendix GNU Free Documentation License
536 @include doclicense.texi
538 @node Key Index, Function Index, GNU Free Documentation License, Top
539 @unnumbered Key Index
542 @node Function Index, Variable Index, Key Index, Top
543 @unnumbered Function Index
546 @node Variable Index, , Function Index, Top
547 @unnumbered Variable Index