This file describes the PGG.

   Copyright (C) 2003, 2004 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".

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.

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

2 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 <http://www.gnupg.org/gph/>.

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

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

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

3.3 Caching passphrase
======================

PGG uses a simple passphrase caching mechanism, which is enabled by
default.

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

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

 -- Variable: pgg-default-user-id
     User ID of your default identity.  It defaults to the value
     returned by '(user-login-name)'.  You can customize this variable.

 -- Variable: pgg-gpg-user-id
     User ID of the GnuPG default identity.  It defaults to 'nil'.  This
     overrides 'pgg-default-user-id'.  You can customize this variable.

 -- Variable: pgg-pgp-user-id
     User ID of the PGP 2.x/6.x default identity.  It defaults to 'nil'.
     This overrides 'pgg-default-user-id'.  You can customize this
     variable.

 -- Variable: pgg-pgp5-user-id
     User ID of the PGP 5.x default identity.  It defaults to 'nil'.
     This overrides 'pgg-default-user-id'.  You can customize this
     variable.

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

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

4.2 Backend methods
===================

In each backend, these methods must be present.  The output of these
methods is stored in special buffers (see 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
     successfully 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'.

4.3 Getting output
==================

The output of the backend methods (see 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.

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