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) 2001 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{} 2001 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::               Complicated stuff you may have to do.
  57 * How to use::                  Getting started quickly.
  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 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/}.
  86
  87 @node How to use
  88 @chapter How to use
  89
  90 The toplevel interface of this library is quite simple, and only
  91 intended to use with public-key cryptographic operation.
  92
  93 To use PGG, evaluate following expression at the beginning of your
  94 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 setting for desired functions 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 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.
 133
 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.
 138
 139 If encryption is successful, it replaces the current region contents (in
 140 the accessible portion) with the resulting data.
 141 @end deffn
 142
 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.
 147 @end deffn
 148
 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.
 155 @end deffn
 156
 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
 161 current region.
 162
 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.
 166 @end deffn
 167
 168 @deffn Command pgg-insert-key
 169 Retrieve the user's public key and insert it as ASCII-armored format.
 170 @end deffn
 171
 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.
 175 @end deffn
 176
 177 @node Selecting an implementation
 178 @section Selecting an implementation
 179
 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.
 185
 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
 192 verifying.
 193
 194 @defvar pgg-scheme
 195 Force specify the scheme of PGP implementation for decrypting and verifying.
 196 The value can be @code{gpg}, @code{pgp}, and @code{pgp5}.
 197 @end defvar
 198
 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}.
 202 @end defvar
 203
 204 @node Caching passphrase
 205 @section Caching passphrase
 206
 207 PGG provides a simple passphrase caching mechanism.  If you want to
 208 arrange the interaction, set the variable @var{pgg-read-passphrase}.
 209
 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}.
 214 @end defvar
 215
 216 @defvar pgg-passphrase-cache-expiry
 217 Elapsed time for expiration in seconds.
 218 @end defvar
 219
 220 @node Architecture
 221 @chapter Architecture
 222
 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.
 226
 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.
 231
 232 @menu
 233 * Initializing::
 234 * Backend methods::
 235 * Getting output::
 236 * Registering backend::
 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 Registering backend
 332 @section Registering backend
 333
 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.
 338
 339 The @code{gpg} backend, for example, is registered as below:
 340
 341 @lisp
 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)
 347    (scheme . gpg)))
 348
 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)
 353    (scheme . gpg)))
 354 @end lisp
 355
 356 The former expression says:
 357
 358 @itemize
 359 @item
 360 the backend @code{gpg} supports version 3 and 4 of the signature format
 361 @item
 362 the backend @code{gpg} supports ELG-E, DSA, and ELG as public-key
 363 algorithm for signing
 364 @item
 365 the backend @code{gpg} supports MD5, SHA1, and RIPEMD160 as hash
 366 algorithm for signing
 367 @end itemize
 368
 369 And the latter expression says:
 370
 371 @itemize
 372 @item
 373 the backend @code{gpg} supports ELG-E, DSA, and ELG as public-key
 374 algorithm for decrypting
 375 @item
 376 the backend @code{gpg} supports 3DES, CAST5, BLOWFISH, and TWOFISH as
 377 cipher algorithm for decrypting.
 378 @end itemize
 379
 380 @node Parsing OpenPGP packets
 381 @chapter Parsing OpenPGP packets
 382
 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.
 386
 387 PGG has its own parser for the OpenPGP packets.
 388
 389 @defun pgg-parse-armor string
 390 List the sequence of packets in @var{string}.
 391 @end defun
 392
 393 @defun pgg-parse-armor-region start end
 394 List the sequence of packets in the current region between @var{start}
 395 and @var{end}.
 396 @end defun
 397
 398 @defvar pgg-ignore-packet-checksum
 399 If non-@code{nil}, don't check the checksum of the packets.
 400 @end defvar
 401
 402 @node Function Index
 403 @chapter Function Index
 404 @printindex fn
 405
 406 @node Variable Index
 407 @chapter Variable Index
 408 @printindex vr
 409
 410 @summarycontents
 411 @contents
 412 @bye
 413
 414 @c End: