man/pgg.texi

   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, 2004, 2005 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.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''.
  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-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)
 113 @end lisp
 114
 115 @menu
 116 * User Commands::
 117 * Selecting an implementation::
 118 * Caching passphrase::
 119 * Default user identity::
 120 @end menu
 121
 122 @node User Commands
 123 @section User Commands
 124
 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.
 131
 132 @deffn Command pgg-encrypt-region start end recipients &optional sign passphrase
 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.
 136
 137 If encryption is successful, it replaces the current region contents (in
 138 the accessible portion) with the resulting data.
 139
 140 If optional argument @var{sign} is non-@code{nil}, the function is
 141 request to do a combined sign and encrypt.  This currently is
 142 confirmed to work with GnuPG, but might not work with PGP or PGP5.
 143
 144 If optional @var{passphrase} is @code{nil}, the passphrase will be
 145 obtained from the passphrase cache or user.
 146 @end deffn
 147
 148 @deffn Command pgg-encrypt-symmetric-region &optional start end passphrase
 149 Encrypt the current region between @var{start} and @var{end} using a
 150 symmetric cipher.  After invocation you are asked for a passphrase.
 151
 152 If optional @var{passphrase} is @code{nil}, the passphrase will be
 153 obtained from the passphrase cache or user.
 154
 155 symmetric-cipher encryption is currently only implemented for GnuPG.
 156 @end deffn
 157
 158 @deffn Command pgg-decrypt-region start end &optional passphrase
 159 Decrypt the current region between @var{start} and @var{end}.  If
 160 decryption is successful, it replaces the current region contents (in
 161 the accessible portion) with the resulting data.
 162
 163 If optional @var{passphrase} is @code{nil}, the passphrase will be
 164 obtained from the passphrase cache or user.
 165 @end deffn
 166
 167 @deffn Command pgg-sign-region start end &optional cleartext passphrase
 168 Make the signature from text between @var{start} and @var{end}.  If the
 169 optional third argument @var{cleartext} is non-@code{nil}, or the
 170 function is called interactively, it does not create a detached
 171 signature.  In such a case, it replaces the current region contents (in
 172 the accessible portion) with the resulting data.
 173
 174 If optional @var{passphrase} is @code{nil}, the passphrase will be
 175 obtained from the passphrase cache or user.
 176 @end deffn
 177
 178 @deffn Command pgg-verify-region start end &optional signature fetch
 179 Verify the current region between @var{start} and @var{end}.  If the
 180 optional third argument @var{signature} is non-@code{nil}, or the function
 181 is called interactively, it is treated as the detached signature of the
 182 current region.
 183
 184 If the optional 4th argument @var{fetch} is non-@code{nil}, or the
 185 function is called interactively, we attempt to fetch the signer's
 186 public key from the key server.
 187 @end deffn
 188
 189 @deffn Command pgg-insert-key
 190 Retrieve the user's public key and insert it as ASCII-armored format.
 191 @end deffn
 192
 193 @deffn Command pgg-snarf-keys-region start end
 194 Collect public keys in the current region between @var{start} and
 195 @var{end}, and add them into the user's keyring.
 196 @end deffn
 197
 198 @node Selecting an implementation
 199 @section Selecting an implementation
 200
 201 Since PGP has a long history and there are a number of PGP
 202 implementations available today, the function which each one has differs
 203 considerably.  For example, if you are using GnuPG, you know you can
 204 select cipher algorithm from 3DES, CAST5, BLOWFISH, and so on, but on
 205 the other hand the version 2 of PGP only supports IDEA.
 206
 207 By default, if the variable @code{pgg-scheme} is not set, PGG searches the
 208 registered scheme for an implementation of the requested service
 209 associated with the named algorithm.  If there are no match, PGG uses
 210 @code{pgg-default-scheme}.  In other words, there are two options to
 211 control which command is used to process the incoming PGP armors.  One
 212 is for encrypting and signing, the other is for decrypting and
 213 verifying.
 214
 215 @defvar pgg-scheme
 216 Force specify the scheme of PGP implementation for decrypting and verifying.
 217 The value can be @code{gpg}, @code{pgp}, and @code{pgp5}.
 218 @end defvar
 219
 220 @defvar pgg-default-scheme
 221 Force specify the scheme of PGP implementation for encrypting and signing.
 222 The value can be @code{gpg}, @code{pgp}, and @code{pgp5}.
 223 @end defvar
 224
 225 @node Caching passphrase
 226 @section Caching passphrase
 227
 228 PGG provides a simple passphrase caching mechanism.  If you want to
 229 arrange the interaction, set the variable @code{pgg-read-passphrase}.
 230
 231 @defvar pgg-cache-passphrase
 232 If non-@code{nil}, store passphrases.  The default value of this
 233 variable is @code{t}.  If you were worry about security issue, however,
 234 you could stop caching with setting it @code{nil}.
 235 @end defvar
 236
 237 @defvar pgg-passphrase-cache-expiry
 238 Elapsed time for expiration in seconds.
 239 @end defvar
 240
 241 @node Default user identity
 242 @section Default user identity
 243
 244 The PGP implementation is usually able to select the proper key to use
 245 for signing and decryption, but if you have more than one key, you may
 246 need to specify the key id to use.
 247
 248 @defvar pgg-default-user-id
 249 User ID of your default identity.  It defaults to the value returned
 250 by @samp{(user-login-name)}.  You can customize this variable.
 251 @end defvar
 252
 253 @defvar pgg-gpg-user-id
 254 User ID of the GnuPG default identity.  It defaults to @samp{nil}.
 255 This overrides @samp{pgg-default-user-id}.  You can customize this
 256 variable.
 257 @end defvar
 258
 259 @defvar pgg-pgp-user-id
 260 User ID of the PGP 2.x/6.x default identity.  It defaults to
 261 @samp{nil}.  This overrides @samp{pgg-default-user-id}.  You can
 262 customize this variable.
 263 @end defvar
 264
 265 @defvar pgg-pgp5-user-id
 266 User ID of the PGP 5.x default identity.  It defaults to @samp{nil}.
 267 This overrides @samp{pgg-default-user-id}.  You can customize this
 268 variable.
 269 @end defvar
 270
 271 @node Architecture
 272 @chapter Architecture
 273
 274 PGG introduces the notion of a "scheme of PGP implementation" (used
 275 interchangeably with "scheme" in this document).  This term refers to a
 276 singleton object wrapped with the luna object system.
 277
 278 Since PGG was designed for accessing and developing PGP functionality,
 279 the architecture had to be designed not just for interoperability but
 280 also for extensiblity.  In this chapter we explore the architecture
 281 while finding out how to write the PGG backend.
 282
 283 @menu
 284 * Initializing::
 285 * Backend methods::
 286 * Getting output::
 287 @end menu
 288
 289 @node Initializing
 290 @section Initializing
 291
 292 A scheme must be initialized before it is used.
 293 It had better guarantee to keep only one instance of a scheme.
 294
 295 The following code is snipped out of @file{pgg-gpg.el}.  Once an
 296 instance of @code{pgg-gpg} scheme is initialized, it's stored to the
 297 variable @code{pgg-scheme-gpg-instance} and will be reused from now on.
 298
 299 @lisp
 300 (defvar pgg-scheme-gpg-instance nil)
 301
 302 (defun pgg-make-scheme-gpg ()
 303   (or pgg-scheme-gpg-instance
 304       (setq pgg-scheme-gpg-instance
 305             (luna-make-entity 'pgg-scheme-gpg))))
 306 @end lisp
 307
 308 The name of the function must follow the
 309 regulation---@code{pgg-make-scheme-} follows the backend name.
 310
 311 @node Backend methods
 312 @section Backend methods
 313
 314 In each backend, these methods must be present.  The output of these
 315 methods is stored in special buffers (@ref{Getting output}), so that
 316 these methods must tell the status of the execution.
 317
 318 @deffn Method pgg-scheme-lookup-key scheme string &optional type
 319 Return keys associated with @var{string}.  If the optional third
 320 argument @var{type} is non-@code{nil}, it searches from the secret
 321 keyrings.
 322 @end deffn
 323
 324 @deffn Method pgg-scheme-encrypt-region scheme start end recipients &optional sign passphrase
 325 Encrypt the current region between @var{start} and @var{end} for
 326 @var{recipients}.  If @var{sign} is non-@code{nil}, do a combined sign
 327 and encrypt.  If encryption is successful, it returns @code{t},
 328 otherwise @code{nil}.
 329 @end deffn
 330
 331 @deffn Method pgg-scheme-encrypt-symmetric-region scheme start end &optional passphrase
 332 Encrypt the current region between @var{start} and @var{end} using a
 333 symmetric cipher and a passphrases.  If encryption is successful, it
 334 returns @code{t}, otherwise @code{nil}.  This function is currently only
 335 implemented for GnuPG.
 336 @end deffn
 337
 338 @deffn Method pgg-scheme-decrypt-region scheme start end &optional passphrase
 339 Decrypt the current region between @var{start} and @var{end}.  If
 340 decryption is successful, it returns @code{t}, otherwise @code{nil}.
 341 @end deffn
 342
 343 @deffn Method pgg-scheme-sign-region scheme start end &optional cleartext passphrase
 344 Make the signature from text between @var{start} and @var{end}.  If the
 345 optional third argument @var{cleartext} is non-@code{nil}, it does not
 346 create a detached signature.  If signing is successful, it returns
 347 @code{t}, otherwise @code{nil}.
 348 @end deffn
 349
 350 @deffn Method pgg-scheme-verify-region scheme start end &optional signature
 351 Verify the current region between @var{start} and @var{end}.  If the
 352 optional third argument @var{signature} is non-@code{nil}, it is treated
 353 as the detached signature of the current region.  If the signature is
 354 successfully verified, it returns @code{t}, otherwise @code{nil}.
 355 @end deffn
 356
 357 @deffn Method pgg-scheme-insert-key scheme
 358 Retrieve the user's public key and insert it as ASCII-armored format.
 359 On success, it returns @code{t}, otherwise @code{nil}.
 360 @end deffn
 361
 362 @deffn Method pgg-scheme-snarf-keys-region scheme start end
 363 Collect public keys in the current region between @var{start} and
 364 @var{end}, and add them into the user's keyring.
 365 On success, it returns @code{t}, otherwise @code{nil}.
 366 @end deffn
 367
 368 @node Getting output
 369 @section Getting output
 370
 371 The output of the backend methods (@ref{Backend methods}) is stored in
 372 special buffers, so that these methods must tell the status of the
 373 execution.
 374
 375 @defvar pgg-errors-buffer
 376 The standard error output of the execution of the PGP command is stored
 377 here.
 378 @end defvar
 379
 380 @defvar pgg-output-buffer
 381 The standard output of the execution of the PGP command is stored here.
 382 @end defvar
 383
 384 @defvar pgg-status-buffer
 385 The rest of status information of the execution of the PGP command is
 386 stored here.
 387 @end defvar
 388
 389 @node Parsing OpenPGP packets
 390 @chapter Parsing OpenPGP packets
 391
 392 The format of OpenPGP messages is maintained in order to publish all
 393 necessary information needed to develop interoperable applications.
 394 The standard is documented in RFC 2440.
 395
 396 PGG has its own parser for the OpenPGP packets.
 397
 398 @defun pgg-parse-armor string
 399 List the sequence of packets in @var{string}.
 400 @end defun
 401
 402 @defun pgg-parse-armor-region start end
 403 List the sequence of packets in the current region between @var{start}
 404 and @var{end}.
 405 @end defun
 406
 407 @defvar pgg-ignore-packet-checksum
 408 If non-@code{nil}, don't check the checksum of the packets.
 409 @end defvar
 410
 411 @node Function Index
 412 @chapter Function Index
 413 @printindex fn
 414
 415 @node Variable Index
 416 @chapter Variable Index
 417 @printindex vr
 418
 419 @summarycontents
 420 @contents
 421 @bye
 422
 423 @c End:
 424
 425 @ignore
 426    arch-tag: 0c205838-34b9-41a5-b9d7-49ae57ccac85
 427 @end ignore