This is pgg.info, produced by makeinfo version 4.2 from pgg.texi.

START-INFO-DIR-ENTRY
* PGG: (pgg).   Emacs interface to various PGP implementations.
END-INFO-DIR-ENTRY

   This file describes the PGG.

   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".


File: pgg.info,  Node: Top,  Next: Overview,  Up: (dir)

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::


File: pgg.info,  Node: Overview,  Next: Prerequisites,  Prev: Top,  Up: Top

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.


File: pgg.info,  Node: Prerequisites,  Next: How to use,  Prev: Overview,  Up: Top

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
recomend that you should look over the GNU Privacy Handbook (GPH) which
is available at `http://www.gnupg.org/gph/'.


File: pgg.info,  Node: How to use,  Next: Architecture,  Prev: Prerequisites,  Up: Top

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.

     (require 'pgg)

   If you want to check existence of pgg.el at runtime, instead you can
list autoload setting for desired functions as follows.

     (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)

* Menu:

* User Commands::
* Selecting an implementation::
* Caching passphrase::


File: pgg.info,  Node: User Commands,  Next: Selecting an implementation,  Up: How to use

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 `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.

 - Command: pgg-encrypt-region start end recipients &optional sign
     Encrypt the current region between START and END for 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 SIGN is non-nil, the function is request to
     do a combined sign and encrypt.  This currently only work with
     GnuPG.

 - Command: pgg-decrypt-region start end
     Decrypt the current region between START and END.  If decryption
     is successful, it replaces the current region contents (in the
     accessible portion) with the resulting data.

 - Command: pgg-sign-region start end &optional cleartext
     Make the signature from text between START and END.  If the
     optional third argument CLEARTEXT is non-`nil', 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.

 - Command: pgg-verify-region start end &optional signature fetch
     Verify the current region between START and END.  If the optional
     third argument SIGNATURE is non-`nil', or the function is called
     interactively, it is treated as the detached signature of the
     current region.

     If the optional 4th argument FETCH is non-`nil', or the function
     is called interactively, we attempt to fetch the signer's public
     key from the key server.

 - Command: pgg-insert-key
     Retrieve the user's public key and insert it as ASCII-armored
     format.

 - Command: pgg-snarf-keys-region start end
     Collect public keys in the current region between START and END,
     and add them into the user's keyring.


File: pgg.info,  Node: Selecting an implementation,  Next: Caching passphrase,  Prev: User Commands,  Up: How to use

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 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
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.

 - Variable: pgg-scheme
     Force specify the scheme of PGP implementation for decrypting and
     verifying.  The value can be `gpg', `pgp', and `pgp5'.

 - Variable: pgg-default-scheme
     Force specify the scheme of PGP implementation for encrypting and
     signing.  The value can be `gpg', `pgp', and `pgp5'.


File: pgg.info,  Node: Caching passphrase,  Prev: Selecting an implementation,  Up: How to use

Caching passphrase
==================

   PGG provides a simple passphrase caching mechanism.  If you want to
arrange the interaction, set the variable PGG-READ-PASSPHRASE.

 - Variable: pgg-cache-passphrase
     If non-`nil', store passphrases.  The default value of this
     variable is `t'.  If you were worry about security issue, however,
     you could stop caching with setting it `nil'.

 - Variable: pgg-passphrase-cache-expiry
     Elapsed time for expiration in seconds.


File: pgg.info,  Node: Architecture,  Next: Parsing OpenPGP packets,  Prev: How to use,  Up: Top

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
interoperablity 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::


File: pgg.info,  Node: Initializing,  Next: Backend methods,  Up: Architecture

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 `pgg-gpg.el'.  Once an instance
of `pgg-gpg' scheme is initialized, it's stored to the variable
PGG-SCHEME-GPG-INSTANCE and will be reused from now on.

     (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))))

   The name of the function must follow the
