Commit | Line | Data |
---|---|---|
23f87bed MB |
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 | ||
b65d8176 | 11 | Copyright (C) 2003, 2004, 2005 Free Software Foundation, Inc. |
23f87bed MB |
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.1 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-decrypt-region "pgg" | |
102 | "Decrypt the current region." t) | |
103 | (autoload 'pgg-sign-region "pgg" | |
104 | "Sign the current region." t) | |
105 | (autoload 'pgg-verify-region "pgg" | |
106 | "Verify the current region." t) | |
107 | (autoload 'pgg-insert-key "pgg" | |
108 | "Insert the ASCII armored public key." t) | |
109 | (autoload 'pgg-snarf-keys-region "pgg" | |
110 | "Import public keys in the current region." t) | |
111 | @end lisp | |
112 | ||
113 | @menu | |
114 | * User Commands:: | |
115 | * Selecting an implementation:: | |
116 | * Caching passphrase:: | |
117 | * Default user identity:: | |
118 | @end menu | |
119 | ||
120 | @node User Commands | |
121 | @section User Commands | |
122 | ||
123 | At this time you can use some cryptographic commands. The behavior of | |
124 | these commands relies on a fashion of invocation because they are also | |
125 | intended to be used as library functions. In case you don't have the | |
126 | signer's public key, for example, the function @code{pgg-verify-region} | |
127 | fails immediately, but if the function had been called interactively, it | |
128 | would ask you to retrieve the signer's public key from the server. | |
129 | ||
130 | @deffn Command pgg-encrypt-region start end recipients &optional sign | |
131 | Encrypt the current region between @var{start} and @var{end} for | |
132 | @var{recipients}. When the function were called interactively, you | |
133 | would be asked about the recipients. | |
134 | ||
135 | If encryption is successful, it replaces the current region contents (in | |
136 | the accessible portion) with the resulting data. | |
137 | ||
f4dd4ae8 MB |
138 | If optional argument @var{sign} is non-@code{nil}, the function is |
139 | request to do a combined sign and encrypt. This currently only work | |
140 | with GnuPG. | |
23f87bed MB |
141 | @end deffn |
142 | ||
143 | @deffn Command pgg-decrypt-region start end | |
144 | Decrypt the current region between @var{start} and @var{end}. If | |
145 | decryption is successful, it replaces the current region contents (in | |
146 | the accessible portion) with the resulting data. | |
147 | @end deffn | |
148 | ||
149 | @deffn Command pgg-sign-region start end &optional cleartext | |
150 | Make the signature from text between @var{start} and @var{end}. If the | |
151 | optional third argument @var{cleartext} is non-@code{nil}, or the | |
152 | function is called interactively, it does not create a detached | |
153 | signature. In such a case, it replaces the current region contents (in | |
154 | the accessible portion) with the resulting data. | |
155 | @end deffn | |
156 | ||
157 | @deffn Command pgg-verify-region start end &optional signature fetch | |
158 | Verify the current region between @var{start} and @var{end}. If the | |
159 | optional third argument @var{signature} is non-@code{nil}, or the function | |
160 | is called interactively, it is treated as the detached signature of the | |
161 | current region. | |
162 | ||
163 | If the optional 4th argument @var{fetch} is non-@code{nil}, or the | |
164 | function is called interactively, we attempt to fetch the signer's | |
165 | public key from the key server. | |
166 | @end deffn | |
167 | ||
168 | @deffn Command pgg-insert-key | |
169 | Retrieve the user's public key and insert it as ASCII-armored format. | |
170 | @end deffn | |
171 | ||
172 | @deffn Command pgg-snarf-keys-region start end | |
173 | Collect public keys in the current region between @var{start} and | |
174 | @var{end}, and add them into the user's keyring. | |
175 | @end deffn | |
176 | ||
177 | @node Selecting an implementation | |
178 | @section Selecting an implementation | |
179 | ||
180 | Since PGP has a long history and there are a number of PGP | |
181 | implementations available today, the function which each one has differs | |
182 | considerably. For example, if you are using GnuPG, you know you can | |
183 | select cipher algorithm from 3DES, CAST5, BLOWFISH, and so on, but on | |
184 | the other hand the version 2 of PGP only supports IDEA. | |
185 | ||
186 | By default, if the variable @code{pgg-scheme} is not set, PGG searches the | |
187 | registered scheme for an implementation of the requested service | |
188 | associated with the named algorithm. If there are no match, PGG uses | |
189 | @code{pgg-default-scheme}. In other words, there are two options to | |
190 | control which command is used to process the incoming PGP armors. One | |
191 | is for encrypting and signing, the other is for decrypting and | |
192 | verifying. | |
193 | ||
194 | @defvar pgg-scheme | |
195 | Force specify the scheme of PGP implementation for decrypting and verifying. | |
196 | The value can be @code{gpg}, @code{pgp}, and @code{pgp5}. | |
197 | @end defvar | |
198 | ||
199 | @defvar pgg-default-scheme | |
200 | Force specify the scheme of PGP implementation for encrypting and signing. | |
201 | The value can be @code{gpg}, @code{pgp}, and @code{pgp5}. | |
202 | @end defvar | |
203 | ||
204 | @node Caching passphrase | |
205 | @section Caching passphrase | |
206 | ||
207 | PGG provides a simple passphrase caching mechanism. If you want to | |
208 | arrange the interaction, set the variable @code{pgg-read-passphrase}. | |
209 | ||
210 | @defvar pgg-cache-passphrase | |
211 | If non-@code{nil}, store passphrases. The default value of this | |
212 | variable is @code{t}. If you were worry about security issue, however, | |
213 | you could stop caching with setting it @code{nil}. | |
214 | @end defvar | |
215 | ||
216 | @defvar pgg-passphrase-cache-expiry | |
217 | Elapsed time for expiration in seconds. | |
218 | @end defvar | |
219 | ||
220 | @node Default user identity | |
221 | @section Default user identity | |
222 | ||
223 | The PGP implementation is usually able to select the proper key to use | |
224 | for signing and decryption, but if you have more than one key, you may | |
225 | need to specify the key id to use. | |
226 | ||
227 | @defvar pgg-default-user-id | |
228 | User ID of your default identity. It defaults to the value returned | |
229 | by @samp{(user-login-name)}. You can customize this variable. | |
230 | @end defvar | |
231 | ||
232 | @defvar pgg-gpg-user-id | |
233 | User ID of the GnuPG default identity. It defaults to @samp{nil}. | |
234 | This overrides @samp{pgg-default-user-id}. You can customize this | |
235 | variable. | |
236 | @end defvar | |
237 | ||
238 | @defvar pgg-pgp-user-id | |
239 | User ID of the PGP 2.x/6.x default identity. It defaults to | |
240 | @samp{nil}. This overrides @samp{pgg-default-user-id}. You can | |
241 | customize this variable. | |
242 | @end defvar | |
243 | ||
244 | @defvar pgg-pgp5-user-id | |
245 | User ID of the PGP 5.x default identity. It defaults to @samp{nil}. | |
246 | This overrides @samp{pgg-default-user-id}. You can customize this | |
247 | variable. | |
248 | @end defvar | |
249 | ||
250 | @node Architecture | |
251 | @chapter Architecture | |
252 | ||
253 | PGG introduces the notion of a "scheme of PGP implementation" (used | |
254 | interchangeably with "scheme" in this document). This term refers to a | |
255 | singleton object wrapped with the luna object system. | |
256 | ||
257 | Since PGG was designed for accessing and developing PGP functionality, | |
258 | the architecture had to be designed not just for interoperability but | |
259 | also for extensiblity. In this chapter we explore the architecture | |
260 | while finding out how to write the PGG backend. | |
261 | ||
262 | @menu | |
263 | * Initializing:: | |
264 | * Backend methods:: | |
265 | * Getting output:: | |
266 | @end menu | |
267 | ||
268 | @node Initializing | |
269 | @section Initializing | |
270 | ||
271 | A scheme must be initialized before it is used. | |
272 | It had better guarantee to keep only one instance of a scheme. | |
273 | ||
274 | The following code is snipped out of @file{pgg-gpg.el}. Once an | |
275 | instance of @code{pgg-gpg} scheme is initialized, it's stored to the | |
276 | variable @code{pgg-scheme-gpg-instance} and will be reused from now on. | |
277 | ||
278 | @lisp | |
279 | (defvar pgg-scheme-gpg-instance nil) | |
280 | ||
281 | (defun pgg-make-scheme-gpg () | |
282 | (or pgg-scheme-gpg-instance | |
283 | (setq pgg-scheme-gpg-instance | |
284 | (luna-make-entity 'pgg-scheme-gpg)))) | |
285 | @end lisp | |
286 | ||
287 | The name of the function must follow the | |
288 | regulation---@code{pgg-make-scheme-} follows the backend name. | |
289 | ||
290 | @node Backend methods | |
291 | @section Backend methods | |
292 | ||
293 | In each backend, these methods must be present. The output of these | |
294 | methods is stored in special buffers (@ref{Getting output}), so that | |
295 | these methods must tell the status of the execution. | |
296 | ||
297 | @deffn Method pgg-scheme-lookup-key scheme string &optional type | |
298 | Return keys associated with @var{string}. If the optional third | |
299 | argument @var{type} is non-@code{nil}, it searches from the secret | |
300 | keyrings. | |
301 | @end deffn | |
302 | ||
303 | @deffn Method pgg-scheme-encrypt-region scheme start end recipients &optional sign | |
304 | Encrypt the current region between @var{start} and @var{end} for | |
f4dd4ae8 MB |
305 | @var{recipients}. If @var{sign} is non-@code{nil}, do a combined sign |
306 | and encrypt. If encryption is successful, it returns @code{t}, | |
307 | otherwise @code{nil}. | |
23f87bed MB |
308 | @end deffn |
309 | ||
310 | @deffn Method pgg-scheme-decrypt-region scheme start end | |
311 | Decrypt the current region between @var{start} and @var{end}. If | |
312 | decryption is successful, it returns @code{t}, otherwise @code{nil}. | |
313 | @end deffn | |
314 | ||
315 | @deffn Method pgg-scheme-sign-region scheme start end &optional cleartext | |
316 | Make the signature from text between @var{start} and @var{end}. If the | |
317 | optional third argument @var{cleartext} is non-@code{nil}, it does not | |
318 | create a detached signature. If signing is successful, it returns | |
319 | @code{t}, otherwise @code{nil}. | |
320 | @end deffn | |
321 | ||
322 | @deffn Method pgg-scheme-verify-region scheme start end &optional signature | |
323 | Verify the current region between @var{start} and @var{end}. If the | |
324 | optional third argument @var{signature} is non-@code{nil}, it is treated | |
325 | as the detached signature of the current region. If the signature is | |
326 | successfully verified, it returns @code{t}, otherwise @code{nil}. | |
327 | @end deffn | |
328 | ||
329 | @deffn Method pgg-scheme-insert-key scheme | |
330 | Retrieve the user's public key and insert it as ASCII-armored format. | |
331 | On success, it returns @code{t}, otherwise @code{nil}. | |
332 | @end deffn | |
333 | ||
334 | @deffn Method pgg-scheme-snarf-keys-region scheme start end | |
335 | Collect public keys in the current region between @var{start} and | |
336 | @var{end}, and add them into the user's keyring. | |
337 | On success, it returns @code{t}, otherwise @code{nil}. | |
338 | @end deffn | |
339 | ||
340 | @node Getting output | |
341 | @section Getting output | |
342 | ||
343 | The output of the backend methods (@ref{Backend methods}) is stored in | |
344 | special buffers, so that these methods must tell the status of the | |
345 | execution. | |
346 | ||
347 | @defvar pgg-errors-buffer | |
348 | The standard error output of the execution of the PGP command is stored | |
349 | here. | |
350 | @end defvar | |
351 | ||
352 | @defvar pgg-output-buffer | |
353 | The standard output of the execution of the PGP command is stored here. | |
354 | @end defvar | |
355 | ||
356 | @defvar pgg-status-buffer | |
357 | The rest of status information of the execution of the PGP command is | |
358 | stored here. | |
359 | @end defvar | |
360 | ||
361 | @node Parsing OpenPGP packets | |
362 | @chapter Parsing OpenPGP packets | |
363 | ||
364 | The format of OpenPGP messages is maintained in order to publish all | |
365 | necessary information needed to develop interoperable applications. | |
366 | The standard is documented in RFC 2440. | |
367 | ||
368 | PGG has its own parser for the OpenPGP packets. | |
369 | ||
370 | @defun pgg-parse-armor string | |
371 | List the sequence of packets in @var{string}. | |
372 | @end defun | |
373 | ||
374 | @defun pgg-parse-armor-region start end | |
375 | List the sequence of packets in the current region between @var{start} | |
376 | and @var{end}. | |
377 | @end defun | |
378 | ||
379 | @defvar pgg-ignore-packet-checksum | |
380 | If non-@code{nil}, don't check the checksum of the packets. | |
381 | @end defvar | |
382 | ||
383 | @node Function Index | |
384 | @chapter Function Index | |
385 | @printindex fn | |
386 | ||
387 | @node Variable Index | |
388 | @chapter Variable Index | |
389 | @printindex vr | |
390 | ||
391 | @summarycontents | |
392 | @contents | |
393 | @bye | |
394 | ||
395 | @c End: | |
396 | ||
397 | @ignore | |
398 | arch-tag: 0c205838-34b9-41a5-b9d7-49ae57ccac85 | |
399 | @end ignore |