EasyPG: Initial check-in.
[bpt/emacs.git] / doc / misc / epa.texi
CommitLineData
c154c0be
MO
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
10This file describes EasyPG Assistant.
11
12Copyright @copyright{} 2007, 2008 Free Software Foundation, Inc.
13
14@quotation
15Permission is granted to copy, distribute and/or modify this document
16under the terms of the GNU Free Documentation License, Version 1.2 or
17any later version published by the Free Software Foundation; with no
18Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
19Texts. A copy of the license is included in the section entitled "GNU
20Free Documentation License".
21@end quotation
22@end copying
23
24@dircategory Emacs
25@direntry
26* EasyPG Assistant: (epa). An Emacs user interface to GNU Privacy Guard.
27@end direntry
28
29
30@titlepage
31@title EasyPG Assistant
32
33@author by Daiki Ueno
34@page
35
36@vskip 0pt plus 1filll
37@insertcopying
38@end titlepage
39@page
40
41@c @summarycontents
42@c @contents
43
44@node Top
45@top EasyPG Assistant user's manual
46
47EasyPG Assistant is an Emacs user interface to GNU Privacy Guard
48(GnuPG, @pxref{Top, , Top, gnupg, Using the GNU Privacy Guard}).
49
50EasyPG Assistant is a part of the package called EasyPG, an all-in-one
51GnuPG interface for Emacs. EasyPG also contains the library interface
52called EasyPG Library.
53
54@noindent
55This manual covers EasyPG version @value{VERSION}.
56
57@menu
58* Overview::
59* Quick start::
60* Commands::
61@end menu
62
63@node Overview
64@chapter Overview
65
66EasyPG Assistant provides the following features.
67
68@itemize @bullet
69@item Key manegement.
70@item Cryptographic operations on regions.
71@item Cryptographic operations on files.
72@item Dired integration.
73@item Mail-mode integration.
74@item Automatic encryption/decryption of *.gpg files.
75@end itemize
76
77@node Quick start
78@chapter Quick start
79
80To install, just follow the standard CMMI installation instructions.
81
82@cartouche
83@example
84$ ./configure
85$ sudo make install
86@end example
87@end cartouche
88
89@noindent
90Then, add the following line to your @file{~/.emacs}
91
92@cartouche
93@lisp
94(require 'epa-setup)
95@end lisp
96@end cartouche
97
98@noindent
99That's all. Restart emacs and type @kbd{M-x epa- @key{TAB}}, and you will see a
100lot of commands available. For example,
101
102@itemize @bullet
103@item To browse your keyring, type @kbd{M-x epa-list-keys}
104
105@item To create a cleartext signature of the region, type @kbd{M-x epa-sign-region}
106@end itemize
107
108@node Commands
109@chapter Commands
110
111This chapter introduces various commands for typical use cases.
112
113@menu
114* Key management::
115* Cryptographic operations on regions::
116* Cryptographic operations on files::
117* Dired integration::
118* Mail-mode integration::
119* Encrypting/decrypting *.gpg files::
120@end menu
121
122@node Key management
123@section Key management
124Probably the first step of using EasyPG Assistant is to browse your
125keyring. @kbd{M-x epa-list-keys} is corresponding to @samp{gpg
126--list-keys} from the command line.
127
128@deffn Command epa-list-keys name mode
129Show all keys matched with @var{name} from the public keyring.
130@end deffn
131
132@noindent
133The output looks as follows.
134
135@example
136 u A5B6B2D4B15813FE Daiki Ueno <ueno@@unixuser.org>
137@end example
138
139@noindent
140A character on the leftmost column indicates the trust level of the
141key. If it is @samp{u}, the key is marked as ultimately trusted. The
142second column is the key ID, and the rest is the user ID.
143
144You can move over entries by @key{TAB}. If you type @key{RET} or
145click button1 on an entry, you will see more detailed information
146about the key you selected.
147
148@example
149 u Daiki Ueno <ueno@@unixuser.org>
150 u A5B6B2D4B15813FE 1024bits DSA
151 Created: 2001-10-09
152 Expires: 2007-09-04
153 Capabilities: sign certify
154 Fingerprint: 8003 7CD0 0F1A 9400 03CA 50AA A5B6 B2D4 B158 13FE
155 u 4447461B2A9BEA2D 2048bits ELGAMAL_E
156 Created: 2001-10-09
157 Expires: 2007-09-04
158 Capabilities: encrypt
159 Fingerprint: 9003 D76B 73B7 4A8A E588 10AF 4447 461B 2A9B EA2D
160@end example
161
162@noindent
163To browse your private keyring, use @kbd{M-x epa-list-secret-keys}.
164
165@deffn Command epa-list-secret-keys name
166Show all keys matched with @var{name} from the private keyring.
167@end deffn
168
169@noindent
170In @samp{*Keys*} buffer, several commands are available. The common
171use case is to export some keys to a file. To do that, type @kbd{m}
172to select keys, type @kbd{o}, and then supply the filename.
173
174Below are other commands related to key management. Some of them take
175a file as input/output, and others take the current region.
176
177@deffn Command epa-insert-keys keys
178Insert selected @var{keys} after the point. It will let you select
179keys before insertion. By default, it will encode keys in the OpenPGP
180armor format.
181@end deffn
182
183@deffn Command epa-import-keys file
184Import keys from @var{file} to your keyring.
185@end deffn
186
187@deffn Command epa-import-keys-region start end
188Import keys from the current region between @var{start} and @var{end}
189to your keyring.
190@end deffn
191
192@deffn Command epa-import-armor-in-region start end
193Import keys in the OpenPGP armor format in the current region between
194@var{start} and @var{end}. The difference from
195@code{epa-import-keys-region} is that
196@code{epa-import-armor-in-region} searches armors in the region and
197applies @code{epa-import-keys-region} to each of them.
198@end deffn
199
200@deffn Command epa-delete-keys allow-secret
201Delete selected keys. If @var{allow-secret} is non-@code{nil}, it
202also delete the secret keys.
203@end deffn
204
205@node Cryptographic operations on regions
206@section Cryptographic operations on regions
207
208@deffn Command epa-decrypt-region start end
209Decrypt the current region between @var{start} and @var{end}. It
210replaces the region with the decrypted text.
211@end deffn
212
213@deffn Command epa-decrypt-armor-in-region start end
214Decrypt OpenPGP armors in the current region between @var{start} and
215@var{end}. The difference from @code{epa-decrypt-region} is that
216@code{epa-decrypt-armor-in-region} searches armors in the region
217and applies @code{epa-decrypt-region} to each of them. That is, this
218command does not alter the original text around armors.
219@end deffn
220
221@deffn Command epa-verify-region start end
222Verify the current region between @var{start} and @var{end}. It sends
223the verification result to the minibuffer or a popup window. It
224replaces the region with the signed text.
225@end deffn
226
227@deffn Command epa-verify-cleartext-in-region
228Verify OpenPGP cleartext blocks in the current region between
229@var{start} and @var{end}. The difference from
230@code{epa-verify-region} is that @code{epa-verify-cleartext-in-region}
231searches OpenPGP cleartext blocks in the region and applies
232@code{epa-verify-region} to each of them. That is, this command does
233not alter the original text around OpenPGP cleartext blocks.
234@end deffn
235
236@deffn Command epa-sign-region start end signers type
237Sign the current region between @var{start} and @var{end}. By
238default, it creates a cleartext signature. If a prefix argument is
239given, it will let you select signing keys, and then a signature
240type.
241@end deffn
242
243@deffn Command epa-encrypt-region start end recipients sign signers
244Encrypt the current region between @var{start} and @var{end}. It will
245let you select recipients. If a prefix argument is given, it will
246also ask you whether or not to sign the text before encryption and if
247you answered yes, it will let you select the signing keys.
248@end deffn
249
250@node Cryptographic operations on files
251@section Cryptographic operations on files
252
253@deffn Command epa-decrypt-file file
254Decrypt @var{file}.
255@end deffn
256
257@deffn Command epa-verify-file file
258Verify @var{file}.
259@end deffn
260
261@deffn Command epa-sign-file file signers type
262Sign @var{file}. If a prefix argument is given, it will let you
263select signing keys, and then a signature type.
264@end deffn
265
266@deffn Command epa-encrypt-file file recipients
267Encrypt @var{file}. It will let you select recipients.
268@end deffn
269
270@node Dired integration
271@section Dired integration
272
273EasyPG Assistant extends Dired Mode for GNU Emacs to allow users to
274easily do cryptographic operations on files. For example,
275
276@example
277M-x dired
278(mark some files)
279: e (or M-x epa-dired-do-encrypt)
280(select recipients by 'm' and click [OK])
281@end example
282
283@noindent
284The following keys are assigned.
285
286@table @kbd
287@item : d
288@kindex @kbd{: d}
289@findex epa-dired-do-decrypt
290Decrypt marked files.
291
292@item : v
293@kindex @kbd{: v}
294@findex epa-dired-do-verify
295Verify marked files.
296
297@item : s
298@kindex @kbd{: s}
299@findex epa-dired-do-sign
300Sign marked files.
301
302@item : e
303@kindex @kbd{: e}
304@findex epa-dired-do-encrypt
305Encrypt marked files.
306
307@end table
308
309@node Mail-mode integration
310@section Mail-mode integration
311
312EasyPG Assistant provides a minor mode to help user compose inline PGP
313messages. Inline PGP is sending the OpenPGP blobs directly inside a
314mail message and it is not recommended and you should consider to use
315PGP/MIME. See
316@uref{http://josefsson.org/inline-openpgp-considered-harmful.html,
317Inline PGP in E-mail is bad, Mm'kay?}.
318
319@noindent
320The following keys are assigned.
321
322@table @kbd
323@item C-c C-e d
324@kindex @kbd{C-c C-e d}
325@findex epa-mail-decrypt
326Decrypt OpenPGP armors in the current buffer.
327
328@item C-c C-e v
329@kindex @kbd{C-c C-e v}
330@findex epa-mail-verify
331Verify OpenPGP cleartext signed messages in the current buffer.
332
333@item C-c C-e s
334@kindex @kbd{C-c C-e s}
335@findex epa-mail-sign
336Compose a signed message from the current buffer.
337
338@item C-c C-e e
339@kindex @kbd{C-c C-e e}
340@findex epa-mail-encrypt
341Compose an encrypted message from the current buffer.
342
343@end table
344
345@node Encrypting/decrypting *.gpg files
346@section Encrypting/decrypting *.gpg files
347Once @code{epa-setup} is loaded, every file whose extension is
348@samp{.gpg} will be treated as encrypted. That is, when you attempt
349to open such a file which already exists, the decrypted text is
350inserted in the buffer rather than encrypted one. On the other hand,
351when you attempt to save the buffer to a file whose extension is
352@samp{.gpg}, encrypted data is written.
353
354If you want to temporarily disable this behavior, use @kbd{M-x
355epa-file-disable}, and then to enable this behavior use @kbd{M-x
356epa-file-enable}.
357
358@deffn Command epa-file-disable
359Disable automatic encryption/decryption of *.gpg files.
360@end deffn
361
362@deffn Command epa-file-enable
363Enable automatic encryption/decryption of *.gpg files.
364@end deffn
365
366@noindent
367@code{epa-file} will let you select recipients. If you want to
368suppress this question, it might be a good idea to put the following
369line on the first line of the text being encrypted.
370@vindex epa-file-encrypt-to
371
372@cartouche
373@lisp
374;; -*- epa-file-encrypt-to: ("ueno@@unixuser.org") -*-
375@end lisp
376@end cartouche
377
378Other variables which control the automatic encryption/decryption
379behavior are below.
380
381@defvar epa-file-cache-passphrase-for-symmetric-encryption
382If non-@code{nil}, cache passphrase for symmetric encryption. The
383default value is @code{nil}.
384@end defvar
385
386@defvar epa-file-inhibit-auto-save
387If non-@code{nil}, disable auto-saving when opening an encrypted file.
388The default value is @code{t}.
389@end defvar
390
391@bye
392
393@c End: