[Emacs-diffs] Changes to pgg.texi

[Glenn Morris]

CVSROOT:        /sources/emacs
Module name:    emacs
Changes by:     Glenn Morris <gm>       07/09/06 05:01:40

Index: pgg.texi
===================================================================
RCS file: pgg.texi
diff -N pgg.texi
--- /dev/null   1 Jan 1970 00:00:00 -0000
+++ pgg.texi    6 Sep 2007 05:01:40 -0000       1.1
@@ -0,0 +1,498 @@
+\input texinfo                  @c -*-texinfo-*-
+
address@hidden ../info/pgg
+
address@hidden VERSION 0.1
+
+
address@hidden
+This file describes PGG, an Emacs interface to various PGP implementations.
+
+Copyright @copyright{} 2001, 2003, 2004, 2005, 2006, 2007  Free Software
+Foundation, Inc.
+
address@hidden
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.2 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
+Texts.  A copy of the license is included in the section entitled ``GNU
+Free Documentation License.''
address@hidden quotation
address@hidden copying
+
address@hidden Emacs
address@hidden
+* PGG: (pgg).   Emacs interface to various PGP implementations.
address@hidden direntry
+
address@hidden PGG @value{VERSION}
+
+
address@hidden
address@hidden PGG
+
address@hidden by Daiki Ueno
address@hidden
+
address@hidden 0pt plus 1filll
address@hidden
address@hidden titlepage
address@hidden
+
address@hidden Top
address@hidden PGG
+This manual describes PGG.  PGG is an interface library between Emacs
+and various tools for secure communication.  PGG also provides a simple
+user interface to encrypt, decrypt, sign, and verify MIME messages.
+
address@hidden
+* Overview::                    What PGG is.
+* Prerequisites::               Complicated stuff you may have to do.
+* How to use::                  Getting started quickly.
+* Architecture::                
+* Parsing OpenPGP packets::     
+* GNU Free Documentation License:: The license for this documentation.
+* Function Index::              
+* Variable Index::              
address@hidden menu
+
address@hidden Overview
address@hidden Overview
+
+PGG is an interface library between Emacs and various tools for secure
+communication.  Even though Mailcrypt has similar feature, it does not
+deal with detached PGP messages, normally used in PGP/MIME
+infrastructure.  This was the main reason why I wrote the new library.
+
+PGP/MIME is an application of MIME Object Security Services (RFC1848).
+The standard is documented in RFC2015.
+
address@hidden Prerequisites
address@hidden Prerequisites
+
+PGG requires at least one implementation of privacy guard system.
+This document assumes that you have already obtained and installed them
+and that you are familiar with its basic functions.
+
+By default, PGG uses GnuPG.  If you are new to such a system, I
+recommend that you should look over the GNU Privacy Handbook (GPH)
+which is available at @uref{http://www.gnupg.org/documentation/}.
+
+When using GnuPG, we recommend the use of the @code{gpg-agent}
+program, which is distributed with versions 2.0 and later of GnuPG.
+This is a daemon to manage private keys independently from any
+protocol, and provides the most secure way to input and cache your
+passphrases (@pxref{Caching passphrase}).  By default, PGG will
+attempt to use @code{gpg-agent} if it is running.  @xref{Invoking
+GPG-AGENT,,,gnupg,Using the GNU Privacy Guard}.
+
+PGG also supports Pretty Good Privacy version 2 or version 5.
+
address@hidden How to use
address@hidden How to use
+
+The toplevel interface of this library is quite simple, and only
+intended to use with public-key cryptographic operation.
+
+To use PGG, evaluate following expression at the beginning of your
+application program.
+
address@hidden
+(require 'pgg)
address@hidden lisp
+
+If you want to check existence of pgg.el at runtime, instead you can
+list autoload setting for desired functions as follows.
+
address@hidden
+(autoload 'pgg-encrypt-region "pgg"
+  "Encrypt the current region." t)
+(autoload 'pgg-encrypt-symmetric-region "pgg"
+  "Encrypt the current region with symmetric algorithm." t)
+(autoload 'pgg-decrypt-region "pgg"
+  "Decrypt the current region." t)
+(autoload 'pgg-sign-region "pgg"
+  "Sign the current region." t)
+(autoload 'pgg-verify-region "pgg"
+  "Verify the current region." t)
+(autoload 'pgg-insert-key "pgg"
+  "Insert the ASCII armored public key." t)
+(autoload 'pgg-snarf-keys-region "pgg"
+  "Import public keys in the current region." t)
address@hidden lisp
+
address@hidden
+* User Commands::               
+* Selecting an implementation::  
+* Caching passphrase::          
+* Default user identity::      
address@hidden menu
+
address@hidden User Commands
address@hidden User Commands
+
+At this time you can use some cryptographic commands.  The behavior of
+these commands relies on a fashion of invocation because they are also
+intended to be used as library functions.  In case you don't have the
+signer's public key, for example, the function @code{pgg-verify-region}
+fails immediately, but if the function had been called interactively, it
+would ask you to retrieve the signer's public key from the server.
+
address@hidden Command pgg-encrypt-region start end recipients &optional sign 
passphrase
+Encrypt the current region between @var{start} and @var{end} for
address@hidden  When the function were called interactively, you
+would be asked about the recipients.
+
+If encryption is successful, it replaces the current region contents (in
+the accessible portion) with the resulting data.
+
+If optional argument @var{sign} is address@hidden, the function is
+request to do a combined sign and encrypt.  This currently is
+confirmed to work with GnuPG, but might not work with PGP or PGP5.
+
+If optional @var{passphrase} is @code{nil}, the passphrase will be
+obtained from the passphrase cache or user.
address@hidden deffn
+
address@hidden Command pgg-encrypt-symmetric-region &optional start end 
passphrase
+Encrypt the current region between @var{start} and @var{end} using a
+symmetric cipher.  After invocation you are asked for a passphrase.
+
+If optional @var{passphrase} is @code{nil}, the passphrase will be
+obtained from the passphrase cache or user.
+
+symmetric-cipher encryption is currently only implemented for GnuPG.
address@hidden deffn
+
address@hidden Command pgg-decrypt-region start end &optional passphrase
+Decrypt the current region between @var{start} and @var{end}.  If
+decryption is successful, it replaces the current region contents (in
+the accessible portion) with the resulting data.
+
+If optional @var{passphrase} is @code{nil}, the passphrase will be
+obtained from the passphrase cache or user.
address@hidden deffn
+
address@hidden Command pgg-sign-region start end &optional cleartext passphrase
+Make the signature from text between @var{start} and @var{end}.  If the
+optional third argument @var{cleartext} is address@hidden, or the
+function is called interactively, it does not create a detached
+signature.  In such a case, it replaces the current region contents (in
+the accessible portion) with the resulting data.
+
+If optional @var{passphrase} is @code{nil}, the passphrase will be
+obtained from the passphrase cache or user.
address@hidden deffn
+
address@hidden Command pgg-verify-region start end &optional signature fetch
+Verify the current region between @var{start} and @var{end}.  If the
+optional third argument @var{signature} is address@hidden, it is treated
+as the detached signature file of the current region.
+
+If the optional 4th argument @var{fetch} is address@hidden, or the
+function is called interactively, we attempt to fetch the signer's
+public key from the key server.
address@hidden deffn
+
address@hidden Command pgg-insert-key
+Retrieve the user's public key and insert it as ASCII-armored format.
address@hidden deffn
+
address@hidden Command pgg-snarf-keys-region start end
+Collect public keys in the current region between @var{start} and
address@hidden, and add them into the user's keyring.
address@hidden deffn
+
address@hidden Selecting an implementation
address@hidden Selecting an implementation
+
+Since PGP has a long history and there are a number of PGP
+implementations available today, the function which each one has differs
+considerably.  For example, if you are using GnuPG, you know you can
+select cipher algorithm from 3DES, CAST5, BLOWFISH, and so on, but on
+the other hand the version 2 of PGP only supports IDEA.
+
+Which implementation is used is controlled by the @code{pgg-scheme}
+variable.  If it is @code{nil} (the default), the value of the
address@hidden variable will be used instead.
+
address@hidden pgg-scheme
+Force specify the scheme of PGP implementation.  The value can be set to
address@hidden, @code{pgp}, and @code{pgp5}.  The default is @code{nil}.
address@hidden defvar
+
address@hidden pgg-default-scheme
+The default scheme of PGP implementation.  The value should be one of
address@hidden, @code{pgp}, and @code{pgp5}.  The default is @code{gpg}.
address@hidden defvar
+
address@hidden Caching passphrase
address@hidden Caching passphrase
+
+When using GnuPG (gpg) as the PGP scheme, we recommend using a program
+called @code{gpg-agent} for entering and caching
address@hidden, @code{gpg-agent} does not cache
+passphrases but private keys.  On the other hand, from a user's point
+of view, this technical difference isn't visible.}.
+
address@hidden pgg-gpg-use-agent
+If address@hidden, attempt to use @code{gpg-agent} whenever possible.
+The default is @code{t}.  If @code{gpg-agent} is not running, or GnuPG
+is not the current PGP scheme, PGG's own passphrase-caching mechanism
+is used (see below).
address@hidden defvar
+
+To use @code{gpg-agent} with PGG, you must first ensure that
address@hidden is running.  For example, if you are running in the X
+Window System, you can do this by putting the following line in your
address@hidden file:
+
address@hidden
+eval "$(gpg-agent --daemon)"
address@hidden smallexample
+
+For more details on invoking @code{gpg-agent}, @xref{Invoking
+GPG-AGENT,,,gnupg,Using the GNU Privacy Guard}.
+
+Whenever you perform a PGG operation that requires a GnuPG passphrase,
+GnuPG will contact @code{gpg-agent}, which prompts you for the
+passphrase.  Furthermore, @code{gpg-agent} ``caches'' the result, so
+that subsequent uses will not require you to enter the passphrase
+again.  (This cache usually expires after a certain time has passed;
+you can change this using the @code{--default-cache-ttl} option when
+invoking @code{gpg-agent}.)
+
+If you are running in a X Window System environment, @code{gpg-agent}
+prompts for a passphrase by opening a graphical window.  However, if
+you are running Emacs on a text terminal, @code{gpg-agent} has trouble
+receiving input from the terminal, since it is being sent to Emacs.
+One workaround for this problem is to run @code{gpg-agent} on a
+different terminal from Emacs, with the @code{--keep-tty} option; this
+tells @code{gpg-agent} use its own terminal to prompt for passphrases.
+
+When @code{gpg-agent} is not being used, PGG prompts for a passphrase
+through Emacs.  It also has its own passphrase caching mechanism,
+which is controlled by the variable @code{pgg-cache-passphrase} (see
+below).
+
+There is a security risk in handling passphrases through PGG rather
+than @code{gpg-agent}.  When you enter your passphrase into an Emacs
+prompt, it is temporarily stored as a cleartext string in the memory
+of the Emacs executable.  If the executable memory is swapped to disk,
+the root user can, in theory, extract the passphrase from the
+swapfile.  Furthermore, the swapfile containing the cleartext
+passphrase might remain on the disk after the system is discarded or
+stolen.  @code{gpg-agent} avoids this problem by using certain tricks,
+such as memory locking, which have not been implemented in Emacs.
+
address@hidden pgg-cache-passphrase
+If address@hidden, store passphrases.  The default value of this
+variable is @code{t}.  If you are worried about security issues,
+however, you could stop the caching of passphrases by setting this
+variable to @code{nil}.
address@hidden defvar
+
address@hidden pgg-passphrase-cache-expiry
+Elapsed time for expiration in seconds.
address@hidden defvar
+
+If your passphrase contains non-ASCII characters, you might need to
+specify the coding system to be used to encode your passphrases, since
+GnuPG treats them as a byte sequence, not as a character sequence.
+
address@hidden pgg-passphrase-coding-system
+Coding system used to encode passphrase.
address@hidden defvar
+
address@hidden Default user identity
address@hidden Default user identity
+
+The PGP implementation is usually able to select the proper key to use
+for signing and decryption, but if you have more than one key, you may
+need to specify the key id to use.
+
address@hidden pgg-default-user-id
+User ID of your default identity.  It defaults to the value returned
+by @samp{(user-login-name)}.  You can customize this variable.
address@hidden defvar
+
address@hidden pgg-gpg-user-id
+User ID of the GnuPG default identity.  It defaults to @samp{nil}.
+This overrides @samp{pgg-default-user-id}.  You can customize this
+variable.
address@hidden defvar
+
address@hidden pgg-pgp-user-id
+User ID of the PGP 2.x/6.x default identity.  It defaults to
address@hidden  This overrides @samp{pgg-default-user-id}.  You can
+customize this variable.
address@hidden defvar
+
address@hidden pgg-pgp5-user-id
+User ID of the PGP 5.x default identity.  It defaults to @samp{nil}.
+This overrides @samp{pgg-default-user-id}.  You can customize this
+variable.
address@hidden defvar
+
address@hidden Architecture
address@hidden Architecture
+
+PGG introduces the notion of a "scheme of PGP implementation" (used
+interchangeably with "scheme" in this document).  This term refers to a
+singleton object wrapped with the luna object system.
+
+Since PGG was designed for accessing and developing PGP functionality,
+the architecture had to be designed not just for interoperability but
+also for extensiblity.  In this chapter we explore the architecture
+while finding out how to write the PGG backend.
+
address@hidden
+* Initializing::                
+* Backend methods::             
+* Getting output::              
address@hidden menu
+
address@hidden Initializing
address@hidden Initializing
+
+A scheme must be initialized before it is used.
+It had better guarantee to keep only one instance of a scheme.
+
+The following code is snipped out of @file{pgg-gpg.el}.  Once an
+instance of @code{pgg-gpg} scheme is initialized, it's stored to the
+variable @code{pgg-scheme-gpg-instance} and will be reused from now on.
+
address@hidden
+(defvar pgg-scheme-gpg-instance nil)
+
+(defun pgg-make-scheme-gpg ()
+  (or pgg-scheme-gpg-instance
+      (setq pgg-scheme-gpg-instance
+           (luna-make-entity 'pgg-scheme-gpg))))
address@hidden lisp
+
+The name of the function must follow the
address@hidden follows the backend name.
+
address@hidden Backend methods
address@hidden Backend methods
+
+In each backend, these methods must be present.  The output of these
+methods is stored in special buffers (@ref{Getting output}), so that
+these methods must tell the status of the execution.
+
address@hidden Method pgg-scheme-lookup-key scheme string &optional type
+Return keys associated with @var{string}.  If the optional third
+argument @var{type} is address@hidden, it searches from the secret
+keyrings.
address@hidden deffn
+
address@hidden Method pgg-scheme-encrypt-region scheme start end recipients 
&optional sign passphrase
+Encrypt the current region between @var{start} and @var{end} for
address@hidden  If @var{sign} is address@hidden, do a combined sign
+and encrypt.  If encryption is successful, it returns @code{t},
+otherwise @code{nil}.
address@hidden deffn
+
address@hidden Method pgg-scheme-encrypt-symmetric-region scheme start end 
&optional passphrase
+Encrypt the current region between @var{start} and @var{end} using a
+symmetric cipher and a passphrases.  If encryption is successful, it
+returns @code{t}, otherwise @code{nil}.  This function is currently only
+implemented for GnuPG.
address@hidden deffn
+
address@hidden Method pgg-scheme-decrypt-region scheme start end &optional 
passphrase
+Decrypt the current region between @var{start} and @var{end}.  If
+decryption is successful, it returns @code{t}, otherwise @code{nil}.
address@hidden deffn
+
address@hidden Method pgg-scheme-sign-region scheme start end &optional 
cleartext passphrase
+Make the signature from text between @var{start} and @var{end}.  If the
+optional third argument @var{cleartext} is address@hidden, it does not
+create a detached signature.  If signing is successful, it returns
address@hidden, otherwise @code{nil}.
address@hidden deffn
+
address@hidden Method pgg-scheme-verify-region scheme start end &optional 
signature
+Verify the current region between @var{start} and @var{end}.  If the
+optional third argument @var{signature} is address@hidden, it is treated
+as the detached signature of the current region.  If the signature is
+successfully verified, it returns @code{t}, otherwise @code{nil}.
address@hidden deffn
+
address@hidden Method pgg-scheme-insert-key scheme
+Retrieve the user's public key and insert it as ASCII-armored format.
+On success, it returns @code{t}, otherwise @code{nil}.
address@hidden deffn
+
address@hidden Method pgg-scheme-snarf-keys-region scheme start end
+Collect public keys in the current region between @var{start} and
address@hidden, and add them into the user's keyring.
+On success, it returns @code{t}, otherwise @code{nil}.
address@hidden deffn
+
address@hidden Getting output
address@hidden Getting output
+
+The output of the backend methods (@ref{Backend methods}) is stored in
+special buffers, so that these methods must tell the status of the
+execution.
+
address@hidden pgg-errors-buffer
+The standard error output of the execution of the PGP command is stored
+here.
address@hidden defvar
+
address@hidden pgg-output-buffer
+The standard output of the execution of the PGP command is stored here.
address@hidden defvar
+
address@hidden pgg-status-buffer
+The rest of status information of the execution of the PGP command is
+stored here.
address@hidden defvar
+
address@hidden Parsing OpenPGP packets
address@hidden Parsing OpenPGP packets
+
+The format of OpenPGP messages is maintained in order to publish all
+necessary information needed to develop interoperable applications.
+The standard is documented in RFC 2440.
+
+PGG has its own parser for the OpenPGP packets.
+
address@hidden pgg-parse-armor string
+List the sequence of packets in @var{string}.
address@hidden defun
+
address@hidden pgg-parse-armor-region start end
+List the sequence of packets in the current region between @var{start}
+and @var{end}.
address@hidden defun
+
address@hidden pgg-ignore-packet-checksum
+If address@hidden, don't check the checksum of the packets.
address@hidden defvar
+
address@hidden GNU Free Documentation License
address@hidden GNU Free Documentation License
address@hidden doclicense.texi
+
address@hidden Function Index
address@hidden Function Index
address@hidden fn
+
address@hidden Variable Index
address@hidden Variable Index
address@hidden vr
+
address@hidden
address@hidden
address@hidden
+
address@hidden End:
+
address@hidden
+   arch-tag: 0c205838-34b9-41a5-b9d7-49ae57ccac85
address@hidden ignore