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

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".
   
INFO-DIR-SECTION Emacs
START-INFO-DIR-ENTRY
* PGG: (pgg).   Emacs interface to various PGP implementations.
END-INFO-DIR-ENTRY


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
recommend 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::
* Default user identity::


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,  Next: Default user identity,  Prev: Selecting an implementation,  Up: How to use

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.


File: pgg.info,  Node: Default user identity,  Prev: Caching passphrase,  Up: How to use

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.


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


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


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-default-user-id:                   Default user identity.
* pgg-errors-buffer:                     Getting output.
* pgg-gpg-user-id:                       Default user identity.
* pgg-ignore-packet-checksum:            Parsing OpenPGP packets.
* pgg-output-buffer:                     Getting output.
* pgg-passphrase-cache-expiry:           Caching passphrase.
* pgg-pgp-user-id:                       Default user identity.
* pgg-pgp5-user-id:                      Default user identity.
* pgg-scheme:                            Selecting an implementation.
* pgg-status-buffer:                     Getting output.



Tag Table:
Node: Top730
Node: Overview1274
Node: Prerequisites1760
Node: How to use2320
Node: User Commands3408
Node: Selecting an implementation5817
Node: Caching passphrase7058
Node: Default user identity7613
Node: Architecture8646
Node: Initializing9295
Node: Backend methods10022
Node: Getting output12047
Node: Parsing OpenPGP packets12673
Node: Function Index13370
Node: Variable Index14391

End Tag Table
