Mercurial > emacs
comparison man/pgg.texi @ 88155:d7ddb3e565de
sync with trunk
author | Henrik Enberg <henrik.enberg@telia.com> |
---|---|
date | Mon, 16 Jan 2006 00:03:54 +0000 |
parents | |
children |
comparison
equal
deleted
inserted
replaced
88154:8ce476d3ba36 | 88155:d7ddb3e565de |
---|---|
1 \input texinfo @c -*-texinfo-*- | |
2 | |
3 @setfilename ../info/pgg | |
4 | |
5 @set VERSION 0.1 | |
6 | |
7 | |
8 @copying | |
9 This file describes the PGG. | |
10 | |
11 Copyright (C) 2003, 2004, 2005 Free Software Foundation, Inc. | |
12 Copyright (C) 2001 Daiki Ueno. | |
13 | |
14 @quotation | |
15 Permission is granted to copy, distribute and/or modify this document | |
16 under the terms of the GNU Free Documentation License, Version 1.2 or | |
17 any later version published by the Free Software Foundation; with no | |
18 Invariant Sections, with no Front-Cover Texts, and with no Back-Cover | |
19 Texts. A copy of the license is included in the section entitled ``GNU | |
20 Free Documentation License''. | |
21 @end quotation | |
22 @end copying | |
23 | |
24 @dircategory Emacs | |
25 @direntry | |
26 * PGG: (pgg). Emacs interface to various PGP implementations. | |
27 @end direntry | |
28 | |
29 @settitle PGG @value{VERSION} | |
30 | |
31 | |
32 @titlepage | |
33 @title PGG | |
34 | |
35 @author by Daiki Ueno | |
36 @page | |
37 | |
38 @vskip 0pt plus 1filll | |
39 @insertcopying | |
40 @end titlepage | |
41 @page | |
42 | |
43 @node Top | |
44 @top PGG | |
45 This manual describes PGG. PGG is an interface library between Emacs | |
46 and various tools for secure communication. PGG also provides a simple | |
47 user interface to encrypt, decrypt, sign, and verify MIME messages. | |
48 | |
49 @menu | |
50 * Overview:: What PGG is. | |
51 * Prerequisites:: Complicated stuff you may have to do. | |
52 * How to use:: Getting started quickly. | |
53 * Architecture:: | |
54 * Parsing OpenPGP packets:: | |
55 * Function Index:: | |
56 * Variable Index:: | |
57 @end menu | |
58 | |
59 @node Overview | |
60 @chapter Overview | |
61 | |
62 PGG is an interface library between Emacs and various tools for secure | |
63 communication. Even though Mailcrypt has similar feature, it does not | |
64 deal with detached PGP messages, normally used in PGP/MIME | |
65 infrastructure. This was the main reason why I wrote the new library. | |
66 | |
67 PGP/MIME is an application of MIME Object Security Services (RFC1848). | |
68 The standard is documented in RFC2015. | |
69 | |
70 @node Prerequisites | |
71 @chapter Prerequisites | |
72 | |
73 PGG requires at least one implementation of privacy guard system. | |
74 This document assumes that you have already obtained and installed them | |
75 and that you are familiar with its basic functions. | |
76 | |
77 By default, PGG uses GnuPG, but Pretty Good Privacy version 2 or version | |
78 5 are also supported. If you are new to such a system, I recommend that | |
79 you should look over the GNU Privacy Handbook (GPH) which is available | |
80 at @uref{http://www.gnupg.org/gph/}. | |
81 | |
82 @node How to use | |
83 @chapter How to use | |
84 | |
85 The toplevel interface of this library is quite simple, and only | |
86 intended to use with public-key cryptographic operation. | |
87 | |
88 To use PGG, evaluate following expression at the beginning of your | |
89 application program. | |
90 | |
91 @lisp | |
92 (require 'pgg) | |
93 @end lisp | |
94 | |
95 If you want to check existence of pgg.el at runtime, instead you can | |
96 list autoload setting for desired functions as follows. | |
97 | |
98 @lisp | |
99 (autoload 'pgg-encrypt-region "pgg" | |
100 "Encrypt the current region." t) | |
101 (autoload 'pgg-encrypt-symmetric-region "pgg" | |
102 "Encrypt the current region with symmetric algorithm." t) | |
103 (autoload 'pgg-decrypt-region "pgg" | |
104 "Decrypt the current region." t) | |
105 (autoload 'pgg-sign-region "pgg" | |
106 "Sign the current region." t) | |
107 (autoload 'pgg-verify-region "pgg" | |
108 "Verify the current region." t) | |
109 (autoload 'pgg-insert-key "pgg" | |
110 "Insert the ASCII armored public key." t) | |
111 (autoload 'pgg-snarf-keys-region "pgg" | |
112 "Import public keys in the current region." t) | |
113 @end lisp | |
114 | |
115 @menu | |
116 * User Commands:: | |
117 * Selecting an implementation:: | |
118 * Caching passphrase:: | |
119 * Default user identity:: | |
120 @end menu | |
121 | |
122 @node User Commands | |
123 @section User Commands | |
124 | |
125 At this time you can use some cryptographic commands. The behavior of | |
126 these commands relies on a fashion of invocation because they are also | |
127 intended to be used as library functions. In case you don't have the | |
128 signer's public key, for example, the function @code{pgg-verify-region} | |
129 fails immediately, but if the function had been called interactively, it | |
130 would ask you to retrieve the signer's public key from the server. | |
131 | |
132 @deffn Command pgg-encrypt-region start end recipients &optional sign passphrase | |
133 Encrypt the current region between @var{start} and @var{end} for | |
134 @var{recipients}. When the function were called interactively, you | |
135 would be asked about the recipients. | |
136 | |
137 If encryption is successful, it replaces the current region contents (in | |
138 the accessible portion) with the resulting data. | |
139 | |
140 If optional argument @var{sign} is non-@code{nil}, the function is | |
141 request to do a combined sign and encrypt. This currently is | |
142 confirmed to work with GnuPG, but might not work with PGP or PGP5. | |
143 | |
144 If optional @var{passphrase} is @code{nil}, the passphrase will be | |
145 obtained from the passphrase cache or user. | |
146 @end deffn | |
147 | |
148 @deffn Command pgg-encrypt-symmetric-region &optional start end passphrase | |
149 Encrypt the current region between @var{start} and @var{end} using a | |
150 symmetric cipher. After invocation you are asked for a passphrase. | |
151 | |
152 If optional @var{passphrase} is @code{nil}, the passphrase will be | |
153 obtained from the passphrase cache or user. | |
154 | |
155 symmetric-cipher encryption is currently only implemented for GnuPG. | |
156 @end deffn | |
157 | |
158 @deffn Command pgg-decrypt-region start end &optional passphrase | |
159 Decrypt the current region between @var{start} and @var{end}. If | |
160 decryption is successful, it replaces the current region contents (in | |
161 the accessible portion) with the resulting data. | |
162 | |
163 If optional @var{passphrase} is @code{nil}, the passphrase will be | |
164 obtained from the passphrase cache or user. | |
165 @end deffn | |
166 | |
167 @deffn Command pgg-sign-region start end &optional cleartext passphrase | |
168 Make the signature from text between @var{start} and @var{end}. If the | |
169 optional third argument @var{cleartext} is non-@code{nil}, or the | |
170 function is called interactively, it does not create a detached | |
171 signature. In such a case, it replaces the current region contents (in | |
172 the accessible portion) with the resulting data. | |
173 | |
174 If optional @var{passphrase} is @code{nil}, the passphrase will be | |
175 obtained from the passphrase cache or user. | |
176 @end deffn | |
177 | |
178 @deffn Command pgg-verify-region start end &optional signature fetch | |
179 Verify the current region between @var{start} and @var{end}. If the | |
180 optional third argument @var{signature} is non-@code{nil}, it is treated | |
181 as the detached signature file of the current region. | |
182 | |
183 If the optional 4th argument @var{fetch} is non-@code{nil}, or the | |
184 function is called interactively, we attempt to fetch the signer's | |
185 public key from the key server. | |
186 @end deffn | |
187 | |
188 @deffn Command pgg-insert-key | |
189 Retrieve the user's public key and insert it as ASCII-armored format. | |
190 @end deffn | |
191 | |
192 @deffn Command pgg-snarf-keys-region start end | |
193 Collect public keys in the current region between @var{start} and | |
194 @var{end}, and add them into the user's keyring. | |
195 @end deffn | |
196 | |
197 @node Selecting an implementation | |
198 @section Selecting an implementation | |
199 | |
200 Since PGP has a long history and there are a number of PGP | |
201 implementations available today, the function which each one has differs | |
202 considerably. For example, if you are using GnuPG, you know you can | |
203 select cipher algorithm from 3DES, CAST5, BLOWFISH, and so on, but on | |
204 the other hand the version 2 of PGP only supports IDEA. | |
205 | |
206 Which implementation is used is controlled by the @code{pgg-scheme} | |
207 variable. If it is @code{nil} (the default), the value of the | |
208 @code{pgg-default-scheme} variable will be used instead. | |
209 | |
210 @defvar pgg-scheme | |
211 Force specify the scheme of PGP implementation. The value can be set to | |
212 @code{gpg}, @code{pgp}, and @code{pgp5}. The default is @code{nil}. | |
213 @end defvar | |
214 | |
215 @defvar pgg-default-scheme | |
216 The default scheme of PGP implementation. The value should be one of | |
217 @code{gpg}, @code{pgp}, and @code{pgp5}. The default is @code{gpg}. | |
218 @end defvar | |
219 | |
220 @node Caching passphrase | |
221 @section Caching passphrase | |
222 | |
223 PGG provides a simple passphrase caching mechanism. If you want to | |
224 arrange the interaction, set the variable @code{pgg-read-passphrase}. | |
225 | |
226 @defvar pgg-cache-passphrase | |
227 If non-@code{nil}, store passphrases. The default value of this | |
228 variable is @code{t}. If you are worried about security issues, | |
229 however, you could stop the caching of passphrases by setting this | |
230 variable to @code{nil}. | |
231 @end defvar | |
232 | |
233 @defvar pgg-passphrase-cache-expiry | |
234 Elapsed time for expiration in seconds. | |
235 @end defvar | |
236 | |
237 @node Default user identity | |
238 @section Default user identity | |
239 | |
240 The PGP implementation is usually able to select the proper key to use | |
241 for signing and decryption, but if you have more than one key, you may | |
242 need to specify the key id to use. | |
243 | |
244 @defvar pgg-default-user-id | |
245 User ID of your default identity. It defaults to the value returned | |
246 by @samp{(user-login-name)}. You can customize this variable. | |
247 @end defvar | |
248 | |
249 @defvar pgg-gpg-user-id | |
250 User ID of the GnuPG default identity. It defaults to @samp{nil}. | |
251 This overrides @samp{pgg-default-user-id}. You can customize this | |
252 variable. | |
253 @end defvar | |
254 | |
255 @defvar pgg-pgp-user-id | |
256 User ID of the PGP 2.x/6.x default identity. It defaults to | |
257 @samp{nil}. This overrides @samp{pgg-default-user-id}. You can | |
258 customize this variable. | |
259 @end defvar | |
260 | |
261 @defvar pgg-pgp5-user-id | |
262 User ID of the PGP 5.x default identity. It defaults to @samp{nil}. | |
263 This overrides @samp{pgg-default-user-id}. You can customize this | |
264 variable. | |
265 @end defvar | |
266 | |
267 @node Architecture | |
268 @chapter Architecture | |
269 | |
270 PGG introduces the notion of a "scheme of PGP implementation" (used | |
271 interchangeably with "scheme" in this document). This term refers to a | |
272 singleton object wrapped with the luna object system. | |
273 | |
274 Since PGG was designed for accessing and developing PGP functionality, | |
275 the architecture had to be designed not just for interoperability but | |
276 also for extensiblity. In this chapter we explore the architecture | |
277 while finding out how to write the PGG backend. | |
278 | |
279 @menu | |
280 * Initializing:: | |
281 * Backend methods:: | |
282 * Getting output:: | |
283 @end menu | |
284 | |
285 @node Initializing | |
286 @section Initializing | |
287 | |
288 A scheme must be initialized before it is used. | |
289 It had better guarantee to keep only one instance of a scheme. | |
290 | |
291 The following code is snipped out of @file{pgg-gpg.el}. Once an | |
292 instance of @code{pgg-gpg} scheme is initialized, it's stored to the | |
293 variable @code{pgg-scheme-gpg-instance} and will be reused from now on. | |
294 | |
295 @lisp | |
296 (defvar pgg-scheme-gpg-instance nil) | |
297 | |
298 (defun pgg-make-scheme-gpg () | |
299 (or pgg-scheme-gpg-instance | |
300 (setq pgg-scheme-gpg-instance | |
301 (luna-make-entity 'pgg-scheme-gpg)))) | |
302 @end lisp | |
303 | |
304 The name of the function must follow the | |
305 regulation---@code{pgg-make-scheme-} follows the backend name. | |
306 | |
307 @node Backend methods | |
308 @section Backend methods | |
309 | |
310 In each backend, these methods must be present. The output of these | |
311 methods is stored in special buffers (@ref{Getting output}), so that | |
312 these methods must tell the status of the execution. | |
313 | |
314 @deffn Method pgg-scheme-lookup-key scheme string &optional type | |
315 Return keys associated with @var{string}. If the optional third | |
316 argument @var{type} is non-@code{nil}, it searches from the secret | |
317 keyrings. | |
318 @end deffn | |
319 | |
320 @deffn Method pgg-scheme-encrypt-region scheme start end recipients &optional sign passphrase | |
321 Encrypt the current region between @var{start} and @var{end} for | |
322 @var{recipients}. If @var{sign} is non-@code{nil}, do a combined sign | |
323 and encrypt. If encryption is successful, it returns @code{t}, | |
324 otherwise @code{nil}. | |
325 @end deffn | |
326 | |
327 @deffn Method pgg-scheme-encrypt-symmetric-region scheme start end &optional passphrase | |
328 Encrypt the current region between @var{start} and @var{end} using a | |
329 symmetric cipher and a passphrases. If encryption is successful, it | |
330 returns @code{t}, otherwise @code{nil}. This function is currently only | |
331 implemented for GnuPG. | |
332 @end deffn | |
333 | |
334 @deffn Method pgg-scheme-decrypt-region scheme start end &optional passphrase | |
335 Decrypt the current region between @var{start} and @var{end}. If | |
336 decryption is successful, it returns @code{t}, otherwise @code{nil}. | |
337 @end deffn | |
338 | |
339 @deffn Method pgg-scheme-sign-region scheme start end &optional cleartext passphrase | |
340 Make the signature from text between @var{start} and @var{end}. If the | |
341 optional third argument @var{cleartext} is non-@code{nil}, it does not | |
342 create a detached signature. If signing is successful, it returns | |
343 @code{t}, otherwise @code{nil}. | |
344 @end deffn | |
345 | |
346 @deffn Method pgg-scheme-verify-region scheme start end &optional signature | |
347 Verify the current region between @var{start} and @var{end}. If the | |
348 optional third argument @var{signature} is non-@code{nil}, it is treated | |
349 as the detached signature of the current region. If the signature is | |
350 successfully verified, it returns @code{t}, otherwise @code{nil}. | |
351 @end deffn | |
352 | |
353 @deffn Method pgg-scheme-insert-key scheme | |
354 Retrieve the user's public key and insert it as ASCII-armored format. | |
355 On success, it returns @code{t}, otherwise @code{nil}. | |
356 @end deffn | |
357 | |
358 @deffn Method pgg-scheme-snarf-keys-region scheme start end | |
359 Collect public keys in the current region between @var{start} and | |
360 @var{end}, and add them into the user's keyring. | |
361 On success, it returns @code{t}, otherwise @code{nil}. | |
362 @end deffn | |
363 | |
364 @node Getting output | |
365 @section Getting output | |
366 | |
367 The output of the backend methods (@ref{Backend methods}) is stored in | |
368 special buffers, so that these methods must tell the status of the | |
369 execution. | |
370 | |
371 @defvar pgg-errors-buffer | |
372 The standard error output of the execution of the PGP command is stored | |
373 here. | |
374 @end defvar | |
375 | |
376 @defvar pgg-output-buffer | |
377 The standard output of the execution of the PGP command is stored here. | |
378 @end defvar | |
379 | |
380 @defvar pgg-status-buffer | |
381 The rest of status information of the execution of the PGP command is | |
382 stored here. | |
383 @end defvar | |
384 | |
385 @node Parsing OpenPGP packets | |
386 @chapter Parsing OpenPGP packets | |
387 | |
388 The format of OpenPGP messages is maintained in order to publish all | |
389 necessary information needed to develop interoperable applications. | |
390 The standard is documented in RFC 2440. | |
391 | |
392 PGG has its own parser for the OpenPGP packets. | |
393 | |
394 @defun pgg-parse-armor string | |
395 List the sequence of packets in @var{string}. | |
396 @end defun | |
397 | |
398 @defun pgg-parse-armor-region start end | |
399 List the sequence of packets in the current region between @var{start} | |
400 and @var{end}. | |
401 @end defun | |
402 | |
403 @defvar pgg-ignore-packet-checksum | |
404 If non-@code{nil}, don't check the checksum of the packets. | |
405 @end defvar | |
406 | |
407 @node Function Index | |
408 @chapter Function Index | |
409 @printindex fn | |
410 | |
411 @node Variable Index | |
412 @chapter Variable Index | |
413 @printindex vr | |
414 | |
415 @summarycontents | |
416 @contents | |
417 @bye | |
418 | |
419 @c End: | |
420 | |
421 @ignore | |
422 arch-tag: 0c205838-34b9-41a5-b9d7-49ae57ccac85 | |
423 @end ignore |