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