Commit | Line | Data |
---|---|---|
c154c0be MO |
1 | \input texinfo @c -*- mode: texinfo -*- |
2 | @c %**start of header | |
29993416 | 3 | @setfilename ../../info/epa.info |
c154c0be | 4 | @settitle EasyPG Assistant User's Manual |
c6ab4664 | 5 | @documentencoding UTF-8 |
c154c0be MO |
6 | @c %**end of header |
7 | ||
8 | @set VERSION 1.0.0 | |
9 | ||
10 | @copying | |
5dc584b5 | 11 | This file describes EasyPG Assistant @value{VERSION}. |
c154c0be | 12 | |
6bc383b1 | 13 | Copyright @copyright{} 2007--2014 Free Software Foundation, Inc. |
c154c0be MO |
14 | |
15 | @quotation | |
16 | Permission is granted to copy, distribute and/or modify this document | |
6a2c4aec | 17 | under the terms of the GNU Free Documentation License, Version 1.3 or |
c154c0be | 18 | any later version published by the Free Software Foundation; with no |
551a89e1 | 19 | Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,'' |
cd5c05d2 | 20 | and with the Back-Cover Texts as in (a) below. A copy of the license |
0b1af106 | 21 | is included in the section entitled ``GNU Free Documentation License''. |
cd5c05d2 GM |
22 | |
23 | (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and | |
6bf430d1 | 24 | modify this GNU manual.'' |
c154c0be MO |
25 | @end quotation |
26 | @end copying | |
27 | ||
0c973505 | 28 | @dircategory Emacs misc features |
c154c0be | 29 | @direntry |
62e034c2 | 30 | * EasyPG Assistant: (epa). An Emacs user interface to GNU Privacy Guard. |
c154c0be MO |
31 | @end direntry |
32 | ||
c154c0be MO |
33 | @titlepage |
34 | @title EasyPG Assistant | |
35 | ||
36 | @author by Daiki Ueno | |
37 | @page | |
38 | ||
39 | @vskip 0pt plus 1filll | |
40 | @insertcopying | |
41 | @end titlepage | |
c154c0be | 42 | |
5dc584b5 | 43 | @contents |
c154c0be MO |
44 | |
45 | @node Top | |
46 | @top EasyPG Assistant user's manual | |
47 | ||
48 | EasyPG Assistant is an Emacs user interface to GNU Privacy Guard | |
49 | (GnuPG, @pxref{Top, , Top, gnupg, Using the GNU Privacy Guard}). | |
50 | ||
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. | |
54 | ||
5dc584b5 KB |
55 | @ifnottex |
56 | @insertcopying | |
57 | @end ifnottex | |
c154c0be MO |
58 | |
59 | @menu | |
1df7defd PE |
60 | * Overview:: |
61 | * Quick start:: | |
62 | * Commands:: | |
63 | * Caching Passphrases:: | |
64 | * Bug Reports:: | |
0b1af106 | 65 | * GNU Free Documentation License:: The license for this documentation. |
6222d672 GM |
66 | * Key Index:: |
67 | * Function Index:: | |
68 | * Variable Index:: | |
c154c0be MO |
69 | @end menu |
70 | ||
71 | @node Overview | |
72 | @chapter Overview | |
73 | ||
74 | EasyPG Assistant provides the following features. | |
75 | ||
76 | @itemize @bullet | |
34a3c587 | 77 | @item Key management. |
c154c0be MO |
78 | @item Cryptographic operations on regions. |
79 | @item Cryptographic operations on files. | |
80 | @item Dired integration. | |
81 | @item Mail-mode integration. | |
82 | @item Automatic encryption/decryption of *.gpg files. | |
83 | @end itemize | |
84 | ||
85 | @node Quick start | |
86 | @chapter Quick start | |
87 | ||
5a8d03e9 | 88 | EasyPG Assistant commands are prefixed by @samp{epa-}. For example, |
c154c0be MO |
89 | |
90 | @itemize @bullet | |
91 | @item To browse your keyring, type @kbd{M-x epa-list-keys} | |
92 | ||
93 | @item To create a cleartext signature of the region, type @kbd{M-x epa-sign-region} | |
5a8d03e9 MO |
94 | |
95 | @item To encrypt a file, type @kbd{M-x epa-encrypt-file} | |
c154c0be MO |
96 | @end itemize |
97 | ||
5a8d03e9 MO |
98 | EasyPG Assistant provides several cryptographic features which can be |
99 | integrated into other Emacs functionalities. For example, automatic | |
d29fbf47 | 100 | encryption/decryption of @file{*.gpg} files. |
5a8d03e9 | 101 | |
c154c0be MO |
102 | @node Commands |
103 | @chapter Commands | |
104 | ||
105 | This chapter introduces various commands for typical use cases. | |
106 | ||
107 | @menu | |
1df7defd PE |
108 | * Key management:: |
109 | * Cryptographic operations on regions:: | |
110 | * Cryptographic operations on files:: | |
111 | * Dired integration:: | |
112 | * Mail-mode integration:: | |
55f612f0 | 113 | * Encrypting/decrypting gpg files:: |
c154c0be MO |
114 | @end menu |
115 | ||
116 | @node Key management | |
117 | @section Key management | |
118 | Probably the first step of using EasyPG Assistant is to browse your | |
119 | keyring. @kbd{M-x epa-list-keys} is corresponding to @samp{gpg | |
120 | --list-keys} from the command line. | |
121 | ||
122 | @deffn Command epa-list-keys name mode | |
123 | Show all keys matched with @var{name} from the public keyring. | |
124 | @end deffn | |
125 | ||
126 | @noindent | |
127 | The output looks as follows. | |
128 | ||
129 | @example | |
130 | u A5B6B2D4B15813FE Daiki Ueno <ueno@@unixuser.org> | |
131 | @end example | |
132 | ||
133 | @noindent | |
134 | A character on the leftmost column indicates the trust level of the | |
135 | key. If it is @samp{u}, the key is marked as ultimately trusted. The | |
136 | second column is the key ID, and the rest is the user ID. | |
137 | ||
138 | You can move over entries by @key{TAB}. If you type @key{RET} or | |
139 | click button1 on an entry, you will see more detailed information | |
140 | about the key you selected. | |
141 | ||
142 | @example | |
143 | u Daiki Ueno <ueno@@unixuser.org> | |
144 | u A5B6B2D4B15813FE 1024bits DSA | |
b1fbbb32 GM |
145 | Created: 2001-10-09 |
146 | Expires: 2007-09-04 | |
147 | Capabilities: sign certify | |
148 | Fingerprint: 8003 7CD0 0F1A 9400 03CA 50AA A5B6 B2D4 B158 13FE | |
c154c0be | 149 | u 4447461B2A9BEA2D 2048bits ELGAMAL_E |
b1fbbb32 GM |
150 | Created: 2001-10-09 |
151 | Expires: 2007-09-04 | |
152 | Capabilities: encrypt | |
153 | Fingerprint: 9003 D76B 73B7 4A8A E588 10AF 4447 461B 2A9B EA2D | |
c154c0be MO |
154 | @end example |
155 | ||
156 | @noindent | |
157 | To browse your private keyring, use @kbd{M-x epa-list-secret-keys}. | |
158 | ||
159 | @deffn Command epa-list-secret-keys name | |
160 | Show all keys matched with @var{name} from the private keyring. | |
161 | @end deffn | |
162 | ||
163 | @noindent | |
d29fbf47 | 164 | In @file{*Keys*} buffer, several commands are available. The common |
c154c0be MO |
165 | use case is to export some keys to a file. To do that, type @kbd{m} |
166 | to select keys, type @kbd{o}, and then supply the filename. | |
167 | ||
168 | Below are other commands related to key management. Some of them take | |
169 | a file as input/output, and others take the current region. | |
170 | ||
171 | @deffn Command epa-insert-keys keys | |
172 | Insert selected @var{keys} after the point. It will let you select | |
173 | keys before insertion. By default, it will encode keys in the OpenPGP | |
174 | armor format. | |
175 | @end deffn | |
176 | ||
177 | @deffn Command epa-import-keys file | |
178 | Import keys from @var{file} to your keyring. | |
179 | @end deffn | |
180 | ||
181 | @deffn Command epa-import-keys-region start end | |
182 | Import keys from the current region between @var{start} and @var{end} | |
183 | to your keyring. | |
184 | @end deffn | |
185 | ||
186 | @deffn Command epa-import-armor-in-region start end | |
187 | Import keys in the OpenPGP armor format in the current region between | |
188 | @var{start} and @var{end}. The difference from | |
189 | @code{epa-import-keys-region} is that | |
190 | @code{epa-import-armor-in-region} searches armors in the region and | |
191 | applies @code{epa-import-keys-region} to each of them. | |
192 | @end deffn | |
193 | ||
194 | @deffn Command epa-delete-keys allow-secret | |
195 | Delete selected keys. If @var{allow-secret} is non-@code{nil}, it | |
196 | also delete the secret keys. | |
197 | @end deffn | |
198 | ||
199 | @node Cryptographic operations on regions | |
200 | @section Cryptographic operations on regions | |
201 | ||
202 | @deffn Command epa-decrypt-region start end | |
203 | Decrypt the current region between @var{start} and @var{end}. It | |
204 | replaces the region with the decrypted text. | |
205 | @end deffn | |
206 | ||
207 | @deffn Command epa-decrypt-armor-in-region start end | |
208 | Decrypt OpenPGP armors in the current region between @var{start} and | |
209 | @var{end}. The difference from @code{epa-decrypt-region} is that | |
210 | @code{epa-decrypt-armor-in-region} searches armors in the region | |
211 | and applies @code{epa-decrypt-region} to each of them. That is, this | |
212 | command does not alter the original text around armors. | |
213 | @end deffn | |
214 | ||
215 | @deffn Command epa-verify-region start end | |
216 | Verify the current region between @var{start} and @var{end}. It sends | |
217 | the verification result to the minibuffer or a popup window. It | |
218 | replaces the region with the signed text. | |
219 | @end deffn | |
220 | ||
221 | @deffn Command epa-verify-cleartext-in-region | |
222 | Verify OpenPGP cleartext blocks in the current region between | |
223 | @var{start} and @var{end}. The difference from | |
224 | @code{epa-verify-region} is that @code{epa-verify-cleartext-in-region} | |
225 | searches OpenPGP cleartext blocks in the region and applies | |
226 | @code{epa-verify-region} to each of them. That is, this command does | |
227 | not alter the original text around OpenPGP cleartext blocks. | |
228 | @end deffn | |
229 | ||
230 | @deffn Command epa-sign-region start end signers type | |
231 | Sign the current region between @var{start} and @var{end}. By | |
232 | default, it creates a cleartext signature. If a prefix argument is | |
233 | given, it will let you select signing keys, and then a signature | |
234 | type. | |
235 | @end deffn | |
236 | ||
237 | @deffn Command epa-encrypt-region start end recipients sign signers | |
238 | Encrypt the current region between @var{start} and @var{end}. It will | |
239 | let you select recipients. If a prefix argument is given, it will | |
240 | also ask you whether or not to sign the text before encryption and if | |
241 | you answered yes, it will let you select the signing keys. | |
242 | @end deffn | |
243 | ||
244 | @node Cryptographic operations on files | |
245 | @section Cryptographic operations on files | |
246 | ||
2c71cd64 KY |
247 | @deffn Command epa-decrypt-file file &optional output |
248 | Decrypt @var{file}. If you do not specify the name @var{output} to | |
249 | use for the decrypted file, this function prompts for the value to use. | |
c154c0be MO |
250 | @end deffn |
251 | ||
252 | @deffn Command epa-verify-file file | |
253 | Verify @var{file}. | |
254 | @end deffn | |
255 | ||
256 | @deffn Command epa-sign-file file signers type | |
257 | Sign @var{file}. If a prefix argument is given, it will let you | |
258 | select signing keys, and then a signature type. | |
259 | @end deffn | |
260 | ||
261 | @deffn Command epa-encrypt-file file recipients | |
262 | Encrypt @var{file}. It will let you select recipients. | |
263 | @end deffn | |
264 | ||
265 | @node Dired integration | |
266 | @section Dired integration | |
267 | ||
268 | EasyPG Assistant extends Dired Mode for GNU Emacs to allow users to | |
269 | easily do cryptographic operations on files. For example, | |
270 | ||
271 | @example | |
272 | M-x dired | |
273 | (mark some files) | |
274 | : e (or M-x epa-dired-do-encrypt) | |
275 | (select recipients by 'm' and click [OK]) | |
276 | @end example | |
277 | ||
278 | @noindent | |
279 | The following keys are assigned. | |
280 | ||
281 | @table @kbd | |
282 | @item : d | |
283 | @kindex @kbd{: d} | |
284 | @findex epa-dired-do-decrypt | |
285 | Decrypt marked files. | |
286 | ||
287 | @item : v | |
288 | @kindex @kbd{: v} | |
289 | @findex epa-dired-do-verify | |
290 | Verify marked files. | |
291 | ||
292 | @item : s | |
293 | @kindex @kbd{: s} | |
294 | @findex epa-dired-do-sign | |
295 | Sign marked files. | |
296 | ||
297 | @item : e | |
298 | @kindex @kbd{: e} | |
299 | @findex epa-dired-do-encrypt | |
300 | Encrypt marked files. | |
301 | ||
302 | @end table | |
303 | ||
304 | @node Mail-mode integration | |
305 | @section Mail-mode integration | |
306 | ||
3b7ab45f | 307 | EasyPG Assistant provides a minor mode @code{epa-mail-mode} to help |
c05c2b9b DU |
308 | user compose inline OpenPGP messages. Inline OpenPGP is a traditional |
309 | style of sending signed/encrypted emails by embedding raw OpenPGP | |
310 | blobs inside a message body, not using modern MIME format. | |
3b7ab45f | 311 | |
c05c2b9b | 312 | NOTE: Inline OpenPGP is not recommended and you should consider to use |
1df7defd | 313 | PGP/MIME@. See |
c154c0be | 314 | @uref{http://josefsson.org/inline-openpgp-considered-harmful.html, |
c05c2b9b | 315 | Inline OpenPGP in E-mail is bad@comma{} Mm'kay?}. |
c154c0be MO |
316 | |
317 | @noindent | |
0f215bca DU |
318 | Once @code{epa-mail-mode} is enabled, the following keys are assigned. |
319 | You can do it by @kbd{C-u 1 M-x epa-mail-mode} or through the Customize | |
320 | interface. Try @kbd{M-x customize-variable epa-global-mail-mode}. | |
c154c0be MO |
321 | |
322 | @table @kbd | |
d85d3b3a DU |
323 | @item C-c C-e C-d and C-c C-e d |
324 | @kindex @kbd{C-c C-e C-d} | |
c154c0be MO |
325 | @kindex @kbd{C-c C-e d} |
326 | @findex epa-mail-decrypt | |
327 | Decrypt OpenPGP armors in the current buffer. | |
328 | ||
d85d3b3a DU |
329 | @item C-c C-e C-v and C-c C-e v |
330 | @kindex @kbd{C-c C-e C-v} | |
c154c0be MO |
331 | @kindex @kbd{C-c C-e v} |
332 | @findex epa-mail-verify | |
333 | Verify OpenPGP cleartext signed messages in the current buffer. | |
334 | ||
d85d3b3a DU |
335 | @item C-c C-e C-s and C-c C-e s |
336 | @kindex @kbd{C-c C-e C-s} | |
c154c0be MO |
337 | @kindex @kbd{C-c C-e s} |
338 | @findex epa-mail-sign | |
339 | Compose a signed message from the current buffer. | |
340 | ||
d85d3b3a DU |
341 | @item C-c C-e C-e and C-c C-e e |
342 | @kindex @kbd{C-c C-e C-e} | |
c154c0be MO |
343 | @kindex @kbd{C-c C-e e} |
344 | @findex epa-mail-encrypt | |
79b6e0a9 | 345 | @vindex epa-mail-aliases |
c154c0be | 346 | Compose an encrypted message from the current buffer. |
7a603b73 DU |
347 | By default it tries to build the recipient list from @samp{to}, |
348 | @samp{cc}, and @samp{bcc} fields of the mail header. To include your | |
349 | key in the recipient list, use @samp{encrypt-to} option in | |
79b6e0a9 GM |
350 | @file{~/.gnupg/gpg.conf}. This function translates recipient |
351 | addresses using the @code{epa-mail-aliases} list. You can also | |
352 | use that option to ignore specific recipients for encryption purposes. | |
c154c0be MO |
353 | |
354 | @end table | |
355 | ||
55f612f0 GM |
356 | @node Encrypting/decrypting gpg files |
357 | @section Encrypting/decrypting gpg files | |
d29fbf47 | 358 | By default, every file whose name ends with @file{.gpg} will be |
8b358e90 DU |
359 | treated as encrypted. That is, when you open such a file, the |
360 | decrypted text is inserted in the buffer rather than encrypted one. | |
d29fbf47 | 361 | Similarly, when you save the buffer to a @file{foo.gpg} file, |
8b358e90 | 362 | encrypted data is written. |
c154c0be | 363 | |
8b358e90 DU |
364 | The file name pattern for encrypted files can be controlled by |
365 | @var{epa-file-name-regexp}. | |
366 | ||
367 | @defvar epa-file-name-regexp | |
368 | Regexp which matches filenames treated as encrypted. | |
369 | @end defvar | |
370 | ||
371 | You can disable this behavior with @kbd{M-x epa-file-disable}, and | |
372 | then get it back with @kbd{M-x epa-file-enable}. | |
c154c0be MO |
373 | |
374 | @deffn Command epa-file-disable | |
375 | Disable automatic encryption/decryption of *.gpg files. | |
376 | @end deffn | |
377 | ||
378 | @deffn Command epa-file-enable | |
379 | Enable automatic encryption/decryption of *.gpg files. | |
380 | @end deffn | |
381 | ||
382 | @noindent | |
8b358e90 DU |
383 | By default, @code{epa-file} will try to use symmetric encryption, aka |
384 | password-based encryption. If you want to use public key encryption | |
385 | instead, do @kbd{M-x epa-file-select-keys}, which will pops up the key | |
386 | selection dialog. | |
387 | ||
388 | @deffn Command epa-file-select-keys | |
389 | Select recipient keys to encrypt the currently visiting file with | |
390 | public key encryption. | |
391 | @end deffn | |
392 | ||
393 | You can also change the default behavior with the variable | |
394 | @var{epa-file-select-keys}. | |
395 | ||
396 | @defvar epa-file-select-keys | |
397 | Control whether or not to pop up the key selection dialog. | |
398 | @end defvar | |
399 | ||
400 | For frequently visited files, it might be a good idea to tell Emacs | |
401 | which encryption method should be used through @xref{File Variables, , | |
402 | , emacs, the Emacs Manual}. Use the @code{epa-file-encrypt-to} local | |
403 | variable for this. | |
c154c0be MO |
404 | @vindex epa-file-encrypt-to |
405 | ||
f358e6e5 | 406 | For example, if you want an Elisp file to be encrypted with a |
8b358e90 DU |
407 | public key associated with an email address @samp{ueno@@unixuser.org}, |
408 | add the following line to the beginning of the file. | |
409 | ||
c154c0be MO |
410 | @cartouche |
411 | @lisp | |
412 | ;; -*- epa-file-encrypt-to: ("ueno@@unixuser.org") -*- | |
413 | @end lisp | |
414 | @end cartouche | |
415 | ||
8b358e90 DU |
416 | Instead, if you want the file always (regardless of the value of the |
417 | @code{epa-file-select-keys} variable) encrypted with symmetric | |
418 | encryption, change the line as follows. | |
2c6c404a | 419 | |
8b358e90 DU |
420 | @cartouche |
421 | @lisp | |
422 | ;; -*- epa-file-encrypt-to: nil -*- | |
423 | @end lisp | |
424 | @end cartouche | |
2c6c404a | 425 | |
c154c0be MO |
426 | Other variables which control the automatic encryption/decryption |
427 | behavior are below. | |
428 | ||
429 | @defvar epa-file-cache-passphrase-for-symmetric-encryption | |
430 | If non-@code{nil}, cache passphrase for symmetric encryption. The | |
431 | default value is @code{nil}. | |
432 | @end defvar | |
433 | ||
434 | @defvar epa-file-inhibit-auto-save | |
435 | If non-@code{nil}, disable auto-saving when opening an encrypted file. | |
436 | The default value is @code{t}. | |
437 | @end defvar | |
438 | ||
65f54520 DU |
439 | @node Caching Passphrases |
440 | @chapter Caching Passphrases | |
441 | ||
442 | Typing passphrases is an irritating task if you frequently open and | |
443 | close the same file. GnuPG and EasyPG Assistant provide mechanisms to | |
444 | remember your passphrases. However, the configuration is a bit | |
445 | confusing since it depends on your GnuPG installation (GnuPG version 1 or | |
446 | GnuPG version 2), encryption method (symmetric or public key), and whether or | |
447 | not you want to use gpg-agent. Here are some questions: | |
448 | ||
449 | @enumerate | |
450 | @item Do you use GnuPG version 2 instead of GnuPG version 1? | |
451 | @item Do you use symmetric encryption rather than public key encryption? | |
452 | @item Do you want to use gpg-agent? | |
453 | @end enumerate | |
454 | ||
455 | Here are configurations depending on your answers: | |
456 | ||
457 | @multitable {111} {222} {333} {configuration configuration configuration} | |
458 | @item @b{1} @tab @b{2} @tab @b{3} @tab Configuration | |
98e2b864 | 459 | @item Yes @tab Yes @tab Yes @tab Set up gpg-agent. |
65f54520 | 460 | @item Yes @tab Yes @tab No @tab You can't, without gpg-agent. |
98e2b864 | 461 | @item Yes @tab No @tab Yes @tab Set up gpg-agent. |
65f54520 DU |
462 | @item Yes @tab No @tab No @tab You can't, without gpg-agent. |
463 | @item No @tab Yes @tab Yes @tab Set up elisp passphrase cache. | |
464 | @item No @tab Yes @tab No @tab Set up elisp passphrase cache. | |
98e2b864 | 465 | @item No @tab No @tab Yes @tab Set up gpg-agent. |
65f54520 DU |
466 | @item No @tab No @tab No @tab You can't, without gpg-agent. |
467 | @end multitable | |
468 | ||
98e2b864 | 469 | To set up gpg-agent, follow the instruction in GnuPG manual. |
65f54520 DU |
470 | @pxref{Invoking GPG-AGENT, , Invoking GPG-AGENT, gnupg}. |
471 | ||
472 | To set up elisp passphrase cache, set | |
473 | @code{epa-file-cache-passphrase-for-symmetric-encryption}. | |
55f612f0 | 474 | @xref{Encrypting/decrypting gpg files}. |
65f54520 | 475 | |
b9476c04 DU |
476 | @node Bug Reports |
477 | @chapter Bug Reports | |
478 | ||
479 | Bugs and problems with EasyPG Assistant are actively worked on by the | |
480 | Emacs development team. Feature requests and suggestions are also | |
481 | more than welcome. Use @kbd{M-x report-emacs-bug}, @pxref{Bugs, , | |
482 | Bugs, emacs, Reporting Bugs}. | |
483 | ||
484 | When submitting a bug report, please try to describe in excruciating | |
485 | detail the steps required to reproduce the problem. Also try to | |
486 | collect necessary information to fix the bug, such as: | |
487 | ||
488 | @itemize @bullet | |
489 | @item the GnuPG version. Send the output of @samp{gpg --version}. | |
490 | @item the GnuPG configuration. Send the contents of @file{~/.gnupg/gpg.conf}. | |
491 | @end itemize | |
492 | ||
493 | Before reporting the bug, you should set @code{epg-debug} in the | |
494 | @file{~/.emacs} file and repeat the bug. Then, include the contents | |
d29fbf47 | 495 | of the @file{ *epg-debug*} buffer. Note that the first letter of the |
b9476c04 DU |
496 | buffer name is a whitespace. |
497 | ||
0b1af106 GM |
498 | @node GNU Free Documentation License |
499 | @appendix GNU Free Documentation License | |
500 | @include doclicense.texi | |
501 | ||
6222d672 GM |
502 | @node Key Index |
503 | @unnumbered Key Index | |
504 | @printindex ky | |
505 | ||
506 | @node Function Index | |
507 | @unnumbered Function Index | |
508 | @printindex fn | |
509 | ||
510 | @node Variable Index | |
511 | @unnumbered Variable Index | |
512 | @printindex vr | |
513 | ||
c154c0be MO |
514 | @bye |
515 | ||
516 | @c End: |