pgg.texi

   1 \input texinfo                  @c -*-texinfo-*-
   2
   3 @setfilename pgg.info
   4
   5 @set VERSION 0.1
   6
   7 @direntry
   8 * PGG: (pgg).   Emacs interface to various PGP implementations.
   9 @end direntry
  10
  11 @settitle PGG @value{VERSION}
  12
  13 @ifinfo
  14 This file describes the PGG.
  15
  16 Copyright (C) 2000 Daiki Ueno.
  17
  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".
  24 @end ifinfo
  25
  26 @tex
  27
  28 @titlepage
  29 @title PGG
  30
  31 @author by Daiki Ueno
  32 @page
  33
  34 @vskip 0pt plus 1filll
  35 Copyright @copyright{} 2000 Daiki Ueno.
  36
  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".
  43 @end titlepage
  44 @page
  45
  46 @end tex
  47
  48 @node Top
  49 @top PGG
  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.
  53
  54 @menu
  55 * Overview::                    What PGG is.
  56 * Prerequisites::
  57 * How to use::                  Calling PGP from your applications.
  58 * Architecture::
  59 * Parsing OpenPGP packets::
  60 * Function Index::
  61 * Variable Index::
  62 @end menu
  63
  64 @node Overview
  65 @chapter Overview
  66
  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.
  71
  72 PGP/MIME is an application of MIME Object Security Services (RFC1848).
  73 The standard is documented in RFC2015.
  74
  75 @node Prerequisites
  76 @chapter Prerequisites
  77
  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.
  81
  82 By default, PGG assumes to use GnuPG, but Pretty Good Privacy version 2
  83 or version 5 are also supported.  If you are new to such a system, I
  84 recomend that you should look over the `GNU Privacy Handbook (GPH)',
  85 which is available at @uref{http://www.gnupg.org/gph/}.
  86
  87 @node How to use
  88 @chapter How to use
  89
  90 The toplevel interface of this library is still simple, and only
  91 intended to use with public-key cryptographic operation.
  92
  93 To use PGG, please evaluate following expression at the beginning of
  94 your application program.
  95
  96 @lisp
  97 (require 'pgg)
  98 @end lisp
  99
 100 If you want to check existence of pgg.el at runtime, instead you can
 101 list autoload settings for functions you want as follows.
 102
 103 @lisp
 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)
 116 @end lisp
 117
 118 @menu
 119 * User Commands::
 120 * Selecting an implementation::
 121 * Caching passphrase::
 122 @end menu
 123
 124 @node User Commands
 125 @section User Commands
 126
 127 At this time you can use various cryptographic commands.  The behavior
 128 of these commands relies on the fashion of invocation because these
 129 commands are also intended to be used as library functions.  For
 130 example, in case you don't have the signer's public key, the function
 131 `pgg-verify-region' fails immediately, but if the function had been
 132 called interactively, it would ask you to retrieve the signer's public
 133 key from the server.
 134
 135 @deffn Command pgg-encrypt-region start end recipients
 136 Encrypt the current region between @var{start} and @var{end} for
 137 @var{recipients}.  When the function were called interactively, you
 138 would be asked about the recipients.
 139
 140 If encryption is successful, it replaces the current region contents (in
 141 the accessible portion) with the resulting data.
 142 @end deffn
 143
 144 @deffn Command pgg-decrypt-region start end
 145 Decrypt the current region between @var{start} and @var{end}.  If
 146 decryption is successful, it replaces the current region contents (in
 147 the accessible portion) with the resulting data.
 148 @end deffn
 149
 150 @deffn Command pgg-sign-region start end &optional cleartext
 151 Make the signature from text between @var{start} and @var{end}.  If the
 152 optional third argument @var{cleartext} is non-@code{nil}, or the
 153 function is called interactively, it does not create a detached
 154 signature.  In such a case, it replaces the current region contents (in
 155 the accessible portion) with the resulting data.
 156 @end deffn
 157
 158 @deffn Command pgg-verify-region start end &optional signature fetch
 159 Verify the current region between @var{start} and @var{end}.  If the
 160 optional third argument @var{signature} is non-@code{nil}, or the function
 161 is called interactively, it is treated as the detached signature of the
 162 current region.
 163
 164 If the optional 4th argument @var{fetch} is non-@code{nil}, or the
 165 function is called interactively, we attempt to fetch the signer's
 166 public key from the key server.
 167 @end deffn
 168
 169 @deffn Command pgg-insert-key
 170 Retrieve the user's public key and insert it as ASCII-armored format.
 171 @end deffn
 172
 173 @deffn Command pgg-snarf-keys-region start end
 174 Collect public keys in the current region between @var{start} and
 175 @var{end}, and add them into the user's keyring.
 176 @end deffn
 177
 178 @node Selecting an implementation
 179 @section Selecting an implementation
 180
 181 Since PGP has a long history and there are a number of PGP
 182 implementations available today, the function which each one has differs
 183 considerably.  For example, if you are using GnuPG, you know you can
 184 select cipher algorithm from 3DES, CAST5, BLOWFISH, and so on, but on
 185 the other hand the version 2 of PGP only supports IDEA.
 186
 187 By default, if the variable @var{pgg-scheme} is not set, PGG searches the
 188 registered scheme for an implementation of the requested service
 189 associated with the named algorithm.  If there are no match, PGG uses
 190 @var{pgg-default-scheme}.  In other words, there are two options to
 191 controll which command is used to process the incoming PGP armors.  One
 192 is for encrypting and signing, the other is for decrypting and
 193 verifying.
 194
 195 @defvar pgg-scheme
 196 Force specify the scheme of PGP implementation for decrypting and verifying.
 197 The value can be @code{gpg}, @code{pgp}, and @code{pgp5}.
 198 @end defvar
 199
 200 @defvar pgg-default-scheme
 201 Force specify the scheme of PGP implementation for encrypting and signing.
 202 The value can be @code{gpg}, @code{pgp}, and @code{pgp5}.
 203 @end defvar
 204
 205 @node Caching passphrase
 206 @section Caching passphrase
 207
 208 PGG provides a simple passphrase caching mechanism.  If you want to
 209 arrange the interaction, set the variable @var{pgg-read-passphrase}.
 210
 211 @defvar pgg-cache-passphrase
 212 If non-@code{nil}, store passphrases.  The default value of this
 213 variable is @code{t}.  If you were worry about security issue, however,
 214 you could stop caching.
 215 @end defvar
 216
 217 @defvar pgg-passphrase-cache-expiry
 218 The elapsed time for expiration in seconds.
 219 @end defvar
 220
 221 @node Architecture
 222 @chapter Architecture
 223
 224 PGG introduces the notion of a "scheme of PGP implementation" (used
 225 interchangeably with "scheme" in this document).  This term refers to a
 226 singleton object wrapped with the luna object system.
 227
 228 Since PGG was designed for accessing and developing PGP functionality,
 229 the architecture had to be designed not just for interoperablity but
 230 also for extensiblity.  In this chapter we explore the architecture
 231 while finding out how to write the PGG backend.
 232
 233 @menu
 234 * Initializing::
 235 * Backend methods::
 236 * Getting output::
 237 @end menu
 238
 239 @node Initializing
 240 @section Initializing
 241
 242 A scheme must be initialized before it is used.
 243 It had better guarantee to keep only one instance of a scheme.
 244
 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.
 248
 249 @lisp
 250 (defvar pgg-scheme-gpg-instance nil)
 251
 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))))
 256 @end lisp
 257
 258 The name of the function must follow the
 259 regulation---@code{pgg-make-scheme-} follows the backend name.
 260
 261 @node Backend methods
 262 @section Backend methods
 263
 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.
 267
 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
 271 keyrings.
 272 @end deffn
 273
 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}.
 278 @end deffn
 279
 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}.
 283 @end deffn
 284
 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}.
 290 @end deffn
 291
 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}.
 297 @end deffn
 298
 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}.
 302 @end deffn
 303
 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}.
 308 @end deffn
 309
 310 @node Getting output
 311 @section Getting output
 312
 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
 315 execution.
 316
 317 @defvar pgg-errors-buffer
 318 The standard error output of the execution of the PGP command is stored
 319 here.
 320 @end defvar
 321
 322 @defvar pgg-output-buffer
 323 The standard output of the execution of the PGP command is stored here.
 324 @end defvar
 325
 326 @defvar pgg-status-buffer
 327 The rest of status information of the execution of the PGP command is
 328 stored here.
 329 @end defvar
 330
 331 @node Parsing OpenPGP packets
 332 @chapter Parsing OpenPGP packets
 333
 334 The format of OpenPGP messages is maintained in order to publish all
 335 necessary information needed to develop interoperable applications.
 336 The standard is documented in RFC 2440.
 337
 338 PGG has its own parser for the OpenPGP packets.
 339
 340 @defun pgg-parse-armor string
 341 List the sequence of packets in @var{string}.
 342 @end defun
 343
 344 @defun pgg-parse-armor-region start end
 345 List the sequence of packets in the current region between @var{start}
 346 and @var{end}.
 347 @end defun
 348
 349 @defvar pgg-ignore-packet-checksum
 350 If non-@code{nil}, don't check the checksum of the packets.
 351 @end defvar
 352
 353 @node Function Index
 354 @chapter Function Index
 355 @printindex fn
 356
 357 @node Variable Index
 358 @chapter Variable Index
 359 @printindex vr
 360
 361 @summarycontents
 362 @contents
 363 @bye
 364
 365 @c End: