1 \input texinfo @c -*- mode: texinfo -*-
3 @setfilename ../../info/epa
4 @settitle EasyPG Assistant User's Manual
5 @documentencoding UTF-8
12 This file describes EasyPG Assistant @value{VERSION}.
14 Copyright @copyright{} 2007--2013 Free Software Foundation, Inc.
17 Permission is granted to copy, distribute and/or modify this document
18 under the terms of the GNU Free Documentation License, Version 1.3 or
19 any later version published by the Free Software Foundation; with no
20 Invariant Sections, with the Front-Cover texts being ``A GNU Manual,''
21 and with the Back-Cover Texts as in (a) below. A copy of the license
22 is included in the section entitled ``GNU Free Documentation License''.
24 (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
25 modify this GNU manual.''
29 @dircategory Emacs misc features
31 * EasyPG Assistant: (epa). An Emacs user interface to GNU Privacy Guard.
35 @title EasyPG Assistant
40 @vskip 0pt plus 1filll
47 @top EasyPG Assistant user's manual
49 EasyPG Assistant is an Emacs user interface to GNU Privacy Guard
50 (GnuPG, @pxref{Top, , Top, gnupg, Using the GNU Privacy Guard}).
52 EasyPG Assistant is a part of the package called EasyPG, an all-in-one
53 GnuPG interface for Emacs. EasyPG also contains the library interface
54 called EasyPG Library.
64 * Caching Passphrases::
66 * GNU Free Documentation License:: The license for this documentation.
72 EasyPG Assistant provides the following features.
76 @item Cryptographic operations on regions.
77 @item Cryptographic operations on files.
78 @item Dired integration.
79 @item Mail-mode integration.
80 @item Automatic encryption/decryption of *.gpg files.
86 EasyPG Assistant commands are prefixed by @samp{epa-}. For example,
89 @item To browse your keyring, type @kbd{M-x epa-list-keys}
91 @item To create a cleartext signature of the region, type @kbd{M-x epa-sign-region}
93 @item To encrypt a file, type @kbd{M-x epa-encrypt-file}
96 EasyPG Assistant provides several cryptographic features which can be
97 integrated into other Emacs functionalities. For example, automatic
98 encryption/decryption of @samp{*.gpg} files.
103 This chapter introduces various commands for typical use cases.
107 * Cryptographic operations on regions::
108 * Cryptographic operations on files::
109 * Dired integration::
110 * Mail-mode integration::
111 * Encrypting/decrypting gpg files::
115 @section Key management
116 Probably the first step of using EasyPG Assistant is to browse your
117 keyring. @kbd{M-x epa-list-keys} is corresponding to @samp{gpg
118 --list-keys} from the command line.
120 @deffn Command epa-list-keys name mode
121 Show all keys matched with @var{name} from the public keyring.
125 The output looks as follows.
128 u A5B6B2D4B15813FE Daiki Ueno <ueno@@unixuser.org>
132 A character on the leftmost column indicates the trust level of the
133 key. If it is @samp{u}, the key is marked as ultimately trusted. The
134 second column is the key ID, and the rest is the user ID.
136 You can move over entries by @key{TAB}. If you type @key{RET} or
137 click button1 on an entry, you will see more detailed information
138 about the key you selected.
141 u Daiki Ueno <ueno@@unixuser.org>
142 u A5B6B2D4B15813FE 1024bits DSA
145 Capabilities: sign certify
146 Fingerprint: 8003 7CD0 0F1A 9400 03CA 50AA A5B6 B2D4 B158 13FE
147 u 4447461B2A9BEA2D 2048bits ELGAMAL_E
150 Capabilities: encrypt
151 Fingerprint: 9003 D76B 73B7 4A8A E588 10AF 4447 461B 2A9B EA2D
155 To browse your private keyring, use @kbd{M-x epa-list-secret-keys}.
157 @deffn Command epa-list-secret-keys name
158 Show all keys matched with @var{name} from the private keyring.
162 In @samp{*Keys*} buffer, several commands are available. The common
163 use case is to export some keys to a file. To do that, type @kbd{m}
164 to select keys, type @kbd{o}, and then supply the filename.
166 Below are other commands related to key management. Some of them take
167 a file as input/output, and others take the current region.
169 @deffn Command epa-insert-keys keys
170 Insert selected @var{keys} after the point. It will let you select
171 keys before insertion. By default, it will encode keys in the OpenPGP
175 @deffn Command epa-import-keys file
176 Import keys from @var{file} to your keyring.
179 @deffn Command epa-import-keys-region start end
180 Import keys from the current region between @var{start} and @var{end}
184 @deffn Command epa-import-armor-in-region start end
185 Import keys in the OpenPGP armor format in the current region between
186 @var{start} and @var{end}. The difference from
187 @code{epa-import-keys-region} is that
188 @code{epa-import-armor-in-region} searches armors in the region and
189 applies @code{epa-import-keys-region} to each of them.
192 @deffn Command epa-delete-keys allow-secret
193 Delete selected keys. If @var{allow-secret} is non-@code{nil}, it
194 also delete the secret keys.
197 @node Cryptographic operations on regions
198 @section Cryptographic operations on regions
200 @deffn Command epa-decrypt-region start end
201 Decrypt the current region between @var{start} and @var{end}. It
202 replaces the region with the decrypted text.
205 @deffn Command epa-decrypt-armor-in-region start end
206 Decrypt OpenPGP armors in the current region between @var{start} and
207 @var{end}. The difference from @code{epa-decrypt-region} is that
208 @code{epa-decrypt-armor-in-region} searches armors in the region
209 and applies @code{epa-decrypt-region} to each of them. That is, this
210 command does not alter the original text around armors.
213 @deffn Command epa-verify-region start end
214 Verify the current region between @var{start} and @var{end}. It sends
215 the verification result to the minibuffer or a popup window. It
216 replaces the region with the signed text.
219 @deffn Command epa-verify-cleartext-in-region
220 Verify OpenPGP cleartext blocks in the current region between
221 @var{start} and @var{end}. The difference from
222 @code{epa-verify-region} is that @code{epa-verify-cleartext-in-region}
223 searches OpenPGP cleartext blocks in the region and applies
224 @code{epa-verify-region} to each of them. That is, this command does
225 not alter the original text around OpenPGP cleartext blocks.
228 @deffn Command epa-sign-region start end signers type
229 Sign the current region between @var{start} and @var{end}. By
230 default, it creates a cleartext signature. If a prefix argument is
231 given, it will let you select signing keys, and then a signature
235 @deffn Command epa-encrypt-region start end recipients sign signers
236 Encrypt the current region between @var{start} and @var{end}. It will
237 let you select recipients. If a prefix argument is given, it will
238 also ask you whether or not to sign the text before encryption and if
239 you answered yes, it will let you select the signing keys.
242 @node Cryptographic operations on files
243 @section Cryptographic operations on files
245 @deffn Command epa-decrypt-file file &optional output
246 Decrypt @var{file}. If you do not specify the name @var{output} to
247 use for the decrypted file, this function prompts for the value to use.
250 @deffn Command epa-verify-file file
254 @deffn Command epa-sign-file file signers type
255 Sign @var{file}. If a prefix argument is given, it will let you
256 select signing keys, and then a signature type.
259 @deffn Command epa-encrypt-file file recipients
260 Encrypt @var{file}. It will let you select recipients.
263 @node Dired integration
264 @section Dired integration
266 EasyPG Assistant extends Dired Mode for GNU Emacs to allow users to
267 easily do cryptographic operations on files. For example,
272 : e (or M-x epa-dired-do-encrypt)
273 (select recipients by 'm' and click [OK])
277 The following keys are assigned.
282 @findex epa-dired-do-decrypt
283 Decrypt marked files.
287 @findex epa-dired-do-verify
292 @findex epa-dired-do-sign
297 @findex epa-dired-do-encrypt
298 Encrypt marked files.
302 @node Mail-mode integration
303 @section Mail-mode integration
305 EasyPG Assistant provides a minor mode @code{epa-mail-mode} to help
306 user compose inline OpenPGP messages. Inline OpenPGP is a traditional
307 style of sending signed/encrypted emails by embedding raw OpenPGP
308 blobs inside a message body, not using modern MIME format.
310 NOTE: Inline OpenPGP is not recommended and you should consider to use
312 @uref{http://josefsson.org/inline-openpgp-considered-harmful.html,
313 Inline OpenPGP in E-mail is bad@comma{} Mm'kay?}.
316 Once @code{epa-mail-mode} is enabled, the following keys are assigned.
317 You can do it by @kbd{C-u 1 M-x epa-mail-mode} or through the Customize
318 interface. Try @kbd{M-x customize-variable epa-global-mail-mode}.
321 @item C-c C-e C-d and C-c C-e d
322 @kindex @kbd{C-c C-e C-d}
323 @kindex @kbd{C-c C-e d}
324 @findex epa-mail-decrypt
325 Decrypt OpenPGP armors in the current buffer.
327 @item C-c C-e C-v and C-c C-e v
328 @kindex @kbd{C-c C-e C-v}
329 @kindex @kbd{C-c C-e v}
330 @findex epa-mail-verify
331 Verify OpenPGP cleartext signed messages in the current buffer.
333 @item C-c C-e C-s and C-c C-e s
334 @kindex @kbd{C-c C-e C-s}
335 @kindex @kbd{C-c C-e s}
336 @findex epa-mail-sign
337 Compose a signed message from the current buffer.
339 @item C-c C-e C-e and C-c C-e e
340 @kindex @kbd{C-c C-e C-e}
341 @kindex @kbd{C-c C-e e}
342 @findex epa-mail-encrypt
343 Compose an encrypted message from the current buffer.
344 By default it tries to build the recipient list from @samp{to},
345 @samp{cc}, and @samp{bcc} fields of the mail header. To include your
346 key in the recipient list, use @samp{encrypt-to} option in
347 @file{~/.gnupg/gpg.conf}.
351 @node Encrypting/decrypting gpg files
352 @section Encrypting/decrypting gpg files
353 By default, every file whose name ends with @samp{.gpg} will be
354 treated as encrypted. That is, when you open such a file, the
355 decrypted text is inserted in the buffer rather than encrypted one.
356 Similarly, when you save the buffer to a @samp{foo.gpg} file,
357 encrypted data is written.
359 The file name pattern for encrypted files can be controlled by
360 @var{epa-file-name-regexp}.
362 @defvar epa-file-name-regexp
363 Regexp which matches filenames treated as encrypted.
366 You can disable this behavior with @kbd{M-x epa-file-disable}, and
367 then get it back with @kbd{M-x epa-file-enable}.
369 @deffn Command epa-file-disable
370 Disable automatic encryption/decryption of *.gpg files.
373 @deffn Command epa-file-enable
374 Enable automatic encryption/decryption of *.gpg files.
378 By default, @code{epa-file} will try to use symmetric encryption, aka
379 password-based encryption. If you want to use public key encryption
380 instead, do @kbd{M-x epa-file-select-keys}, which will pops up the key
383 @deffn Command epa-file-select-keys
384 Select recipient keys to encrypt the currently visiting file with
385 public key encryption.
388 You can also change the default behavior with the variable
389 @var{epa-file-select-keys}.
391 @defvar epa-file-select-keys
392 Control whether or not to pop up the key selection dialog.
395 For frequently visited files, it might be a good idea to tell Emacs
396 which encryption method should be used through @xref{File Variables, ,
397 , emacs, the Emacs Manual}. Use the @code{epa-file-encrypt-to} local
399 @vindex epa-file-encrypt-to
401 For example, if you want an Elisp file to be encrypted with a
402 public key associated with an email address @samp{ueno@@unixuser.org},
403 add the following line to the beginning of the file.
407 ;; -*- epa-file-encrypt-to: ("ueno@@unixuser.org") -*-
411 Instead, if you want the file always (regardless of the value of the
412 @code{epa-file-select-keys} variable) encrypted with symmetric
413 encryption, change the line as follows.
417 ;; -*- epa-file-encrypt-to: nil -*-
421 Other variables which control the automatic encryption/decryption
424 @defvar epa-file-cache-passphrase-for-symmetric-encryption
425 If non-@code{nil}, cache passphrase for symmetric encryption. The
426 default value is @code{nil}.
429 @defvar epa-file-inhibit-auto-save
430 If non-@code{nil}, disable auto-saving when opening an encrypted file.
431 The default value is @code{t}.
434 @node Caching Passphrases
435 @chapter Caching Passphrases
437 Typing passphrases is an irritating task if you frequently open and
438 close the same file. GnuPG and EasyPG Assistant provide mechanisms to
439 remember your passphrases. However, the configuration is a bit
440 confusing since it depends on your GnuPG installation (GnuPG version 1 or
441 GnuPG version 2), encryption method (symmetric or public key), and whether or
442 not you want to use gpg-agent. Here are some questions:
445 @item Do you use GnuPG version 2 instead of GnuPG version 1?
446 @item Do you use symmetric encryption rather than public key encryption?
447 @item Do you want to use gpg-agent?
450 Here are configurations depending on your answers:
452 @multitable {111} {222} {333} {configuration configuration configuration}
453 @item @b{1} @tab @b{2} @tab @b{3} @tab Configuration
454 @item Yes @tab Yes @tab Yes @tab Set up gpg-agent.
455 @item Yes @tab Yes @tab No @tab You can't, without gpg-agent.
456 @item Yes @tab No @tab Yes @tab Set up gpg-agent.
457 @item Yes @tab No @tab No @tab You can't, without gpg-agent.
458 @item No @tab Yes @tab Yes @tab Set up elisp passphrase cache.
459 @item No @tab Yes @tab No @tab Set up elisp passphrase cache.
460 @item No @tab No @tab Yes @tab Set up gpg-agent.
461 @item No @tab No @tab No @tab You can't, without gpg-agent.
464 To set up gpg-agent, follow the instruction in GnuPG manual.
465 @pxref{Invoking GPG-AGENT, , Invoking GPG-AGENT, gnupg}.
467 To set up elisp passphrase cache, set
468 @code{epa-file-cache-passphrase-for-symmetric-encryption}.
469 @xref{Encrypting/decrypting gpg files}.
474 Bugs and problems with EasyPG Assistant are actively worked on by the
475 Emacs development team. Feature requests and suggestions are also
476 more than welcome. Use @kbd{M-x report-emacs-bug}, @pxref{Bugs, ,
477 Bugs, emacs, Reporting Bugs}.
479 When submitting a bug report, please try to describe in excruciating
480 detail the steps required to reproduce the problem. Also try to
481 collect necessary information to fix the bug, such as:
484 @item the GnuPG version. Send the output of @samp{gpg --version}.
485 @item the GnuPG configuration. Send the contents of @file{~/.gnupg/gpg.conf}.
488 Before reporting the bug, you should set @code{epg-debug} in the
489 @file{~/.emacs} file and repeat the bug. Then, include the contents
490 of the @samp{ *epg-debug*} buffer. Note that the first letter of the
491 buffer name is a whitespace.
493 @node GNU Free Documentation License
494 @appendix GNU Free Documentation License
495 @include doclicense.texi