pgg-ja.texi

   1 \input texinfo                  @c -*-texinfo-*-
   2
   3 @setfilename pgg-ja
   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
  22 \e$B$3$NJ8=q$r!"%U%j!<%=%U%H%&%'%":bCDH/9T$N\e(B GNU \e$B%U%j!<J8=qMxMQ5vBz7@Ls=q\e(B
  23 \e$BBh\e(B 1.1 \e$BHG$^$?$O$=$l0J9_$NHG$,Dj$a$k>r7o$N2<$GJ#@=!"G[I[!"$"$k$$$OJQ99$9\e(B
  24 \e$B$k$3$H$r5v2D$7$^$9!#JQ99IT2DItJ,!"I=I=;f%F%-%9%H$*$h$SN"I=;f%F%-%9%H$O;X\e(B
  25 \e$BDj$7$^$;$s!#$3$NMxMQ5vBz7@Ls=q$NJ#<L$O!V\e(BGNU \e$B%U%j!<J8=qMxMQ5vBz7@Ls=q!W$H\e(B
  26 \e$B$$$&>O$K4^$^$l$F$$$^$9!#\e(B
  27 @end quotation
  28 @end copying
  29
  30 @dircategory Emacs
  31 @direntry
  32 * PGG: (pgg-ja).                Emacs interface to various PGP implementations.
  33 @end direntry
  34
  35 @settitle PGG @value{VERSION}
  36
  37
  38 @titlepage
  39 @title PGG
  40
  41 @author by Daiki Ueno
  42 @page
  43
  44 @vskip 0pt plus 1filll
  45 @insertcopying
  46 @end titlepage
  47 @page
  48
  49 @node Top
  50 @top PGG
  51 \e$B$3$l$O\e(B PGG \e$B$N%^%K%e%"%k$G$9!#\e(BPGG \e$B$O!"0BA4$JDL?.$N$?$a$NMM!9$J%D!<%k$H\e(B
  52 Emacs \e$B$NCg$r<h$j;}$D%$%s%?%U%'!<%9$G$9!#$^$?!"\e(BPGG \e$B$O!"\e(BMIME \e$B%a%C%;!<%8\e(B
  53 \e$B$N0E9f2=!"I|9f2=!"=pL>!"8!>Z$N$?$a$NC1=c$J%f!<%6%$%s%?%U%'!<%9$bDs6!$7$^\e(B
  54 \e$B$9!#\e(B
  55
  56 @menu
  57 * Overview::                    PGG \e$B$H$O\e(B
  58 * Prerequisites::               \e$B$"$i$+$8$a$7$F$*$/$Y$-J#;($J;vJA\e(B
  59 * How to use::                  \e$B$H$C$H$H;H$$;O$a$h$&\e(B
  60 * Architecture::
  61 * Parsing OpenPGP packets::
  62 * Function Index::
  63 * Variable Index::
  64 @end menu
  65
  66 @node Overview
  67 @chapter Overview
  68
  69 PGG \e$B$O!"0BA4$JDL?.$N$?$a$NMM!9$J%D!<%k$H\e(B Emacs \e$B$NCg$r<h$j;}$D%$%s%?%U%'!<\e(B
  70 \e$B%9$G$9!#F1MM$N5!G=$O\e(B Mailcrypt \e$B$b;}$C$F$$$^$9$,!"\e(BMailcrypt \e$B$O\e(B PGP/MIME
  71 \e$B$N%$%s%U%i$GDL>oMQ$$$i$l$kJ,N%$5$l$?\e(B PGP \e$B%a%C%;!<%8$r<h$j07$&$3$H$,$G$-\e(B
  72 \e$B$^$;$s!#$3$l$,!";d\e(B(\e$B:n<T\e(B)\e$B$,?7$7$$%i%$%V%i%j$r=q$$$?<g$JM}M3$G$9!#\e(B
  73
  74 PGP/MIME \e$B$O\e(B MIME Object Security Services (RFC1848) \e$B$N<BAu$G$9!#$=$NI8=`\e(B
  75 \e$B$O\e(B RFC2015 \e$B$G5-=R$5$l$F$$$^$9!#\e(B
  76
  77 @node Prerequisites
  78 @chapter Prerequisites
  79
  80 PGG \e$B$r;H$&$?$a$K$O>/$J$/$H$b\e(B1\e$B$D$N%W%i%$%P%7!<J]8n%7%9%F%`$N<BAu$,I,MW$G\e(B
  81 \e$B$9!#$3$N%^%K%e%"%k$G$O!"$"$J$?$,$=$N$h$&$J%W%m%0%i%`$r$9$G$K<hF@!"%$%s%9\e(B
  82 \e$B%H!<%k$7$F$$$F!"4pK\E*$J;H$$J}$rCN$C$F$$$k$3$H$r2>Dj$7$^$9!#\e(B
  83
  84 \e$B%G%#%U%)%k%H$G$O!"\e(BPGG \e$B$O\e(B GnuPG \e$B$r;H$$$^$9!#$7$+$7!"\e(BPGP (Pretty Good
  85 Privacy) \e$B$N%P!<%8%g%s\e(B2\e$B$^$?$O\e(B5\e$B$b%5%]!<%H$7$^$9!#$b$7!"$"$J$?$,$3$N$h$&$J\e(B
  86 \e$B%7%9%F%`$K47$l$F$$$J$$$N$G$"$l$P!"\e(BGNU Privacy Handbook (GPH) \e$B$r@h$KFI$^\e(B
  87 \e$B$l$k$3$H$r$*A&$a$7$^$9!#\e(BGPH \e$B$O!"\e(B@uref{http://www.gnupg.org/gph/} \e$B$G8+$k\e(B
  88 \e$B$3$H$,$G$-$^$9!#\e(B
  89
  90 @node How to use
  91 @chapter How to use
  92
  93 \e$B$3$N%i%$%V%i%j$N:G>e0L%$%s%?%U%'!<%9$O$H$F$bC1=c$G!"8x3+80$K$h$k0E9f$NA`\e(B
  94 \e$B:n$N$_$rA[Dj$7$F$$$^$9!#\e(B
  95
  96 PGG \e$B$r;H$&$?$a$K$O!"$"$J$?$N%"%W%j%1!<%7%g%s%W%m%0%i%`$NKAF,$G<!$N\e(B S \e$B<0\e(B
  97 \e$B$rI>2A$7$^$9!#\e(B
  98
  99 @lisp
 100 (require 'pgg)
 101 @end lisp
 102
 103 \e$B$"$J$?$,\e(B pgg.el \e$B$NB8:_$r3NG'$7$?$$$J$i!">e5-$NJ}K!$G$O$J$/0J2<$N$h$&$K!"\e(B
 104 \e$BI,MW$J5!G=$K$D$$$F\e(B autoload \e$B$N%j%9%H$r@_Dj$9$k$3$H$b$G$-$^$9!#\e(B
 105
 106 @lisp
 107 (autoload 'pgg-encrypt-region "pgg"
 108   "Encrypt the current region." t)
 109 (autoload 'pgg-decrypt-region "pgg"
 110   "Decrypt the current region." t)
 111 (autoload 'pgg-sign-region "pgg"
 112   "Sign the current region." t)
 113 (autoload 'pgg-verify-region "pgg"
 114   "Verify the current region." t)
 115 (autoload 'pgg-insert-key "pgg"
 116   "Insert the ASCII armored public key." t)
 117 (autoload 'pgg-snarf-keys-region "pgg"
 118   "Import public keys in the current region." t)
 119 @end lisp
 120
 121 @menu
 122 * User Commands::
 123 * Selecting an implementation::
 124 * Caching passphrase::
 125 * Default user identity::
 126 @end menu
 127
 128 @node User Commands
 129 @section User Commands
 130
 131 \e$B$3$N;~E@$G!"$"$J$?$O$$$/$D$+$N0E9f$K4X$9$k%3%^%s%I$r;H$&$3$H$,$G$-$^$9!#\e(B
 132 \e$B$3$l$i$N%3%^%s%I$N5sF0$O5/F0J}K!$K0MB8$7$^$9!#$3$l$i$N%3%^%s%I$O%i%$%V%i\e(B
 133 \e$B%j4X?t$H$7$FMxMQ$5$l$k$3$H$b$"$k$+$i$G$9!#Nc$($P!"$"$J$?$,$"$k=pL><T$N8x\e(B
 134 \e$B3+80$r;}$C$F$$$J$$$H$-!"\e(B@code{pgg-verify-region} \e$B$H$$$&4X?t$OB(:B$K<:GT\e(B
 135 \e$B$7$^$9$,!"$3$l$,BPOCE*$K8F$S=P$5$l$?>l9g$K$O!"%5!<%P$+$i8x3+80$r%@%&%s%m!<\e(B
 136 \e$B%I$9$k$+$I$&$+!"$"$J$?$K3NG'$7$^$9!#\e(B
 137
 138 @deffn Command pgg-encrypt-region start end recipients &optional sign
 139 @var{recipients}\e$B08$N%a%C%;!<%8$K$D$$$F!"\e(B@var{start}\e$B$H\e(B@var{end}\e$B$N4V$G;XDj\e(B
 140 \e$B$5$l$?8=:_$NHO0O$r0E9f2=$7$^$9!#BPOCE*$K8F$P$l$k$H!"<u?.<T$rJ9$+$l$^$9!#\e(B
 141
 142 \e$B0E9f2=$K@.8y$9$k$H!"8=:_$NHO0O$NFbMF$,\e(B(\e$B2DG=$JItJ,$K$D$$$F\e(B)\e$B0E9f2=$5$l$?Fb\e(B
 143 \e$BMF$KCV$-49$($i$l$^$9!#\e(B
 144
 145 \e$B%*%W%7%g%s0z?t\e(B @var{sign} \e$B$,\e(B non-@code{nil} \e$B$J$i$P!"=pL>$H0E9f2=$,F1;~$K\e(B
 146 \e$B9T$o$l$^$9!#8=:_!"$3$N5!G=$O\e(B GnuPG \e$B$G$@$1F0:n$7$^$9!#\e(B
 147 @end deffn
 148
 149 @deffn Command pgg-decrypt-region start end
 150 @var{start}\e$B$H\e(B@var{end}\e$B$N4V$G;XDj$5$l$?8=:_$NHO0O$rI|9f2=$7$^$9!#I|9f2=$K\e(B
 151 \e$B@.8y$9$k$H!"8=:_$NHO0O$NFbMF$,\e(B(\e$B2DG=$JItJ,$K$D$$$F\e(B)\e$BI|9f2=$5$l$?FbMF$KCV$-\e(B
 152 \e$B49$($i$l$^$9!#\e(B
 153 @end deffn
 154
 155 @deffn Command pgg-sign-region start end &optional cleartext
 156 @var{start}\e$B$H\e(B@var{end}\e$B$N4V$N%F%-%9%H$K=pL>$7$^$9!#\e(B3\e$BHVL\$N%*%W%7%g%s0z?t\e(B
 157 @var{cleartext} \e$B$,\e(B non-@code{nil} \e$B$G$"$k$+!"$"$k$$$OBPOCE*$K8F$P$l$?>l9g!"\e(B
 158 \e$BJ,N%$5$l$?=pL>$O:n$i$l$^$;$s!#$=$N$h$&$J>l9g!"8=:_$NHO0O$NFbMF$,\e(B(\e$B2DG=$J\e(B
 159 \e$BItJ,$K$D$$$F\e(B)\e$B=pL>$5$l$?7k2L$KCV$-49$($i$l$^$9!#\e(B
 160 @end deffn
 161
 162 @deffn Command pgg-verify-region start end &optional signature fetch
 163 @var{start}\e$B$H\e(B@var{end}\e$B$N4V$NHO0O$r8!::$7$^$9!#\e(B3\e$BHVL\$N%*%W%7%g%s0z?t\e(B
 164 @var{signature} \e$B$,\e(B non-@code{nil} \e$B$G$"$k$+!"$"$k$$$OBPOCE*$K8F$P$l$?>l9g!"\e(B
 165 \e$BJ,N%$5$l$?=pL>$H$7$F<h$j07$o$l$^$9!#\e(B
 166
 167 4\e$BHVL\$N%*%W%7%g%s0z?t\e(B @var{fetch} \e$B$,\e(B non-@code{nil} \e$B$G$"$k$+!"$"$k$$$OBP\e(B
 168 \e$BOCE*$K8F$P$l$?>l9g!"8x3+80$r%5!<%P$+$i<hF@$7$^$9!#\e(B
 169 @end deffn
 170
 171 @deffn Command pgg-insert-key
 172 \e$B%f!<%6$N8x3+80$r<hF@$7$F!"\e(BASCII-armored \e$B%U%)!<%^%C%H$GA^F~$7$^$9!#\e(B
 173 @end deffn
 174
 175 @deffn Command pgg-snarf-keys-region start end
 176 @var{start}\e$B$H\e(B@var{end}\e$B$N4V$NHO0O$K$"$k8x3+80$r=8$a!"%f!<%6$N80NX\e(B
 177 (keyring)\e$B$KDI2C$7$^$9!#\e(B
 178 @end deffn
 179
 180 @node Selecting an implementation
 181 @section Selecting an implementation
 182
 183 Since PGP has a long history and there are a number of PGP
 184 implementations available today, the function which each one has differs
 185 considerably.  For example, if you are using GnuPG, you know you can
 186 select cipher algorithm from 3DES, CAST5, BLOWFISH, and so on, but on
 187 the other hand the version 2 of PGP only supports IDEA.
 188
 189 By default, if the variable @code{pgg-scheme} is not set, PGG searches the
 190 registered scheme for an implementation of the requested service
 191 associated with the named algorithm.  If there are no match, PGG uses
 192 @code{pgg-default-scheme}.  In other words, there are two options to
 193 control which command is used to process the incoming PGP armors.  One
 194 is for encrypting and signing, the other is for decrypting and
 195 verifying.
 196
 197 @defvar pgg-scheme
 198 Force specify the scheme of PGP implementation for decrypting and verifying.
 199 The value can be @code{gpg}, @code{pgp}, and @code{pgp5}.
 200 @end defvar
 201
 202 @defvar pgg-default-scheme
 203 Force specify the scheme of PGP implementation for encrypting and signing.
 204 The value can be @code{gpg}, @code{pgp}, and @code{pgp5}.
 205 @end defvar
 206
 207 @node Caching passphrase
 208 @section Caching passphrase
 209
 210 PGG uses a simple passphrase caching mechanism, which is enabled by
 211 default.
 212
 213 @defvar pgg-cache-passphrase
 214 If non-@code{nil}, store passphrases.  The default value of this
 215 variable is @code{t}.  If you were worry about security issue, however,
 216 you could stop caching with setting it @code{nil}.
 217 @end defvar
 218
 219 @defvar pgg-passphrase-cache-expiry
 220 Elapsed time for expiration in seconds.
 221 @end defvar
 222
 223 @node Default user identity
 224 @section Default user identity
 225
 226 The PGP implementation is usually able to select the proper key to use
 227 for signing and decryption, but if you have more than one key, you may
 228 need to specify the key id to use.
 229
 230 @defvar pgg-default-user-id
 231 User ID of your default identity.  It defaults to the value returned
 232 by @samp{(user-login-name)}.  You can customize this variable.
 233 @end defvar
 234
 235 @defvar pgg-gpg-user-id
 236 User ID of the GnuPG default identity.  It defaults to @samp{nil}.
 237 This overrides @samp{pgg-default-user-id}.  You can customize this
 238 variable.
 239 @end defvar
 240
 241 @defvar pgg-pgp-user-id
 242 User ID of the PGP 2.x/6.x default identity.  It defaults to
 243 @samp{nil}.  This overrides @samp{pgg-default-user-id}.  You can
 244 customize this variable.
 245 @end defvar
 246
 247 @defvar pgg-pgp5-user-id
 248 User ID of the PGP 5.x default identity.  It defaults to @samp{nil}.
 249 This overrides @samp{pgg-default-user-id}.  You can customize this
 250 variable.
 251 @end defvar
 252
 253 @node Architecture
 254 @chapter Architecture
 255
 256 PGG introduces the notion of a "scheme of PGP implementation" (used
 257 interchangeably with "scheme" in this document).  This term refers to a
 258 singleton object wrapped with the luna object system.
 259
 260 Since PGG was designed for accessing and developing PGP functionality,
 261 the architecture had to be designed not just for interoperability but
 262 also for extensiblity.  In this chapter we explore the architecture
 263 while finding out how to write the PGG back end.
 264
 265 @menu
 266 * Initializing::
 267 * Back end methods::
 268 * Getting output::
 269 @end menu
 270
 271 @node Initializing
 272 @section Initializing
 273
 274 A scheme must be initialized before it is used.
 275 It had better guarantee to keep only one instance of a scheme.
 276
 277 The following code is snipped out of @file{pgg-gpg.el}.  Once an
 278 instance of @code{pgg-gpg} scheme is initialized, it's stored to the
 279 variable @code{pgg-scheme-gpg-instance} and will be reused from now on.
 280
 281 @lisp
 282 (defvar pgg-scheme-gpg-instance nil)
 283
 284 (defun pgg-make-scheme-gpg ()
 285   (or pgg-scheme-gpg-instance
 286       (setq pgg-scheme-gpg-instance
 287             (luna-make-entity 'pgg-scheme-gpg))))
 288 @end lisp
 289
 290 The name of the function must follow the
 291 regulation---@code{pgg-make-scheme-} follows the back end name.
 292
 293 @node Back end methods
 294 @section Back end methods
 295
 296 In each back end, these methods must be present.  The output of these
 297 methods is stored in special buffers (@ref{Getting output}), so that
 298 these methods must tell the status of the execution.
 299
 300 @deffn Method pgg-scheme-lookup-key scheme string &optional type
 301 Return keys associated with @var{string}.  If the optional third
 302 argument @var{type} is non-@code{nil}, it searches from the secret
 303 keyrings.
 304 @end deffn
 305
 306 @deffn Method pgg-scheme-encrypt-region scheme start end recipients &optional sign
 307 Encrypt the current region between @var{start} and @var{end} for
 308 @var{recipients}.  If @var{sign} is non-@code{nil}, do a combined sign
 309 and encrypt.  If encryption is successful, it returns @code{t},
 310 otherwise @code{nil}.
 311 @end deffn
 312
 313 @deffn Method pgg-scheme-decrypt-region scheme start end
 314 Decrypt the current region between @var{start} and @var{end}.  If
 315 decryption is successful, it returns @code{t}, otherwise @code{nil}.
 316 @end deffn
 317
 318 @deffn Method pgg-scheme-sign-region scheme start end &optional cleartext
 319 Make the signature from text between @var{start} and @var{end}.  If the
 320 optional third argument @var{cleartext} is non-@code{nil}, it does not
 321 create a detached signature.  If signing is successful, it returns
 322 @code{t}, otherwise @code{nil}.
 323 @end deffn
 324
 325 @deffn Method pgg-scheme-verify-region scheme start end &optional signature
 326 Verify the current region between @var{start} and @var{end}.  If the
 327 optional third argument @var{signature} is non-@code{nil}, it is treated
 328 as the detached signature of the current region.  If the signature is
 329 successfully verified, it returns @code{t}, otherwise @code{nil}.
 330 @end deffn
 331
 332 @deffn Method pgg-scheme-insert-key scheme
 333 Retrieve the user's public key and insert it as ASCII-armored format.
 334 On success, it returns @code{t}, otherwise @code{nil}.
 335 @end deffn
 336
 337 @deffn Method pgg-scheme-snarf-keys-region scheme start end
 338 Collect public keys in the current region between @var{start} and
 339 @var{end}, and add them into the user's keyring.
 340 On success, it returns @code{t}, otherwise @code{nil}.
 341 @end deffn
 342
 343 @node Getting output
 344 @section Getting output
 345
 346 The output of the back end methods (@ref{Back end methods}) is stored in
 347 special buffers, so that these methods must tell the status of the
 348 execution.
 349
 350 @defvar pgg-errors-buffer
 351 The standard error output of the execution of the PGP command is stored
 352 here.
 353 @end defvar
 354
 355 @defvar pgg-output-buffer
 356 The standard output of the execution of the PGP command is stored here.
 357 @end defvar
 358
 359 @defvar pgg-status-buffer
 360 The rest of status information of the execution of the PGP command is
 361 stored here.
 362 @end defvar
 363
 364 @node Parsing OpenPGP packets
 365 @chapter Parsing OpenPGP packets
 366
 367 The format of OpenPGP messages is maintained in order to publish all
 368 necessary information needed to develop interoperable applications.
 369 The standard is documented in RFC 2440.
 370
 371 PGG has its own parser for the OpenPGP packets.
 372
 373 @defun pgg-parse-armor string
 374 List the sequence of packets in @var{string}.
 375 @end defun
 376
 377 @defun pgg-parse-armor-region start end
 378 List the sequence of packets in the current region between @var{start}
 379 and @var{end}.
 380 @end defun
 381
 382 @defvar pgg-ignore-packet-checksum
 383 If non-@code{nil}, don't check the checksum of the packets.
 384 @end defvar
 385
 386 @node Function Index
 387 @chapter Function Index
 388 @printindex fn
 389
 390 @node Variable Index
 391 @chapter Variable Index
 392 @printindex vr
 393
 394 @summarycontents
 395 @contents
 396 @bye
 397
 398 @c Local Variables:
 399 @c coding: iso-2022-7bit
 400 @c fill-column: 72
 401 @c mode: texinfo
 402 @c use-kuten-for-period: t
 403 @c use-touten-for-comma: t
 404 @c End: