[Emacs-diffs] Changes to emacs/man/pgg.texi [gnus-5_10-branch]

[Reiner Steib]

Index: emacs/man/pgg.texi
diff -c /dev/null emacs/man/pgg.texi:1.1.2.1
*** /dev/null   Mon Aug  2 13:28:48 2004
--- emacs/man/pgg.texi  Mon Aug  2 13:28:45 2004
***************
*** 0 ****
--- 1,404 ----
+ \input texinfo                  @c -*-texinfo-*-
+ 
+ @setfilename ../info/pgg
+ 
+ @set VERSION 0.1
+ 
+ @direntry
+ * PGG: (pgg).   Emacs interface to various PGP implementations.
+ @end direntry
+ 
+ @settitle PGG @value{VERSION}
+ 
+ @ifinfo
+ This file describes the PGG.
+ 
+ Copyright (C) 2003 Free Software Foundation, Inc.
+ Copyright (C) 2001 Daiki Ueno.
+ 
+ Permission is granted to copy, distribute and/or modify this document
+ under the terms of the GNU Free Documentation License, Version 1.1 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".
+ @end ifinfo
+ 
+ @tex
+ 
+ @titlepage
+ @title PGG
+ 
+ @author by Daiki Ueno
+ @page
+ 
+ @vskip 0pt plus 1filll
+ Copyright @copyright{} 2001 Daiki Ueno.
+ 
+ Permission is granted to copy, distribute and/or modify this document
+ under the terms of the GNU Free Documentation License, Version 1.1 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".
+ @end titlepage
+ @page
+ 
+ @end tex
+ 
+ @node Top
+ @top 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.
+ 
+ @menu
+ * Overview::                    What PGG is.
+ * Prerequisites::               Complicated stuff you may have to do.
+ * How to use::                  Getting started quickly.
+ * Architecture::                
+ * Parsing OpenPGP packets::     
+ * Function Index::              
+ * Variable Index::              
+ @end menu
+ 
+ @node Overview
+ @chapter 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.
+ 
+ @node Prerequisites
+ @chapter 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, but Pretty Good Privacy version 2 or version
+ 5 are also supported.  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/gph/}.
+ 
+ @node How to use
+ @chapter 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.
+ 
+ @lisp
+ (require 'pgg)
+ @end lisp
+ 
+ If you want to check existence of pgg.el at runtime, instead you can
+ list autoload setting for desired functions as follows.
+ 
+ @lisp
+ (autoload 'pgg-encrypt-region "pgg"
+   "Encrypt the current region." 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)
+ @end lisp
+ 
+ @menu
+ * User Commands::               
+ * Selecting an implementation::  
+ * Caching passphrase::          
+ * Default user identity::     
+ @end menu
+ 
+ @node User Commands
+ @section 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.
+ 
+ @deffn Command pgg-encrypt-region start end recipients &optional sign
+ Encrypt the current region between @var{start} and @var{end} for
+ @var{recipients}.  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 non-nil, the function is request to
+ do a combined sign and encrypt.  This currently only work with GnuPG.
+ @end deffn
+ 
+ @deffn Command pgg-decrypt-region start end
+ 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.
+ @end deffn
+ 
+ @deffn Command pgg-sign-region start end &optional cleartext
+ 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.
+ @end deffn
+ 
+ @deffn 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, or the function
+ is called interactively, it is treated as the detached signature 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.
+ @end deffn
+ 
+ @deffn Command pgg-insert-key
+ Retrieve the user's public key and insert it as ASCII-armored format.
+ @end deffn
+ 
+ @deffn Command pgg-snarf-keys-region start end
+ Collect public keys in the current region between @var{start} and
+ @var{end}, and add them into the user's keyring.
+ @end deffn
+ 
+ @node Selecting an implementation
+ @section 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.
+ 
+ By default, if the variable @code{pgg-scheme} is not set, PGG searches the
+ registered scheme for an implementation of the requested service
+ associated with the named algorithm.  If there are no match, PGG uses
+ @code{pgg-default-scheme}.  In other words, there are two options to
+ control which command is used to process the incoming PGP armors.  One
+ is for encrypting and signing, the other is for decrypting and
+ verifying.
+ 
+ @defvar pgg-scheme
+ Force specify the scheme of PGP implementation for decrypting and verifying.
+ The value can be @code{gpg}, @code{pgp}, and @code{pgp5}.
+ @end defvar
+ 
+ @defvar pgg-default-scheme
+ Force specify the scheme of PGP implementation for encrypting and signing.
+ The value can be @code{gpg}, @code{pgp}, and @code{pgp5}.
+ @end defvar
+ 
+ @node Caching passphrase
+ @section Caching passphrase
+ 
+ PGG provides a simple passphrase caching mechanism.  If you want to
+ arrange the interaction, set the variable @code{pgg-read-passphrase}.
+ 
+ @defvar pgg-cache-passphrase
+ If address@hidden, store passphrases.  The default value of this
+ variable is @code{t}.  If you were worry about security issue, however,
+ you could stop caching with setting it @code{nil}.
+ @end defvar
+ 
+ @defvar pgg-passphrase-cache-expiry
+ Elapsed time for expiration in seconds.
+ @end defvar
+ 
+ @node Default user identity
+ @section 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.
+ 
+ @defvar 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.
+ @end defvar
+ 
+ @defvar 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.
+ @end defvar
+ 
+ @defvar pgg-pgp-user-id
+ User ID of the PGP 2.x/6.x default identity.  It defaults to
+ @samp{nil}.  This overrides @samp{pgg-default-user-id}.  You can
+ customize this variable.
+ @end defvar
+ 
+ @defvar 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.
+ @end defvar
+ 
+ @node Architecture
+ @chapter 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.
+ 
+ @menu
+ * Initializing::                
+ * Backend methods::             
+ * Getting output::              
+ @end menu
+ 
+ @node Initializing
+ @section 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.
+ 
+ @lisp
+ (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))))
+ @end lisp
+ 
+ The name of the function must follow the
+ address@hidden follows the backend name.
+ 
+ @node Backend methods
+ @section 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.
+ 
+ @deffn 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.
+ @end deffn
+ 
+ @deffn Method pgg-scheme-encrypt-region scheme start end recipients &optional 
sign
+ Encrypt the current region between @var{start} and @var{end} for
+ @var{recipients}.  If @var{sign} is non-nil, do a combined sign and
+ encrypt.  If encryption is successful, it returns @code{t}, otherwise
+ @code{nil}.
+ @end deffn
+ 
+ @deffn Method pgg-scheme-decrypt-region scheme start end
+ Decrypt the current region between @var{start} and @var{end}.  If
+ decryption is successful, it returns @code{t}, otherwise @code{nil}.
+ @end deffn
+ 
+ @deffn Method pgg-scheme-sign-region scheme start end &optional cleartext
+ 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
+ @code{t}, otherwise @code{nil}.
+ @end deffn
+ 
+ @deffn 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}.
+ @end deffn
+ 
+ @deffn 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}.
+ @end deffn
+ 
+ @deffn Method pgg-scheme-snarf-keys-region scheme start end
+ Collect public keys in the current region between @var{start} and
+ @var{end}, and add them into the user's keyring.
+ On success, it returns @code{t}, otherwise @code{nil}.
+ @end deffn
+ 
+ @node Getting output
+ @section 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.
+ 
+ @defvar pgg-errors-buffer
+ The standard error output of the execution of the PGP command is stored
+ here.
+ @end defvar
+ 
+ @defvar pgg-output-buffer
+ The standard output of the execution of the PGP command is stored here.
+ @end defvar
+ 
+ @defvar pgg-status-buffer
+ The rest of status information of the execution of the PGP command is
+ stored here.
+ @end defvar
+ 
+ @node Parsing OpenPGP packets
+ @chapter 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.
+ 
+ @defun pgg-parse-armor string
+ List the sequence of packets in @var{string}.
+ @end defun
+ 
+ @defun pgg-parse-armor-region start end
+ List the sequence of packets in the current region between @var{start}
+ and @var{end}.
+ @end defun
+ 
+ @defvar pgg-ignore-packet-checksum
+ If address@hidden, don't check the checksum of the packets.
+ @end defvar
+ 
+ @node Function Index
+ @chapter Function Index
+ @printindex fn
+ 
+ @node Variable Index
+ @chapter Variable Index
+ @printindex vr
+ 
+ @summarycontents
+ @contents
+ @bye
+ 
+ @c End:
+ 
+ @ignore
+    arch-tag: 0c205838-34b9-41a5-b9d7-49ae57ccac85
+ @end ignore