epa.texi: Add indices
[gnus] / texi / epa.texi
1 \input texinfo                  @c -*- mode: texinfo -*-
2 @c %**start of header
3 @setfilename epa
4 @settitle EasyPG Assistant User's Manual
5 @documentencoding UTF-8
6 @c %**end of header
7
8 @set VERSION 1.0.0
9
10 @copying
11 This file describes EasyPG Assistant @value{VERSION}.
12
13 Copyright @copyright{} 2007--2014 Free Software Foundation, Inc.
14
15 @quotation
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''.
22
23 (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
24 modify this GNU manual.''
25 @end quotation
26 @end copying
27
28 @dircategory Emacs misc features
29 @direntry
30 * EasyPG Assistant: (epa).      An Emacs user interface to GNU Privacy Guard.
31 @end direntry
32
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
42
43 @contents
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
55 @ifnottex
56 @insertcopying
57 @end ifnottex
58
59 @menu
60 * Overview::
61 * Quick start::
62 * Commands::
63 * Caching Passphrases::
64 * Bug Reports::
65 * GNU Free Documentation License::  The license for this documentation.
66 * Key Index::
67 * Function Index::
68 * Variable Index::
69 @end menu
70
71 @node  Overview
72 @chapter Overview
73
74 EasyPG Assistant provides the following features.
75
76 @itemize @bullet
77 @item Key management.
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
88 EasyPG Assistant commands are prefixed by @samp{epa-}.  For example,
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}
94
95 @item To encrypt a file, type @kbd{M-x epa-encrypt-file}
96 @end itemize
97
98 EasyPG Assistant provides several cryptographic features which can be
99 integrated into other Emacs functionalities.  For example, automatic
100 encryption/decryption of @samp{*.gpg} files.
101
102 @node Commands
103 @chapter Commands
104
105 This chapter introduces various commands for typical use cases.
106
107 @menu
108 * Key management::
109 * Cryptographic operations on regions::
110 * Cryptographic operations on files::
111 * Dired integration::
112 * Mail-mode integration::
113 * Encrypting/decrypting gpg files::
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
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
149  u 4447461B2A9BEA2D 2048bits ELGAMAL_E
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
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
164 In @samp{*Keys*} buffer, several commands are available.  The common
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
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.
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
307 EasyPG Assistant provides a minor mode @code{epa-mail-mode} to help
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.
311
312 NOTE: Inline OpenPGP is not recommended and you should consider to use
313 PGP/MIME@.  See
314 @uref{http://josefsson.org/inline-openpgp-considered-harmful.html,
315 Inline OpenPGP in E-mail is bad@comma{} Mm'kay?}.
316
317 @noindent
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}.
321
322 @table @kbd
323 @item C-c C-e C-d and C-c C-e d
324 @kindex @kbd{C-c C-e C-d}
325 @kindex @kbd{C-c C-e d}
326 @findex epa-mail-decrypt
327 Decrypt OpenPGP armors in the current buffer.
328
329 @item C-c C-e C-v and C-c C-e v
330 @kindex @kbd{C-c C-e C-v}
331 @kindex @kbd{C-c C-e v}
332 @findex epa-mail-verify
333 Verify OpenPGP cleartext signed messages in the current buffer.
334
335 @item C-c C-e C-s and C-c C-e s
336 @kindex @kbd{C-c C-e C-s}
337 @kindex @kbd{C-c C-e s}
338 @findex epa-mail-sign
339 Compose a signed message from the current buffer.
340
341 @item C-c C-e C-e and C-c C-e e
342 @kindex @kbd{C-c C-e C-e}
343 @kindex @kbd{C-c C-e e}
344 @findex epa-mail-encrypt
345 Compose an encrypted message from the current buffer.
346 By default it tries to build the recipient list from @samp{to},
347 @samp{cc}, and @samp{bcc} fields of the mail header.  To include your
348 key in the recipient list, use @samp{encrypt-to} option in
349 @file{~/.gnupg/gpg.conf}.
350
351 @end table
352
353 @node Encrypting/decrypting gpg files
354 @section Encrypting/decrypting gpg files
355 By default, every file whose name ends with @samp{.gpg} will be
356 treated as encrypted.  That is, when you open such a file, the
357 decrypted text is inserted in the buffer rather than encrypted one.
358 Similarly, when you save the buffer to a @samp{foo.gpg} file,
359 encrypted data is written.
360
361 The file name pattern for encrypted files can be controlled by
362 @var{epa-file-name-regexp}.
363
364 @defvar epa-file-name-regexp
365 Regexp which matches filenames treated as encrypted.
366 @end defvar
367
368 You can disable this behavior with @kbd{M-x epa-file-disable}, and
369 then get it back with @kbd{M-x epa-file-enable}.
370
371 @deffn Command epa-file-disable
372 Disable automatic encryption/decryption of *.gpg files.
373 @end deffn
374
375 @deffn Command epa-file-enable
376 Enable automatic encryption/decryption of *.gpg files.
377 @end deffn
378
379 @noindent
380 By default, @code{epa-file} will try to use symmetric encryption, aka
381 password-based encryption.  If you want to use public key encryption
382 instead, do @kbd{M-x epa-file-select-keys}, which will pops up the key
383 selection dialog.
384
385 @deffn Command epa-file-select-keys
386 Select recipient keys to encrypt the currently visiting file with
387 public key encryption.
388 @end deffn
389
390 You can also change the default behavior with the variable
391 @var{epa-file-select-keys}.
392
393 @defvar epa-file-select-keys
394 Control whether or not to pop up the key selection dialog.
395 @end defvar
396
397 For frequently visited files, it might be a good idea to tell Emacs
398 which encryption method should be used through @xref{File Variables, ,
399 , emacs, the Emacs Manual}.  Use the @code{epa-file-encrypt-to} local
400 variable for this.
401 @vindex epa-file-encrypt-to
402
403 For example, if you want an Elisp file to be encrypted with a
404 public key associated with an email address @samp{ueno@@unixuser.org},
405 add the following line to the beginning of the file.
406
407 @cartouche
408 @lisp
409 ;; -*- epa-file-encrypt-to: ("ueno@@unixuser.org") -*-
410 @end lisp
411 @end cartouche
412
413 Instead, if you want the file always (regardless of the value of the
414 @code{epa-file-select-keys} variable) encrypted with symmetric
415 encryption, change the line as follows.
416
417 @cartouche
418 @lisp
419 ;; -*- epa-file-encrypt-to: nil -*-
420 @end lisp
421 @end cartouche
422
423 Other variables which control the automatic encryption/decryption
424 behavior are below.
425
426 @defvar epa-file-cache-passphrase-for-symmetric-encryption
427 If non-@code{nil}, cache passphrase for symmetric encryption.  The
428 default value is @code{nil}.
429 @end defvar
430
431 @defvar epa-file-inhibit-auto-save
432 If non-@code{nil}, disable auto-saving when opening an encrypted file.
433 The default value is @code{t}.
434 @end defvar
435
436 @node Caching Passphrases
437 @chapter Caching Passphrases
438
439 Typing passphrases is an irritating task if you frequently open and
440 close the same file.  GnuPG and EasyPG Assistant provide mechanisms to
441 remember your passphrases.  However, the configuration is a bit
442 confusing since it depends on your GnuPG installation (GnuPG version 1 or
443 GnuPG version 2), encryption method (symmetric or public key), and whether or
444 not you want to use gpg-agent.  Here are some questions:
445
446 @enumerate
447 @item Do you use GnuPG version 2 instead of GnuPG version 1?
448 @item Do you use symmetric encryption rather than public key encryption?
449 @item Do you want to use gpg-agent?
450 @end enumerate
451
452 Here are configurations depending on your answers:
453
454 @multitable {111} {222} {333} {configuration configuration configuration}
455 @item @b{1} @tab @b{2} @tab @b{3} @tab Configuration
456 @item Yes @tab Yes @tab Yes @tab Set up gpg-agent.
457 @item Yes @tab Yes @tab No @tab You can't, without gpg-agent.
458 @item Yes @tab No @tab Yes @tab Set up gpg-agent.
459 @item Yes @tab No @tab No @tab You can't, without gpg-agent.
460 @item No @tab Yes @tab Yes @tab Set up elisp passphrase cache.
461 @item No @tab Yes @tab No @tab Set up elisp passphrase cache.
462 @item No @tab No @tab Yes @tab Set up gpg-agent.
463 @item No @tab No @tab No @tab You can't, without gpg-agent.
464 @end multitable
465
466 To set up gpg-agent, follow the instruction in GnuPG manual.
467 @pxref{Invoking GPG-AGENT, , Invoking GPG-AGENT, gnupg}.
468
469 To set up elisp passphrase cache, set
470 @code{epa-file-cache-passphrase-for-symmetric-encryption}.
471 @xref{Encrypting/decrypting gpg files}.
472
473 @node Bug Reports
474 @chapter Bug Reports
475
476 Bugs and problems with EasyPG Assistant are actively worked on by the
477 Emacs development team.  Feature requests and suggestions are also
478 more than welcome.  Use @kbd{M-x report-emacs-bug}, @pxref{Bugs, ,
479 Bugs, emacs, Reporting Bugs}.
480
481 When submitting a bug report, please try to describe in excruciating
482 detail the steps required to reproduce the problem.  Also try to
483 collect necessary information to fix the bug, such as:
484
485 @itemize @bullet
486 @item the GnuPG version.  Send the output of @samp{gpg --version}.
487 @item the GnuPG configuration.  Send the contents of @file{~/.gnupg/gpg.conf}.
488 @end itemize
489
490 Before reporting the bug, you should set @code{epg-debug} in the
491 @file{~/.emacs} file and repeat the bug.  Then, include the contents
492 of the @samp{ *epg-debug*} buffer.  Note that the first letter of the
493 buffer name is a whitespace.
494
495 @node GNU Free Documentation License
496 @appendix GNU Free Documentation License
497 @include doclicense.texi
498
499 @node Key Index
500 @unnumbered Key Index
501 @printindex ky
502
503 @node Function Index
504 @unnumbered Function Index
505 @printindex fn
506
507 @node Variable Index
508 @unnumbered Variable Index
509 @printindex vr
510
511 @bye
512
513 @c End: