* epg.el (epg-make-verify-result): Renamed epg-signature to
[elisp/semi.git] / pgg.texi
index 0f07f15..cbb305a 100644 (file)
--- a/pgg.texi
+++ b/pgg.texi
@@ -13,7 +13,7 @@
 @ifinfo
 This file describes the PGG.
 
 @ifinfo
 This file describes the PGG.
 
-Copyright (C) 2000 Daiki Ueno.
+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
 
 Permission is granted to copy, distribute and/or modify this document
 under the terms of the GNU Free Documentation License, Version 1.1 or
@@ -32,7 +32,7 @@ Free Documentation License".
 @page
 
 @vskip 0pt plus 1filll
 @page
 
 @vskip 0pt plus 1filll
-Copyright @copyright{} 2000 Daiki Ueno.
+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
 
 Permission is granted to copy, distribute and/or modify this document
 under the terms of the GNU Free Documentation License, Version 1.1 or
@@ -53,8 +53,8 @@ user interface to encrypt, decrypt, sign, and verify MIME messages.
 
 @menu
 * Overview::                    What PGG is.
 
 @menu
 * Overview::                    What PGG is.
-* Prerequisites::               
-* How to use::                  Calling PGP from your applications.
+* Prerequisites::               Complicated stuff you may have to do.
+* How to use::                  Getting started quickly.
 * Architecture::                
 * Parsing OpenPGP packets::     
 * Function Index::              
 * Architecture::                
 * Parsing OpenPGP packets::     
 * Function Index::              
@@ -79,26 +79,26 @@ 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.
 
 This document assumes that you have already obtained and installed them
 and that you are familiar with its basic functions.
 
-By default, PGG assumes to use GnuPG, but Pretty Good Privacy version 2
-or version 5 are also supported.  If you are new to such a system, I
-recomend that you should look over the `GNU Privacy Handbook (GPH)',
-which is available at @uref{http://www.gnupg.org/gph/}.
+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 recomend 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
 
 
 @node How to use
 @chapter How to use
 
-The toplevel interface of this library is still simple, and only
+The toplevel interface of this library is quite simple, and only
 intended to use with public-key cryptographic operation.
 
 intended to use with public-key cryptographic operation.
 
-To use PGG, please evaluate following expression at the beginning of
-your application program.
+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
 
 @lisp
 (require 'pgg)
 @end lisp
 
 If you want to check existence of pgg.el at runtime, instead you can
-list autoload settings for functions you want as follows.
+list autoload setting for desired functions as follows.
 
 @lisp
 (autoload 'pgg-encrypt-region "pgg"
 
 @lisp
 (autoload 'pgg-encrypt-region "pgg"
@@ -124,13 +124,12 @@ list autoload settings for functions you want as follows.
 @node User Commands
 @section User Commands
 
 @node User Commands
 @section User Commands
 
-At this time you can use various cryptographic commands.  The behavior
-of these commands relies on the fashion of invocation because these
-commands are also intended to be used as library functions.  For
-example, in case you don't have the signer's public key, the function
-`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.
+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
 Encrypt the current region between @var{start} and @var{end} for
 
 @deffn Command pgg-encrypt-region start end recipients
 Encrypt the current region between @var{start} and @var{end} for
@@ -188,7 +187,7 @@ By default, if the variable @var{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
 @var{pgg-default-scheme}.  In other words, there are two options to
 registered scheme for an implementation of the requested service
 associated with the named algorithm.  If there are no match, PGG uses
 @var{pgg-default-scheme}.  In other words, there are two options to
-controll which command is used to process the incoming PGP armors.  One
+control which command is used to process the incoming PGP armors.  One
 is for encrypting and signing, the other is for decrypting and
 verifying.
 
 is for encrypting and signing, the other is for decrypting and
 verifying.
 
@@ -211,11 +210,11 @@ arrange the interaction, set the variable @var{pgg-read-passphrase}.
 @defvar pgg-cache-passphrase
 If non-@code{nil}, store passphrases.  The default value of this
 variable is @code{t}.  If you were worry about security issue, however,
 @defvar pgg-cache-passphrase
 If non-@code{nil}, store passphrases.  The default value of this
 variable is @code{t}.  If you were worry about security issue, however,
-you could stop caching.
+you could stop caching with setting it @code{nil}.
 @end defvar
 
 @defvar pgg-passphrase-cache-expiry
 @end defvar
 
 @defvar pgg-passphrase-cache-expiry
-The elapsed time for expiration in seconds.
+Elapsed time for expiration in seconds.
 @end defvar
 
 @node Architecture
 @end defvar
 
 @node Architecture
@@ -234,6 +233,7 @@ while finding out how to write the PGG backend.
 * Initializing::                
 * Backend methods::             
 * Getting output::              
 * Initializing::                
 * Backend methods::             
 * Getting output::              
+* Registering backend::         
 @end menu
 
 @node Initializing
 @end menu
 
 @node Initializing
@@ -328,6 +328,55 @@ The rest of status information of the execution of the PGP command is
 stored here.
 @end defvar
 
 stored here.
 @end defvar
 
+@node Registering backend
+@section Registering backend
+
+When decrypting and verifying PGG searches the registered scheme for an
+implementation from @var{pgg-verify-condition} and
+@var{pgg-decrypt-condition}.  These variable hold capability information
+of backend implementations.
+
+The @code{gpg} backend, for example, is registered as below:
+
+@lisp
+(ctree-set-calist-strictly
+ 'pgg-verify-condition
+ '((signature-version 3 4)
+   (public-key-algorithm ELG-E DSA ELG)
+   (hash-algorithm MD5 SHA1 RIPEMD160)
+   (scheme . gpg)))
+
+(ctree-set-calist-strictly
+ 'pgg-decrypt-condition
+ '((public-key-algorithm ELG-E DSA ELG)
+   (symmetric-key-algorithm 3DES CAST5 BLOWFISH TWOFISH)
+   (scheme . gpg)))
+@end lisp
+
+The former expression says:
+
+@itemize
+@item
+the backend @code{gpg} supports version 3 and 4 of the signature format
+@item
+the backend @code{gpg} supports ELG-E, DSA, and ELG as public-key
+algorithm for signing
+@item
+the backend @code{gpg} supports MD5, SHA1, and RIPEMD160 as hash
+algorithm for signing
+@end itemize
+
+And the latter expression says:
+
+@itemize
+@item
+the backend @code{gpg} supports ELG-E, DSA, and ELG as public-key
+algorithm for decrypting
+@item
+the backend @code{gpg} supports 3DES, CAST5, BLOWFISH, and TWOFISH as
+cipher algorithm for decrypting.
+@end itemize
+
 @node Parsing OpenPGP packets
 @chapter Parsing OpenPGP packets
 
 @node Parsing OpenPGP packets
 @chapter Parsing OpenPGP packets