/[emacs]/emacs/man/pgg.texi
ViewVC logotype

Diff of /emacs/man/pgg.texi

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.1 by rsteib, Mon Aug 2 13:28:45 2004 UTC revision 1.2 by miles, Sat Sep 4 13:13:44 2004 UTC
# Line 0  Line 1 
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

Legend:
Removed from v.1.1  
changed lines
  Added in v.1.2

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26