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.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-@code{nil}, the function is
 139 request to do a combined sign and encrypt.  This currently only work
 140 with GnuPG.
 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 @code{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 @code{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 @code{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 Default user identity
 221 @section Default user identity
 222
 223 The PGP implementation is usually able to select the proper key to use
 224 for signing and decryption, but if you have more than one key, you may
 225 need to specify the key id to use.
 226
 227 @defvar pgg-default-user-id
 228 User ID of your default identity.  It defaults to the value returned
 229 by @samp{(user-login-name)}.  You can customize this variable.
 230 @end defvar
 231
 232 @defvar pgg-gpg-user-id
 233 User ID of the GnuPG default identity.  It defaults to @samp{nil}.
 234 This overrides @samp{pgg-default-user-id}.  You can customize this
 235 variable.
 236 @end defvar
 237
 238 @defvar pgg-pgp-user-id
 239 User ID of the PGP 2.x/6.x default identity.  It defaults to
 240 @samp{nil}.  This overrides @samp{pgg-default-user-id}.  You can
 241 customize this variable.
 242 @end defvar
 243
 244 @defvar pgg-pgp5-user-id
 245 User ID of the PGP 5.x default identity.  It defaults to @samp{nil}.
 246 This overrides @samp{pgg-default-user-id}.  You can customize this
 247 variable.
 248 @end defvar
 249
 250 @node Architecture
 251 @chapter Architecture
 252
 253 PGG introduces the notion of a "scheme of PGP implementation" (used
 254 interchangeably with "scheme" in this document).  This term refers to a
 255 singleton object wrapped with the luna object system.
 256
 257 Since PGG was designed for accessing and developing PGP functionality,
 258 the architecture had to be designed not just for interoperability but
 259 also for extensiblity.  In this chapter we explore the architecture
 260 while finding out how to write the PGG backend.
 261
 262 @menu
 263 * Initializing::
 264 * Backend methods::
 265 * Getting output::
 266 @end menu
 267
 268 @node Initializing
 269 @section Initializing
 270
 271 A scheme must be initialized before it is used.
 272 It had better guarantee to keep only one instance of a scheme.
 273
 274 The following code is snipped out of @file{pgg-gpg.el}.  Once an
 275 instance of @code{pgg-gpg} scheme is initialized, it's stored to the
 276 variable @code{pgg-scheme-gpg-instance} and will be reused from now on.
 277
 278 @lisp
 279 (defvar pgg-scheme-gpg-instance nil)
 280
 281 (defun pgg-make-scheme-gpg ()
 282   (or pgg-scheme-gpg-instance
 283       (setq pgg-scheme-gpg-instance
 284             (luna-make-entity 'pgg-scheme-gpg))))
 285 @end lisp
 286
 287 The name of the function must follow the
 288 regulation---@code{pgg-make-scheme-} follows the backend name.
 289
 290 @node Backend methods
 291 @section Backend methods
 292
 293 In each backend, these methods must be present.  The output of these
 294 methods is stored in special buffers (@ref{Getting output}), so that
 295 these methods must tell the status of the execution.
 296
 297 @deffn Method pgg-scheme-lookup-key scheme string &optional type
 298 Return keys associated with @var{string}.  If the optional third
 299 argument @var{type} is non-@code{nil}, it searches from the secret
 300 keyrings.
 301 @end deffn
 302
 303 @deffn Method pgg-scheme-encrypt-region scheme start end recipients &optional sign
 304 Encrypt the current region between @var{start} and @var{end} for
 305 @var{recipients}.  If @var{sign} is non-@code{nil}, do a combined sign
 306 and encrypt.  If encryption is successful, it returns @code{t},
 307 otherwise @code{nil}.
 308 @end deffn
 309
 310 @deffn Method pgg-scheme-decrypt-region scheme start end
 311 Decrypt the current region between @var{start} and @var{end}.  If
 312 decryption is successful, it returns @code{t}, otherwise @code{nil}.
 313 @end deffn
 314
 315 @deffn Method pgg-scheme-sign-region scheme start end &optional cleartext
 316 Make the signature from text between @var{start} and @var{end}.  If the
 317 optional third argument @var{cleartext} is non-@code{nil}, it does not
 318 create a detached signature.  If signing is successful, it returns
 319 @code{t}, otherwise @code{nil}.
 320 @end deffn
 321
 322 @deffn Method pgg-scheme-verify-region scheme start end &optional signature
 323 Verify the current region between @var{start} and @var{end}.  If the
 324 optional third argument @var{signature} is non-@code{nil}, it is treated
 325 as the detached signature of the current region.  If the signature is
 326 successfully verified, it returns @code{t}, otherwise @code{nil}.
 327 @end deffn
 328
 329 @deffn Method pgg-scheme-insert-key scheme
 330 Retrieve the user's public key and insert it as ASCII-armored format.
 331 On success, it returns @code{t}, otherwise @code{nil}.
 332 @end deffn
 333
 334 @deffn Method pgg-scheme-snarf-keys-region scheme start end
 335 Collect public keys in the current region between @var{start} and
 336 @var{end}, and add them into the user's keyring.
 337 On success, it returns @code{t}, otherwise @code{nil}.
 338 @end deffn
 339
 340 @node Getting output
 341 @section Getting output
 342
 343 The output of the backend methods (@ref{Backend methods}) is stored in
 344 special buffers, so that these methods must tell the status of the
 345 execution.
 346
 347 @defvar pgg-errors-buffer
 348 The standard error output of the execution of the PGP command is stored
 349 here.
 350 @end defvar
 351
 352 @defvar pgg-output-buffer
 353 The standard output of the execution of the PGP command is stored here.
 354 @end defvar
 355
 356 @defvar pgg-status-buffer
 357 The rest of status information of the execution of the PGP command is
 358 stored here.
 359 @end defvar
 360
 361 @node Parsing OpenPGP packets
 362 @chapter Parsing OpenPGP packets
 363
 364 The format of OpenPGP messages is maintained in order to publish all
 365 necessary information needed to develop interoperable applications.
 366 The standard is documented in RFC 2440.
 367
 368 PGG has its own parser for the OpenPGP packets.
 369
 370 @defun pgg-parse-armor string
 371 List the sequence of packets in @var{string}.
 372 @end defun
 373
 374 @defun pgg-parse-armor-region start end
 375 List the sequence of packets in the current region between @var{start}
 376 and @var{end}.
 377 @end defun
 378
 379 @defvar pgg-ignore-packet-checksum
 380 If non-@code{nil}, don't check the checksum of the packets.
 381 @end defvar
 382
 383 @node Function Index
 384 @chapter Function Index
 385 @printindex fn
 386
 387 @node Variable Index
 388 @chapter Variable Index
 389 @printindex vr
 390
 391 @summarycontents
 392 @contents
 393 @bye
 394
 395 @c End:
 396
 397 @ignore
 398    arch-tag: 0c205838-34b9-41a5-b9d7-49ae57ccac85
 399 @end ignore