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