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

     この文書を、フリーソフトウェア財団発行の GNU フリー文書利用許諾契約書第 1.1 版またはそれ以降の版が定める条件の下で複製、配布、あるいは変更することを許可します。変更不可部分、表表紙テキストおよび裏表紙テキストは指定しません。この利用許諾契約書の複写は「GNU フリー文書利用許諾契約書」という章に含まれています。

PGG
***

これは PGG のマニュアルです。PGG は、安全な通信のための様々なツールと Emacs の仲を取り持つインタフェースです。また、PGG は、MIME メッセージの暗号化、復号化、署名、検証のための単純なユーザインタフェースも提供します。

Overview
********

PGG は、安全な通信のための様々なツールと Emacs の仲を取り持つインタフェースです。同様の機能は Mailcrypt も持っていますが、Mailcrypt は PGP/MIME のインフラで通常用いられる分離された PGP メッセージを取り扱うことができません。これが、私(作者)が新しいライブラリを書いた主な理由です。

PGP/MIME は MIME Object Security Services (RFC1848) の実装です。その標準は RFC2015 で記述されています。

Prerequisites
*************

PGG を使うためには少なくとも1つのプライバシー保護システムの実装が必要です。このマニュアルでは、あなたがそのようなプログラムをすでに取得、インストールしていて、基本的な使い方を知っていることを仮定します。

ディフォルトでは、PGG は GnuPG を使います。しかし、PGP (Pretty Good Privacy) のバージョン2または5もサポートします。もし、あなたがこのようなシステムに慣れていないのであれば、GNU Privacy Handbook (GPH) を先に読まれることをお薦めします。GPH は、http://www.gnupg.org/gph/ で見ることができます。

How to use
**********

このライブラリの最上位インタフェースはとても単純で、公開鍵による暗号の操作のみを想定しています。

PGG を使うためには、あなたのアプリケーションプログラムの冒頭で次の S 式を評価します。

     (require 'pgg)

あなたが pgg.el の存在を確認したいなら、上記の方法ではなく以下のように、必要な機能について autoload のリストを設定することもできます。

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

User Commands
=============

この時点で、あなたはいくつかの暗号に関するコマンドを使うことができます。これらのコマンドの挙動は起動方法に依存します。これらのコマンドはライブラリ関数として利用されることもあるからです。例えば、あなたがある署名者の公開鍵を持っていないとき、pgg-verify-region という関数は即座に失敗しますが、これが対話的に呼び出された場合には、サーバから公開鍵をダウンロードするかどうか、あなたに確認します。

 -- Command: pgg-encrypt-region start end recipients &optional sign
     RECIPIENTS宛のメッセージについて、STARTとENDの間で指定された現在の範囲を暗号化します。対話的に呼ばれると、受信者を聞かれます。

     暗号化に成功すると、現在の範囲の内容が(可能な部分について)暗号化された内容に置き換えられます。

     オプション引数 SIGN が non-nil ならば、署名と暗号化が同時に行われます。現在、この機能は GnuPG でだけ動作します。

 -- Command: pgg-decrypt-region start end
     STARTとENDの間で指定された現在の範囲を復号化します。復号化に成功すると、現在の範囲の内容が(可能な部分について)復号化された内容に置き換えられます。

 -- Command: pgg-sign-region start end &optional cleartext
     STARTとENDの間のテキストに署名します。3番目のオプション引数 CLEARTEXT が non-nil であるか、あるいは対話的に呼ばれた場合、分離された署名は作られません。そのような場合、現在の範囲の内容が(可能な部分について)署名された結果に置き換えられます。

 -- Command: pgg-verify-region start end &optional signature fetch
     STARTとENDの間の範囲を検査します。3番目のオプション引数 SIGNATURE が non-nil であるか、あるいは対話的に呼ばれた場合、分離された署名として取り扱われます。

     4番目のオプション引数 FETCH が non-nil であるか、あるいは対話的に呼ばれた場合、公開鍵をサーバから取得します。

 -- Command: pgg-insert-key
     ユーザの公開鍵を取得して、ASCII-armored フォーマットで挿入します。

 -- Command: pgg-snarf-keys-region start end
     STARTとENDの間の範囲にある公開鍵を集め、ユーザの鍵輪 (keyring)に追加します。

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.

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.

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.

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

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 back end name.

Back end methods
================

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

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

The output of the back end methods (Back end 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.

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.