1 \input texinfo @c -*-texinfo-*-
3 @setfilename ../info/pgg
9 This file describes the PGG.
11 Copyright (C) 2003, 2004, 2005 Free Software Foundation, Inc.
12 Copyright (C) 2001 Daiki Ueno.
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''.
26 * PGG: (pgg). Emacs interface to various PGP implementations.
29 @settitle PGG @value{VERSION}
38 @vskip 0pt plus 1filll
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.
50 * Overview:: What PGG is.
51 * Prerequisites:: Complicated stuff you may have to do.
52 * How to use:: Getting started quickly.
54 * Parsing OpenPGP packets::
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.
67 PGP/MIME is an application of MIME Object Security Services (RFC1848).
68 The standard is documented in RFC2015.
71 @chapter Prerequisites
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.
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/}.
85 The toplevel interface of this library is quite simple, and only
86 intended to use with public-key cryptographic operation.
88 To use PGG, evaluate following expression at the beginning of your
95 If you want to check existence of pgg.el at runtime, instead you can
96 list autoload setting for desired functions as follows.
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)
117 * Selecting an implementation::
118 * Caching passphrase::
119 * Default user identity::
123 @section User Commands
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.
132 @deffn Command pgg-encrypt-region start end recipients &optional sign
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.
137 If encryption is successful, it replaces the current region contents (in
138 the accessible portion) with the resulting data.
140 If optional argument @var{sign} is non-@code{nil}, the function is
141 request to do a combined sign and encrypt. This currently only work
145 @deffn Command pgg-encrypt-symmetric-region start end
146 Encrypt the current region between @var{start} and @var{end} using a
147 symmetric cipher. After invocation you are asked for a passphrase.
149 This is currently only implemented for GnuPG.
152 @deffn Command pgg-decrypt-region start end
153 Decrypt the current region between @var{start} and @var{end}. If
154 decryption is successful, it replaces the current region contents (in
155 the accessible portion) with the resulting data.
158 @deffn Command pgg-sign-region start end &optional cleartext
159 Make the signature from text between @var{start} and @var{end}. If the
160 optional third argument @var{cleartext} is non-@code{nil}, or the
161 function is called interactively, it does not create a detached
162 signature. In such a case, it replaces the current region contents (in
163 the accessible portion) with the resulting data.
166 @deffn Command pgg-verify-region start end &optional signature fetch
167 Verify the current region between @var{start} and @var{end}. If the
168 optional third argument @var{signature} is non-@code{nil}, or the function
169 is called interactively, it is treated as the detached signature of the
172 If the optional 4th argument @var{fetch} is non-@code{nil}, or the
173 function is called interactively, we attempt to fetch the signer's
174 public key from the key server.
177 @deffn Command pgg-insert-key
178 Retrieve the user's public key and insert it as ASCII-armored format.
181 @deffn Command pgg-snarf-keys-region start end
182 Collect public keys in the current region between @var{start} and
183 @var{end}, and add them into the user's keyring.
186 @node Selecting an implementation
187 @section Selecting an implementation
189 Since PGP has a long history and there are a number of PGP
190 implementations available today, the function which each one has differs
191 considerably. For example, if you are using GnuPG, you know you can
192 select cipher algorithm from 3DES, CAST5, BLOWFISH, and so on, but on
193 the other hand the version 2 of PGP only supports IDEA.
195 By default, if the variable @code{pgg-scheme} is not set, PGG searches the
196 registered scheme for an implementation of the requested service
197 associated with the named algorithm. If there are no match, PGG uses
198 @code{pgg-default-scheme}. In other words, there are two options to
199 control which command is used to process the incoming PGP armors. One
200 is for encrypting and signing, the other is for decrypting and
204 Force specify the scheme of PGP implementation for decrypting and verifying.
205 The value can be @code{gpg}, @code{pgp}, and @code{pgp5}.
208 @defvar pgg-default-scheme
209 Force specify the scheme of PGP implementation for encrypting and signing.
210 The value can be @code{gpg}, @code{pgp}, and @code{pgp5}.
213 @node Caching passphrase
214 @section Caching passphrase
216 PGG provides a simple passphrase caching mechanism. If you want to
217 arrange the interaction, set the variable @code{pgg-read-passphrase}.
219 @defvar pgg-cache-passphrase
220 If non-@code{nil}, store passphrases. The default value of this
221 variable is @code{t}. If you were worry about security issue, however,
222 you could stop caching with setting it @code{nil}.
225 @defvar pgg-passphrase-cache-expiry
226 Elapsed time for expiration in seconds.
229 @node Default user identity
230 @section Default user identity
232 The PGP implementation is usually able to select the proper key to use
233 for signing and decryption, but if you have more than one key, you may
234 need to specify the key id to use.
236 @defvar pgg-default-user-id
237 User ID of your default identity. It defaults to the value returned
238 by @samp{(user-login-name)}. You can customize this variable.
241 @defvar pgg-gpg-user-id
242 User ID of the GnuPG default identity. It defaults to @samp{nil}.
243 This overrides @samp{pgg-default-user-id}. You can customize this
247 @defvar pgg-pgp-user-id
248 User ID of the PGP 2.x/6.x default identity. It defaults to
249 @samp{nil}. This overrides @samp{pgg-default-user-id}. You can
250 customize this variable.
253 @defvar pgg-pgp5-user-id
254 User ID of the PGP 5.x default identity. It defaults to @samp{nil}.
255 This overrides @samp{pgg-default-user-id}. You can customize this
260 @chapter Architecture
262 PGG introduces the notion of a "scheme of PGP implementation" (used
263 interchangeably with "scheme" in this document). This term refers to a
264 singleton object wrapped with the luna object system.
266 Since PGG was designed for accessing and developing PGP functionality,
267 the architecture had to be designed not just for interoperability but
268 also for extensiblity. In this chapter we explore the architecture
269 while finding out how to write the PGG backend.
278 @section Initializing
280 A scheme must be initialized before it is used.
281 It had better guarantee to keep only one instance of a scheme.
283 The following code is snipped out of @file{pgg-gpg.el}. Once an
284 instance of @code{pgg-gpg} scheme is initialized, it's stored to the
285 variable @code{pgg-scheme-gpg-instance} and will be reused from now on.
288 (defvar pgg-scheme-gpg-instance nil)
290 (defun pgg-make-scheme-gpg ()
291 (or pgg-scheme-gpg-instance
292 (setq pgg-scheme-gpg-instance
293 (luna-make-entity 'pgg-scheme-gpg))))
296 The name of the function must follow the
297 regulation---@code{pgg-make-scheme-} follows the backend name.
299 @node Backend methods
300 @section Backend methods
302 In each backend, these methods must be present. The output of these
303 methods is stored in special buffers (@ref{Getting output}), so that
304 these methods must tell the status of the execution.
306 @deffn Method pgg-scheme-lookup-key scheme string &optional type
307 Return keys associated with @var{string}. If the optional third
308 argument @var{type} is non-@code{nil}, it searches from the secret
312 @deffn Method pgg-scheme-encrypt-region scheme start end recipients &optional sign
313 Encrypt the current region between @var{start} and @var{end} for
314 @var{recipients}. If @var{sign} is non-@code{nil}, do a combined sign
315 and encrypt. If encryption is successful, it returns @code{t},
316 otherwise @code{nil}.
319 @deffn Method pgg-scheme-encrypt-symmetric-region scheme start end
320 Encrypt the current region between @var{start} and @var{end} using a
321 symmetric cipher and a passphrases. If encryption is successful, it
322 returns @code{t}, otherwise @code{nil}. This function is currently only
323 implemented for GnuPG.
326 @deffn Method pgg-scheme-decrypt-region scheme start end
327 Decrypt the current region between @var{start} and @var{end}. If
328 decryption is successful, it returns @code{t}, otherwise @code{nil}.
331 @deffn Method pgg-scheme-sign-region scheme start end &optional cleartext
332 Make the signature from text between @var{start} and @var{end}. If the
333 optional third argument @var{cleartext} is non-@code{nil}, it does not
334 create a detached signature. If signing is successful, it returns
335 @code{t}, otherwise @code{nil}.
338 @deffn Method pgg-scheme-verify-region scheme start end &optional signature
339 Verify the current region between @var{start} and @var{end}. If the
340 optional third argument @var{signature} is non-@code{nil}, it is treated
341 as the detached signature of the current region. If the signature is
342 successfully verified, it returns @code{t}, otherwise @code{nil}.
345 @deffn Method pgg-scheme-insert-key scheme
346 Retrieve the user's public key and insert it as ASCII-armored format.
347 On success, it returns @code{t}, otherwise @code{nil}.
350 @deffn Method pgg-scheme-snarf-keys-region scheme start end
351 Collect public keys in the current region between @var{start} and
352 @var{end}, and add them into the user's keyring.
353 On success, it returns @code{t}, otherwise @code{nil}.
357 @section Getting output
359 The output of the backend methods (@ref{Backend methods}) is stored in
360 special buffers, so that these methods must tell the status of the
363 @defvar pgg-errors-buffer
364 The standard error output of the execution of the PGP command is stored
368 @defvar pgg-output-buffer
369 The standard output of the execution of the PGP command is stored here.
372 @defvar pgg-status-buffer
373 The rest of status information of the execution of the PGP command is
377 @node Parsing OpenPGP packets
378 @chapter Parsing OpenPGP packets
380 The format of OpenPGP messages is maintained in order to publish all
381 necessary information needed to develop interoperable applications.
382 The standard is documented in RFC 2440.
384 PGG has its own parser for the OpenPGP packets.
386 @defun pgg-parse-armor string
387 List the sequence of packets in @var{string}.
390 @defun pgg-parse-armor-region start end
391 List the sequence of packets in the current region between @var{start}
395 @defvar pgg-ignore-packet-checksum
396 If non-@code{nil}, don't check the checksum of the packets.
400 @chapter Function Index
404 @chapter Variable Index
414 arch-tag: 0c205838-34b9-41a5-b9d7-49ae57ccac85