1 \input texinfo @c -*- mode: texinfo -*-
4 @settitle EasyPG Assistant
7 @c @documentlanguage en
9 @dircategory GNU Emacs Lisp
11 * epa: (epa). EasyPG Assistant
15 This file describes EasyPG Assistant.
17 Copyright (C) 2007 Daiki Ueno.
19 Permission is granted to copy, distribute and/or modify this document
20 under the terms of the GNU Free Documentation License, Version 1.1 or
21 any later version published by the Free Software Foundation; with no
22 Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
23 Texts. A copy of the license is included in the section entitled "GNU
24 Free Documentation License".
30 @title EasyPG Assistant
35 @vskip 0pt plus 1filll
36 Copyright @copyright{} 2007 Daiki Ueno.
38 Permission is granted to copy, distribute and/or modify this document
39 under the terms of the GNU Free Documentation License, Version 1.1 or
40 any later version published by the Free Software Foundation; with no
41 Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
42 Texts. A copy of the license is included in the section entitled "GNU
43 Free Documentation License".
53 @top EasyPG Assistant user's manual
55 EasyPG Assistant is an Emacs user interface for GNU Privacy Guard
56 (GnuPG, @pxref{Top, , Top, gnupg, Using the GNU Privacy Guard}).
58 EasyPG Assistant is a part of the package called EasyPG, an all-in-one
59 GnuPG interface for Emacs. EasyPG also contains the library interface
60 called EasyPG Library.
63 This manual covers EasyPG version @value{VERSION}.
74 EasyPG Assistant provides the following features.
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.
88 To install, just follow the standard CMMI installation instructions.
98 Then, add the following line to your @file{~/.emacs}
107 That's all. Restart emacs and type @kbd{M-x epa- @key{TAB}}, and you will see a
108 lot of commands available. For example,
111 @item To browse your keyring, type @kbd{M-x epa-list-keys}
113 @item To create a cleartext signature of the region, type @kbd{M-x epa-sign-region}
119 This chapter introduces various commands for typical use cases.
123 * Cryptographic operations on regions::
124 * Cryptographic operations on files::
125 * Dired integration::
126 * Mail-mode integration::
127 * Encrypting/decrypting *.gpg files::
131 @section Key management
132 Probably the first step of using EasyPG Assistant is to browse your
133 keyring. @kbd{M-x epa-list-keys} is corresponding to @samp{gpg
134 --list-keys} from the command line.
136 @deffn Command epa-list-keys name mode
137 Show all keys matched with @var{name} from the public keyring.
141 The output looks as follows.
144 u A5B6B2D4B15813FE Daiki Ueno <ueno@@unixuser.org>
148 A character on the leftmost column indicates the trust level of the
149 key. If it is @samp{u}, the key is marked as ultimately trusted. The
150 second column is the key ID, and the rest is the user ID.
152 You can move over entries by @key{TAB}. If you type @key{RET} or
153 click button1 on an entry, you will see more detailed information
154 about the key you selected.
157 u Daiki Ueno <ueno@@unixuser.org>
158 u A5B6B2D4B15813FE 1024bits DSA
161 Capabilities: sign certify
162 Fingerprint: 8003 7CD0 0F1A 9400 03CA 50AA A5B6 B2D4 B158 13FE
163 u 4447461B2A9BEA2D 2048bits ELGAMAL_E
166 Capabilities: encrypt
167 Fingerprint: 9003 D76B 73B7 4A8A E588 10AF 4447 461B 2A9B EA2D
171 To browse your private keyring, use @kbd{M-x epa-list-secret-keys}.
173 @deffn Command epa-list-secret-keys name
174 Show all keys matched with @var{name} from the private keyring.
178 In @samp{*Keys*} buffer, several commands are available. The common
179 use case is to export some keys to a file. To do that, type @kbd{m}
180 to select keys, type @kbd{o}, and then supply the filename.
182 Below are other commands related to key management. Some of them take
183 a file as input/output, and others take the current region.
185 @deffn Command epa-insert-keys keys
186 Insert selected @var{keys} after the point. It will let you select
187 keys before insertion. By default, it will encode keys in the OpenPGP
191 @deffn Command epa-import-keys file
192 Import keys from @var{file} to your keyring.
195 @deffn Command epa-import-keys-region start end
196 Import keys from the current region between @var{start} and @var{end}
200 @deffn Command epa-import-armor-in-region start end
201 Import keys in the OpenPGP armor format in the current region between
202 @var{start} and @var{end}. The difference from
203 @code{epa-import-keys-region} is that
204 @code{epa-import-armor-in-region} searches armors in the region and
205 applies @code{epa-import-keys-region} to each of them.
208 @deffn Command epa-delete-keys allow-secret
209 Delete selected keys. If @var{allow-secret} is non-@code{nil}, it
210 also delete the secret keys.
213 @node Cryptographic operations on regions
214 @section Cryptographic operations on regions
216 @deffn Command epa-decrypt-region start end
217 Decrypt the current region between @var{start} and @var{end}. It
218 replaces the region with the decrypted text.
221 @deffn Command epa-decrypt-armor-in-region start end
222 Decrypt OpenPGP armors in the current region between @var{start} and
223 @var{end}. The difference from @code{epa-decrypt-region} is that
224 @code{epa-decrypt-armor-in-region} searches armors in the region
225 and applies @code{epa-decrypt-region} to each of them. That is, this
226 command does not alter the original text around armors.
229 @deffn Command epa-verify-region start end
230 Verify the current region between @var{start} and @var{end}. It sends
231 the verification result to the minibuffer or a popup window. It
232 replaces the region with the signed text.
235 @deffn Command epa-verify-cleartext-in-region
236 Verify OpenPGP cleartext blocks in the current region between
237 @var{start} and @var{end}. The difference from
238 @code{epa-verify-region} is that @code{epa-verify-cleartext-in-region}
239 searches OpenPGP cleartext blocks in the region and applies
240 @code{epa-verify-region} to each of them. That is, this command does
241 not alter the original text around OpenPGP cleartext blocks.
244 @deffn Command epa-sign-region start end signers type
245 Sign the current region between @var{start} and @var{end}. By
246 default, it creates a cleartext signature. If a prefix argument is
247 given, it will let you select signing keys, and then a signature
251 @deffn Command epa-encrypt-region start end recipients sign signers
252 Encrypt the current region between @var{start} and @var{end}. It will
253 let you select recipients. If a prefix argument is given, it will
254 also ask you whether or not to sign the text before encryption and if
255 you answered yes, it will let you select the signing keys.
258 @node Cryptographic operations on files
259 @section Cryptographic operations on files
261 @deffn Command epa-decrypt-file file
265 @deffn Command epa-verify-file file
269 @deffn Command epa-sign-file file signers type
270 Sign @var{file}. If a prefix argument is given, it will let you
271 select signing keys, and then a signature type.
274 @deffn Command epa-encrypt-file file recipients
275 Encrypt @var{file}. It will let you select recipients.
278 @node Dired integration
279 @section Dired integration
281 EasyPG Assistant extends Dired Mode for GNU Emacs to allow users to
282 easily do cryptographic operations on files. For example,
287 : e (or M-x epa-dired-do-encrypt)
288 (select recipients by 'm' and click [OK])
292 The following keys are assigned.
297 @findex epa-dired-do-decrypt
298 Decrypt marked files.
302 @findex epa-dired-do-verify
307 @findex epa-dired-do-sign
312 @findex epa-dired-do-encrypt
313 Encrypt marked files.
317 @node Mail-mode integration
318 @section Mail-mode integration
320 EasyPG Assistant provides a minor mode to help composing clearsigned
321 or OpenPGP armored encrypted mails. The following keys are assigned.
325 @node Encrypting/decrypting *.gpg files
326 @section Encrypting/decrypting *.gpg files
327 Once @code{epa-setup} is loaded, every file whose extension is
328 @samp{.gpg} will be treated as encrypted. That is, when you attempt
329 to open such a file which already exists, the decrypted text is
330 inserted in the buffer rather than encrypted one. On the other hand,
331 when you attempt to save the buffer to a file whose extension is
332 @samp{.gpg}, encrypted data is written.
334 If you want to temporarily disable this behavior, use @kbd{M-x
335 epa-file-disable}, and then to enable this behavior use @kbd{M-x
338 @deffn Command epa-file-disable
339 Disable automatic encryption/decryption of *.gpg files.
342 @deffn Command epa-file-enable
343 Enable automatic encryption/decryption of *.gpg files.
347 @code{epa-file} will let you select recipients. If you want to
348 suppress this question, it might be a good idea to put the following
349 line on the first line of the text being encrypted.
350 @vindex epa-file-encrypt-to
354 ;; -*- epa-file-encrypt-to: ("ueno@@unixuser.org") -*-
358 Other variables which control the automatic encryption/decryption
361 @defvar epa-file-cache-passphrase-for-symmetric-encryption
362 If non-@code{nil}, cache passphrase for symmetric encryption. The
363 default value is @code{nil}.
366 @defvar epa-file-inhibit-auto-save
367 If non-@code{nil}, disable auto-saving when opening an encrypted file.
368 The default value is @code{t}.