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