1 \input texinfo @c -*-texinfo-*-
8 * PGG: (pgg). Emacs interface to various PGP implementations.
11 @settitle PGG @value{VERSION}
14 This file describes the PGG.
16 Copyright (C) 2001 Daiki Ueno.
18 Permission is granted to copy, distribute and/or modify this document
19 under the terms of the GNU Free Documentation License, Version 1.1 or
20 any later version published by the Free Software Foundation; with no
21 Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
22 Texts. A copy of the license is included in the section entitled "GNU
23 Free Documentation License".
34 @vskip 0pt plus 1filll
35 Copyright @copyright{} 2001 Daiki Ueno.
37 Permission is granted to copy, distribute and/or modify this document
38 under the terms of the GNU Free Documentation License, Version 1.1 or
39 any later version published by the Free Software Foundation; with no
40 Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
41 Texts. A copy of the license is included in the section entitled "GNU
42 Free Documentation License".
50 This manual describes PGG. PGG is an interface library between Emacs
51 and various tools for secure communication. PGG also provides a simple
52 user interface to encrypt, decrypt, sign, and verify MIME messages.
55 * Overview:: What PGG is.
56 * Prerequisites:: Complicated stuff you may have to do.
57 * How to use:: Getting started quickly.
59 * Parsing OpenPGP packets::
67 PGG is an interface library between Emacs and various tools for secure
68 communication. Even though Mailcrypt has similar feature, it does not
69 deal with detached PGP messages, normally used in PGP/MIME
70 infrastructure. This was the main reason why I wrote the new library.
72 PGP/MIME is an application of MIME Object Security Services (RFC1848).
73 The standard is documented in RFC2015.
76 @chapter Prerequisites
78 PGG requires at least one implementation of privacy guard system.
79 This document assumes that you have already obtained and installed them
80 and that you are familiar with its basic functions.
82 By default, PGG uses GnuPG, but Pretty Good Privacy version 2 or version
83 5 are also supported. If you are new to such a system, I recomend that
84 you should look over the GNU Privacy Handbook (GPH) which is available
85 at @uref{http://www.gnupg.org/gph/}.
90 The toplevel interface of this library is quite simple, and only
91 intended to use with public-key cryptographic operation.
93 To use PGG, evaluate following expression at the beginning of your
100 If you want to check existence of pgg.el at runtime, instead you can
101 list autoload setting for desired functions as follows.
104 (autoload 'pgg-encrypt-region "pgg"
105 "Encrypt the current region." t)
106 (autoload 'pgg-decrypt-region "pgg"
107 "Decrypt the current region." t)
108 (autoload 'pgg-sign-region "pgg"
109 "Sign the current region." t)
110 (autoload 'pgg-verify-region "pgg"
111 "Verify the current region." t)
112 (autoload 'pgg-insert-key "pgg"
113 "Insert the ASCII armored public key." t)
114 (autoload 'pgg-snarf-keys-region "pgg"
115 "Import public keys in the current region." t)
120 * Selecting an implementation::
121 * Caching passphrase::
125 @section User Commands
127 At this time you can use some cryptographic commands. The behavior of
128 these commands relies on a fashion of invocation because they are also
129 intended to be used as library functions. In case you don't have the
130 signer's public key, for example, the function @code{pgg-verify-region}
131 fails immediately, but if the function had been called interactively, it
132 would ask you to retrieve the signer's public key from the server.
134 @deffn Command pgg-encrypt-region start end recipients
135 Encrypt the current region between @var{start} and @var{end} for
136 @var{recipients}. When the function were called interactively, you
137 would be asked about the recipients.
139 If encryption is successful, it replaces the current region contents (in
140 the accessible portion) with the resulting data.
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.
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.
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
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.
168 @deffn Command pgg-insert-key
169 Retrieve the user's public key and insert it as ASCII-armored format.
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.
177 @node Selecting an implementation
178 @section Selecting an implementation
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.
186 By default, if the variable @var{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 @var{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
195 Force specify the scheme of PGP implementation for decrypting and verifying.
196 The value can be @code{gpg}, @code{pgp}, and @code{pgp5}.
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}.
204 @node Caching passphrase
205 @section Caching passphrase
207 PGG provides a simple passphrase caching mechanism. If you want to
208 arrange the interaction, set the variable @var{pgg-read-passphrase}.
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}.
216 @defvar pgg-passphrase-cache-expiry
217 Elapsed time for expiration in seconds.
221 @chapter Architecture
223 PGG introduces the notion of a "scheme of PGP implementation" (used
224 interchangeably with "scheme" in this document). This term refers to a
225 singleton object wrapped with the luna object system.
227 Since PGG was designed for accessing and developing PGP functionality,
228 the architecture had to be designed not just for interoperablity but
229 also for extensiblity. In this chapter we explore the architecture
230 while finding out how to write the PGG backend.
236 * Registering backend::
240 @section Initializing
242 A scheme must be initialized before it is used.
243 It had better guarantee to keep only one instance of a scheme.
245 The following code is snipped out of @file{pgg-gpg.el}. Once an
246 instance of @code{pgg-gpg} scheme is initialized, it's stored to the
247 variable @var{pgg-scheme-gpg-instance} and will be reused from now on.
250 (defvar pgg-scheme-gpg-instance nil)
252 (defun pgg-make-scheme-gpg ()
253 (or pgg-scheme-gpg-instance
254 (setq pgg-scheme-gpg-instance
255 (luna-make-entity 'pgg-scheme-gpg))))
258 The name of the function must follow the
259 regulation---@code{pgg-make-scheme-} follows the backend name.
261 @node Backend methods
262 @section Backend methods
264 In each backend, these methods must be present. The output of these
265 methods is stored in special buffers (@ref{Getting output}), so that
266 these methods must tell the status of the execution.
268 @deffn Method pgg-scheme-lookup-key scheme string &optional type
269 Return keys associated with @var{string}. If the optional third
270 argument @var{type} is non-@code{nil}, it searches from the secret
274 @deffn Method pgg-scheme-encrypt-region scheme start end recipients
275 Encrypt the current region between @var{start} and @var{end} for
276 @var{recipients}. If encryption is successful, it returns @code{t},
277 otherwise @code{nil}.
280 @deffn Method pgg-scheme-decrypt-region scheme start end
281 Decrypt the current region between @var{start} and @var{end}. If
282 decryption is successful, it returns @code{t}, otherwise @code{nil}.
285 @deffn Method pgg-scheme-sign-region scheme start end &optional cleartext
286 Make the signature from text between @var{start} and @var{end}. If the
287 optional third argument @var{cleartext} is non-@code{nil}, it does not
288 create a detached signature. If signing is successful, it returns
289 @code{t}, otherwise @code{nil}.
292 @deffn Method pgg-scheme-verify-region scheme start end &optional signature
293 Verify the current region between @var{start} and @var{end}. If the
294 optional third argument @var{signature} is non-@code{nil}, it is treated
295 as the detached signature of the current region. If the signature is
296 successflly verified, it returns @code{t}, otherwise @code{nil}.
299 @deffn Method pgg-scheme-insert-key scheme
300 Retrieve the user's public key and insert it as ASCII-armored format.
301 On success, it returns @code{t}, otherwise @code{nil}.
304 @deffn Method pgg-scheme-snarf-keys-region scheme start end
305 Collect public keys in the current region between @var{start} and
306 @var{end}, and add them into the user's keyring.
307 On success, it returns @code{t}, otherwise @code{nil}.
311 @section Getting output
313 The output of the backend methods (@ref{Backend methods}) is stored in
314 special buffers, so that these methods must tell the status of the
317 @defvar pgg-errors-buffer
318 The standard error output of the execution of the PGP command is stored
322 @defvar pgg-output-buffer
323 The standard output of the execution of the PGP command is stored here.
326 @defvar pgg-status-buffer
327 The rest of status information of the execution of the PGP command is
331 @node Registering backend
332 @section Registering backend
334 When decrypting and verifying PGG searches the registered scheme for an
335 implementation from @var{pgg-verify-condition} and
336 @var{pgg-decrypt-condition}. These variable hold capability information
337 of backend implementations.
339 The @code{gpg} backend, for example, is registered as below:
342 (ctree-set-calist-strictly
343 'pgg-verify-condition
344 '((signature-version 3 4)
345 (public-key-algorithm ELG-E DSA ELG)
346 (hash-algorithm MD5 SHA1 RIPEMD160)
349 (ctree-set-calist-strictly
350 'pgg-decrypt-condition
351 '((public-key-algorithm ELG-E DSA ELG)
352 (symmetric-key-algorithm 3DES CAST5 BLOWFISH TWOFISH)
356 The former expression says:
360 the backend @code{gpg} supports version 3 and 4 of the signature format
362 the backend @code{gpg} supports ELG-E, DSA, and ELG as public-key
363 algorithm for signing
365 the backend @code{gpg} supports MD5, SHA1, and RIPEMD160 as hash
366 algorithm for signing
369 And the latter expression says:
373 the backend @code{gpg} supports ELG-E, DSA, and ELG as public-key
374 algorithm for decrypting
376 the backend @code{gpg} supports 3DES, CAST5, BLOWFISH, and TWOFISH as
377 cipher algorithm for decrypting.
380 @node Parsing OpenPGP packets
381 @chapter Parsing OpenPGP packets
383 The format of OpenPGP messages is maintained in order to publish all
384 necessary information needed to develop interoperable applications.
385 The standard is documented in RFC 2440.
387 PGG has its own parser for the OpenPGP packets.
389 @defun pgg-parse-armor string
390 List the sequence of packets in @var{string}.
393 @defun pgg-parse-armor-region start end
394 List the sequence of packets in the current region between @var{start}
398 @defvar pgg-ignore-packet-checksum
399 If non-@code{nil}, don't check the checksum of the packets.
403 @chapter Function Index
407 @chapter Variable Index