regulation--`pgg-make-scheme-' follows the backend name.


File: pgg.info,  Node: Backend methods,  Next: Getting output,  Prev: Initializing,  Up: Architecture

Backend methods
===============

   In each backend, these methods must be present.  The output of these
methods is stored in special buffers (*Note Getting output::), so that
these methods must tell the status of the execution.

 - Method: pgg-scheme-lookup-key scheme string &optional type
     Return keys associated with STRING.  If the optional third
     argument TYPE is non-`nil', it searches from the secret keyrings.

 - Method: pgg-scheme-encrypt-region scheme start end recipients
          &optional sign
     Encrypt the current region between START and END for RECIPIENTS.
     If SIGN is non-nil, do a combined sign and encrypt.  If encryption
     is successful, it returns `t', otherwise `nil'.

 - Method: pgg-scheme-decrypt-region scheme start end
     Decrypt the current region between START and END.  If decryption
     is successful, it returns `t', otherwise `nil'.

 - Method: pgg-scheme-sign-region scheme start end &optional cleartext
     Make the signature from text between START and END.  If the
     optional third argument CLEARTEXT is non-`nil', it does not create
     a detached signature.  If signing is successful, it returns `t',
     otherwise `nil'.

 - Method: pgg-scheme-verify-region scheme start end &optional signature
     Verify the current region between START and END.  If the optional
     third argument SIGNATURE is non-`nil', it is treated as the
     detached signature of the current region.  If the signature is
     successflly verified, it returns `t', otherwise `nil'.

 - Method: pgg-scheme-insert-key scheme
     Retrieve the user's public key and insert it as ASCII-armored
     format.  On success, it returns `t', otherwise `nil'.

 - Method: pgg-scheme-snarf-keys-region scheme start end
     Collect public keys in the current region between START and END,
     and add them into the user's keyring.  On success, it returns `t',
     otherwise `nil'.


File: pgg.info,  Node: Getting output,  Prev: Backend methods,  Up: Architecture

Getting output
==============

   The output of the backend methods (*Note Backend methods::) is
stored in special buffers, so that these methods must tell the status
of the execution.

 - Variable: pgg-errors-buffer
     The standard error output of the execution of the PGP command is
     stored here.

 - Variable: pgg-output-buffer
     The standard output of the execution of the PGP command is stored
     here.

 - Variable: pgg-status-buffer
     The rest of status information of the execution of the PGP command
     is stored here.


File: pgg.info,  Node: Parsing OpenPGP packets,  Next: Function Index,  Prev: Architecture,  Up: Top

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.

 - Function: pgg-parse-armor string
     List the sequence of packets in STRING.

 - Function: pgg-parse-armor-region start end
     List the sequence of packets in the current region between START
     and END.

 - Variable: pgg-ignore-packet-checksum
     If non-`nil', don't check the checksum of the packets.


File: pgg.info,  Node: Function Index,  Next: Variable Index,  Prev: Parsing OpenPGP packets,  Up: Top

Function Index
**************

* Menu:

* pgg-decrypt-region:                    User Commands.
* pgg-encrypt-region:                    User Commands.
* pgg-insert-key:                        User Commands.
* pgg-parse-armor:                       Parsing OpenPGP packets.
* pgg-parse-armor-region:                Parsing OpenPGP packets.
* pgg-scheme-decrypt-region:             Backend methods.
* pgg-scheme-encrypt-region:             Backend methods.
* pgg-scheme-insert-key:                 Backend methods.
* pgg-scheme-lookup-key:                 Backend methods.
* pgg-scheme-sign-region:                Backend methods.
* pgg-scheme-snarf-keys-region:          Backend methods.
* pgg-scheme-verify-region:              Backend methods.
* pgg-sign-region:                       User Commands.
* pgg-snarf-keys-region:                 User Commands.
* pgg-verify-region:                     User Commands.


File: pgg.info,  Node: Variable Index,  Prev: Function Index,  Up: Top

Variable Index
**************

* Menu:

* pgg-cache-passphrase:                  Caching passphrase.
* pgg-default-scheme:                    Selecting an implementation.
* pgg-errors-buffer:                     Getting output.
* pgg-ignore-packet-checksum:            Parsing OpenPGP packets.
* pgg-output-buffer:                     Getting output.
* pgg-passphrase-cache-expiry:           Caching passphrase.
* pgg-scheme:                            Selecting an implementation.
* pgg-status-buffer:                     Getting output.



Tag Table:
Node: Top623
Node: Overview1170
Node: Prerequisites1659
Node: How to use2220
Node: User Commands3285
Node: Selecting an implementation5695
Node: Caching passphrase6935
Node: Architecture7517
Node: Initializing8168
Node: Backend methods8896
Node: Getting output10921
Node: Parsing OpenPGP packets11550
Node: Function Index12250
Node: Variable Index13271

End Tag Table
