doc/misc/pgg.texi

   1 \input texinfo                  @c -*-texinfo-*-
   2
   3 @include gnus-overrides.texi
   4
   5 @setfilename ../../info/pgg.info
   6
   7 @set VERSION 0.1
   8 @settitle PGG @value{VERSION}
   9 @include docstyle.texi
  10
  11 @copying
  12 This file describes PGG @value{VERSION}, an Emacs interface to various
  13 PGP implementations.
  14
  15 Copyright @copyright{} 2001, 2003--2017 Free Software Foundation, Inc.
  16
  17 @quotation
  18 Permission is granted to copy, distribute and/or modify this document
  19 under the terms of the GNU Free Documentation License, Version 1.3 or
  20 any later version published by the Free Software Foundation; with no
  21 Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,''
  22 and with the Back-Cover Texts as in (a) below.  A copy of the license
  23 is included in the section entitled ``GNU Free Documentation License.''
  24
  25 (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
  26 modify this GNU manual.''
  27 @end quotation
  28 @end copying
  29
  30 @dircategory Emacs network features
  31 @direntry
  32 * PGG: (pgg).                   Emacs interface to various PGP implementations.
  33 @end direntry
  34
  35 @titlepage
  36 @ifset WEBHACKDEVEL
  37 @title PGG (DEVELOPMENT VERSION)
  38 @end ifset
  39 @ifclear WEBHACKDEVEL
  40 @title PGG
  41 @end ifclear
  42
  43 @author by Daiki Ueno
  44 @page
  45
  46 @vskip 0pt plus 1filll
  47 @insertcopying
  48 @end titlepage
  49
  50 @contents
  51
  52 @node Top
  53 @top PGG
  54
  55 PGG is an interface library between Emacs
  56 and various tools for secure communication.  PGG also provides a simple
  57 user interface to encrypt, decrypt, sign, and verify MIME messages.
  58 This package is obsolete; for new code we recommend EasyPG instead.
  59 @xref{Top,, EasyPG, epa, EasyPG Assistant User's Manual}.
  60
  61 @ifnottex
  62 @insertcopying
  63 @end ifnottex
  64
  65 @menu
  66 * Overview::                    What PGG is.
  67 * Prerequisites::               Complicated stuff you may have to do.
  68 * How to use::                  Getting started quickly.
  69 * Architecture::
  70 * Parsing OpenPGP packets::
  71 * GNU Free Documentation License:: The license for this documentation.
  72 * Function Index::
  73 * Variable Index::
  74 @end menu
  75
  76 @node Overview
  77 @chapter Overview
  78
  79 PGG is an interface library between Emacs and various tools for secure
  80 communication.  Even though Mailcrypt has similar feature, it does not
  81 deal with detached PGP messages, normally used in PGP/MIME
  82 infrastructure.  This was the main reason why I wrote the new library.
  83
  84 Note that the PGG library is now obsolete, replaced by EasyPG@.
  85 @xref{Top,, EasyPG, epa, EasyPG Assistant User's Manual}.
  86
  87 PGP/MIME is an application of MIME Object Security Services (RFC1848).
  88 The standard is documented in RFC2015.
  89
  90 @node Prerequisites
  91 @chapter Prerequisites
  92
  93 PGG requires at least one implementation of privacy guard system.
  94 This document assumes that you have already obtained and installed them
  95 and that you are familiar with its basic functions.
  96
  97 By default, PGG uses GnuPG@.  If you are new to such a system, I
  98 recommend that you should look over the GNU Privacy Handbook (GPH)
  99 which is available at @uref{http://www.gnupg.org/documentation/}.
 100
 101 When using GnuPG, we recommend the use of the @code{gpg-agent}
 102 program, which is distributed with versions 2.0 and later of GnuPG@.
 103 This is a daemon to manage private keys independently from any
 104 protocol, and provides the most secure way to input and cache your
 105 passphrases (@pxref{Caching passphrase}).  By default, PGG will
 106 attempt to use @code{gpg-agent} if it is running.  @xref{Invoking
 107 GPG-AGENT,,,gnupg,Using the GNU Privacy Guard}.
 108
 109 PGG also supports Pretty Good Privacy version 2 or version 5.
 110
 111 @node How to use
 112 @chapter How to use
 113
 114 The toplevel interface of this library is quite simple, and only
 115 intended to use with public-key cryptographic operation.
 116
 117 To use PGG, evaluate following expression at the beginning of your
 118 application program.
 119
 120 @lisp
 121 (require 'pgg)
 122 @end lisp
 123
 124 If you want to check existence of pgg.el at runtime, instead you can
 125 list autoload setting for desired functions as follows.
 126
 127 @lisp
 128 (autoload 'pgg-encrypt-region "pgg"
 129   "Encrypt the current region." t)
 130 (autoload 'pgg-encrypt-symmetric-region "pgg"
 131   "Encrypt the current region with symmetric algorithm." t)
 132 (autoload 'pgg-decrypt-region "pgg"
 133   "Decrypt the current region." t)
 134 (autoload 'pgg-sign-region "pgg"
 135   "Sign the current region." t)
 136 (autoload 'pgg-verify-region "pgg"
 137   "Verify the current region." t)
 138 (autoload 'pgg-insert-key "pgg"
 139   "Insert the ASCII armored public key." t)
 140 (autoload 'pgg-snarf-keys-region "pgg"
 141   "Import public keys in the current region." t)
 142 @end lisp
 143
 144 @menu
 145 * User Commands::
 146 * Selecting an implementation::
 147 * Caching passphrase::
 148 * Default user identity::
 149 @end menu
 150
 151 @node User Commands
 152 @section User Commands
 153
 154 At this time you can use some cryptographic commands.  The behavior of
 155 these commands relies on a fashion of invocation because they are also
 156 intended to be used as library functions.  In case you don't have the
 157 signer's public key, for example, the function @code{pgg-verify-region}
 158 fails immediately, but if the function had been called interactively, it
 159 would ask you to retrieve the signer's public key from the server.
 160
 161 @deffn Command pgg-encrypt-region start end recipients &optional sign passphrase
 162 Encrypt the current region between @var{start} and @var{end} for
 163 @var{recipients}.  When the function were called interactively, you
 164 would be asked about the recipients.
 165
 166 If encryption is successful, it replaces the current region contents (in
 167 the accessible portion) with the resulting data.
 168
 169 If optional argument @var{sign} is non-@code{nil}, the function is
 170 request to do a combined sign and encrypt.  This currently is
 171 confirmed to work with GnuPG, but might not work with PGP or PGP5.
 172
 173 If optional @var{passphrase} is @code{nil}, the passphrase will be
 174 obtained from the passphrase cache or user.
 175 @end deffn
 176
 177 @deffn Command pgg-encrypt-symmetric-region &optional start end passphrase
 178 Encrypt the current region between @var{start} and @var{end} using a
 179 symmetric cipher.  After invocation you are asked for a passphrase.
 180
 181 If optional @var{passphrase} is @code{nil}, the passphrase will be
 182 obtained from the passphrase cache or user.
 183
 184 symmetric-cipher encryption is currently only implemented for GnuPG.
 185 @end deffn
 186
 187 @deffn Command pgg-decrypt-region start end &optional passphrase
 188 Decrypt the current region between @var{start} and @var{end}.  If
 189 decryption is successful, it replaces the current region contents (in
 190 the accessible portion) with the resulting data.
 191
 192 If optional @var{passphrase} is @code{nil}, the passphrase will be
 193 obtained from the passphrase cache or user.
 194 @end deffn
 195
 196 @deffn Command pgg-sign-region start end &optional cleartext passphrase
 197 Make the signature from text between @var{start} and @var{end}.  If the
 198 optional third argument @var{cleartext} is non-@code{nil}, or the
 199 function is called interactively, it does not create a detached
 200 signature.  In such a case, it replaces the current region contents (in
 201 the accessible portion) with the resulting data.
 202
 203 If optional @var{passphrase} is @code{nil}, the passphrase will be
 204 obtained from the passphrase cache or user.
 205 @end deffn
 206
 207 @deffn Command pgg-verify-region start end &optional signature fetch
 208 Verify the current region between @var{start} and @var{end}.  If the
 209 optional third argument @var{signature} is non-@code{nil}, it is treated
 210 as the detached signature file of the current region.
 211
 212 If the optional 4th argument @var{fetch} is non-@code{nil}, or the
 213 function is called interactively, we attempt to fetch the signer's
 214 public key from the key server.
 215 @end deffn
 216
 217 @deffn Command pgg-insert-key
 218 Retrieve the user's public key and insert it as ASCII-armored format.
 219 @end deffn
 220
 221 @deffn Command pgg-snarf-keys-region start end
 222 Collect public keys in the current region between @var{start} and
 223 @var{end}, and add them into the user's keyring.
 224 @end deffn
 225
 226 @node Selecting an implementation
 227 @section Selecting an implementation
 228
 229 Since PGP has a long history and there are a number of PGP
 230 implementations available today, the function which each one has differs
 231 considerably.  For example, if you are using GnuPG, you know you can
 232 select cipher algorithm from 3DES, CAST5, BLOWFISH, and so on, but on
 233 the other hand the version 2 of PGP only supports IDEA.
 234
 235 Which implementation is used is controlled by the @code{pgg-scheme}
 236 variable.  If it is @code{nil} (the default), the value of the
 237 @code{pgg-default-scheme} variable will be used instead.
 238
 239 @defvar pgg-scheme
 240 Force specify the scheme of PGP implementation.  The value can be set to
 241 @code{gpg}, @code{pgp}, and @code{pgp5}.  The default is @code{nil}.
 242 @end defvar
 243
 244 @defvar pgg-default-scheme
 245 The default scheme of PGP implementation.  The value should be one of
 246 @code{gpg}, @code{pgp}, and @code{pgp5}.  The default is @code{gpg}.
 247 @end defvar
 248
 249 @node Caching passphrase
 250 @section Caching passphrase
 251
 252 When using GnuPG (gpg) as the PGP scheme, we recommend using a program
 253 called @code{gpg-agent} for entering and caching
 254 passphrases@footnote{Actually, @code{gpg-agent} does not cache
 255 passphrases but private keys.  On the other hand, from a user's point
 256 of view, this technical difference isn't visible.}.
 257
 258 @defvar pgg-gpg-use-agent
 259 If non-@code{nil}, attempt to use @code{gpg-agent} whenever possible.
 260 The default is @code{t}.  If @code{gpg-agent} is not running, or GnuPG
 261 is not the current PGP scheme, PGG's own passphrase-caching mechanism
 262 is used (see below).
 263 @end defvar
 264
 265 To use @code{gpg-agent} with PGG, you must first ensure that
 266 @code{gpg-agent} is running.  For example, if you are running in the X
 267 Window System, you can do this by putting the following line in your
 268 @file{.xsession} file:
 269
 270 @smallexample
 271 eval "$(gpg-agent --daemon)"
 272 @end smallexample
 273
 274 For more details on invoking @code{gpg-agent}, @xref{Invoking
 275 GPG-AGENT,,,gnupg,Using the GNU Privacy Guard}.
 276
 277 Whenever you perform a PGG operation that requires a GnuPG passphrase,
 278 GnuPG will contact @code{gpg-agent}, which prompts you for the
 279 passphrase.  Furthermore, @code{gpg-agent} ``caches'' the result, so
 280 that subsequent uses will not require you to enter the passphrase
 281 again.  (This cache usually expires after a certain time has passed;
 282 you can change this using the @code{--default-cache-ttl} option when
 283 invoking @code{gpg-agent}.)
 284
 285 If you are running in a X Window System environment, @code{gpg-agent}
 286 prompts for a passphrase by opening a graphical window.  However, if
 287 you are running Emacs on a text terminal, @code{gpg-agent} has trouble
 288 receiving input from the terminal, since it is being sent to Emacs.
 289 One workaround for this problem is to run @code{gpg-agent} on a
 290 different terminal from Emacs, with the @code{--keep-tty} option; this
 291 tells @code{gpg-agent} use its own terminal to prompt for passphrases.
 292
 293 When @code{gpg-agent} is not being used, PGG prompts for a passphrase
 294 through Emacs.  It also has its own passphrase caching mechanism,
 295 which is controlled by the variable @code{pgg-cache-passphrase} (see
 296 below).
 297
 298 There is a security risk in handling passphrases through PGG rather
 299 than @code{gpg-agent}.  When you enter your passphrase into an Emacs
 300 prompt, it is temporarily stored as a cleartext string in the memory
 301 of the Emacs executable.  If the executable memory is swapped to disk,
 302 the root user can, in theory, extract the passphrase from the
 303 swapfile.  Furthermore, the swapfile containing the cleartext
 304 passphrase might remain on the disk after the system is discarded or
 305 stolen.  @code{gpg-agent} avoids this problem by using certain tricks,
 306 such as memory locking, which have not been implemented in Emacs.
 307
 308 @defvar pgg-cache-passphrase
 309 If non-@code{nil}, store passphrases.  The default value of this
 310 variable is @code{t}.  If you are worried about security issues,
 311 however, you could stop the caching of passphrases by setting this
 312 variable to @code{nil}.
 313 @end defvar
 314
 315 @defvar pgg-passphrase-cache-expiry
 316 Elapsed time for expiration in seconds.
 317 @end defvar
 318
 319 If your passphrase contains non-ASCII characters, you might need to
 320 specify the coding system to be used to encode your passphrases, since
 321 GnuPG treats them as a byte sequence, not as a character sequence.
 322
 323 @defvar pgg-passphrase-coding-system
 324 Coding system used to encode passphrase.
 325 @end defvar
 326
 327 @node Default user identity
 328 @section Default user identity
 329
 330 The PGP implementation is usually able to select the proper key to use
 331 for signing and decryption, but if you have more than one key, you may
 332 need to specify the key id to use.
 333
 334 @defvar pgg-default-user-id
 335 User ID of your default identity.  It defaults to the value returned
 336 by @samp{(user-login-name)}.  You can customize this variable.
 337 @end defvar
 338
 339 @defvar pgg-gpg-user-id
 340 User ID of the GnuPG default identity.  It defaults to @samp{nil}.
 341 This overrides @samp{pgg-default-user-id}.  You can customize this
 342 variable.
 343 @end defvar
 344
 345 @defvar pgg-pgp-user-id
 346 User ID of the PGP 2.x/6.x default identity.  It defaults to
 347 @samp{nil}.  This overrides @samp{pgg-default-user-id}.  You can
 348 customize this variable.
 349 @end defvar
 350
 351 @defvar pgg-pgp5-user-id
 352 User ID of the PGP 5.x default identity.  It defaults to @samp{nil}.
 353 This overrides @samp{pgg-default-user-id}.  You can customize this
 354 variable.
 355 @end defvar
 356
 357 @node Architecture
 358 @chapter Architecture
 359
 360 PGG introduces the notion of a "scheme of PGP implementation" (used
 361 interchangeably with "scheme" in this document).  This term refers to a
 362 singleton object wrapped with the luna object system.
 363
 364 Since PGG was designed for accessing and developing PGP functionality,
 365 the architecture had to be designed not just for interoperability but
 366 also for extensibility.  In this chapter we explore the architecture
 367 while finding out how to write the PGG back end.
 368
 369 @menu
 370 * Initializing::
 371 * Back end methods::
 372 * Getting output::
 373 @end menu
 374
 375 @node Initializing
 376 @section Initializing
 377
 378 A scheme must be initialized before it is used.
 379 It had better guarantee to keep only one instance of a scheme.
 380
 381 The following code is snipped out of @file{pgg-gpg.el}.  Once an
 382 instance of @code{pgg-gpg} scheme is initialized, it's stored to the
 383 variable @code{pgg-scheme-gpg-instance} and will be reused from now on.
 384
 385 @lisp
 386 (defvar pgg-scheme-gpg-instance nil)
 387
 388 (defun pgg-make-scheme-gpg ()
 389   (or pgg-scheme-gpg-instance
 390       (setq pgg-scheme-gpg-instance
 391             (luna-make-entity 'pgg-scheme-gpg))))
 392 @end lisp
 393
 394 The name of the function must follow the
 395 regulation---@code{pgg-make-scheme-} follows the back end name.
 396
 397 @node Back end methods
 398 @section Back end methods
 399
 400 In each back end, these methods must be present.  The output of these
 401 methods is stored in special buffers (@ref{Getting output}), so that
 402 these methods must tell the status of the execution.
 403
 404 @deffn Method pgg-scheme-lookup-key scheme string &optional type
 405 Return keys associated with @var{string}.  If the optional third
 406 argument @var{type} is non-@code{nil}, it searches from the secret
 407 keyrings.
 408 @end deffn
 409
 410 @deffn Method pgg-scheme-encrypt-region scheme start end recipients &optional sign passphrase
 411 Encrypt the current region between @var{start} and @var{end} for
 412 @var{recipients}.  If @var{sign} is non-@code{nil}, do a combined sign
 413 and encrypt.  If encryption is successful, it returns @code{t},
 414 otherwise @code{nil}.
 415 @end deffn
 416
 417 @deffn Method pgg-scheme-encrypt-symmetric-region scheme start end &optional passphrase
 418 Encrypt the current region between @var{start} and @var{end} using a
 419 symmetric cipher and a passphrases.  If encryption is successful, it
 420 returns @code{t}, otherwise @code{nil}.  This function is currently only
 421 implemented for GnuPG.
 422 @end deffn
 423
 424 @deffn Method pgg-scheme-decrypt-region scheme start end &optional passphrase
 425 Decrypt the current region between @var{start} and @var{end}.  If
 426 decryption is successful, it returns @code{t}, otherwise @code{nil}.
 427 @end deffn
 428
 429 @deffn Method pgg-scheme-sign-region scheme start end &optional cleartext passphrase
 430 Make the signature from text between @var{start} and @var{end}.  If the
 431 optional third argument @var{cleartext} is non-@code{nil}, it does not
 432 create a detached signature.  If signing is successful, it returns
 433 @code{t}, otherwise @code{nil}.
 434 @end deffn
 435
 436 @deffn Method pgg-scheme-verify-region scheme start end &optional signature
 437 Verify the current region between @var{start} and @var{end}.  If the
 438 optional third argument @var{signature} is non-@code{nil}, it is treated
 439 as the detached signature of the current region.  If the signature is
 440 successfully verified, it returns @code{t}, otherwise @code{nil}.
 441 @end deffn
 442
 443 @deffn Method pgg-scheme-insert-key scheme
 444 Retrieve the user's public key and insert it as ASCII-armored format.
 445 On success, it returns @code{t}, otherwise @code{nil}.
 446 @end deffn
 447
 448 @deffn Method pgg-scheme-snarf-keys-region scheme start end
 449 Collect public keys in the current region between @var{start} and
 450 @var{end}, and add them into the user's keyring.
 451 On success, it returns @code{t}, otherwise @code{nil}.
 452 @end deffn
 453
 454 @node Getting output
 455 @section Getting output
 456
 457 The output of the back end methods (@ref{Back end methods}) is stored in
 458 special buffers, so that these methods must tell the status of the
 459 execution.
 460
 461 @defvar pgg-errors-buffer
 462 The standard error output of the execution of the PGP command is stored
 463 here.
 464 @end defvar
 465
 466 @defvar pgg-output-buffer
 467 The standard output of the execution of the PGP command is stored here.
 468 @end defvar
 469
 470 @defvar pgg-status-buffer
 471 The rest of status information of the execution of the PGP command is
 472 stored here.
 473 @end defvar
 474
 475 @node Parsing OpenPGP packets
 476 @chapter Parsing OpenPGP packets
 477
 478 The format of OpenPGP messages is maintained in order to publish all
 479 necessary information needed to develop interoperable applications.
 480 The standard is documented in RFC 2440.
 481
 482 PGG has its own parser for the OpenPGP packets.
 483
 484 @defun pgg-parse-armor string
 485 List the sequence of packets in @var{string}.
 486 @end defun
 487
 488 @defun pgg-parse-armor-region start end
 489 List the sequence of packets in the current region between @var{start}
 490 and @var{end}.
 491 @end defun
 492
 493 @defvar pgg-ignore-packet-checksum
 494 If non-@code{nil}, don't check the checksum of the packets.
 495 @end defvar
 496
 497 @node GNU Free Documentation License
 498 @appendix GNU Free Documentation License
 499 @include doclicense.texi
 500
 501 @node Function Index
 502 @unnumbered Function Index
 503 @printindex fn
 504
 505 @node Variable Index
 506 @unnumbered Variable Index
 507 @printindex vr
 508
 509 @bye
 510
 511 @c End: