This file describes the PGG.

Copyright (C) 2003, 2004, 2005 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
===========================

PGP は歴史が長く、今では多くの実装を利用することができるので、それぞれが持っている個々の機能がずいぶん異なっていることがあります。例えば、あなたが GnuPG をお使いなら、暗号アルゴリズムに 3DES や CAST5、BLOWFISH などを選ぶことができるが、PGP のバージョン 2 では IDEA しかサポートされていないことをご存じでしょう。

デフォルトでは、pgg-scheme 変数が設定されていなければ、PGG はあらかじめ用意されたスキーム (scheme) から、用いたい暗号アルゴリズムに必要なサービスの実装を検索します。言い換えれば、やってくる PGP 武装を処理するのにどのコマンドを使うかを制御するための 2 つのオプションがあります。 1つは暗号化と署名について、もう一方は復号化と検証について、です。

 -- Variable: pgg-scheme
     復号化と検証にどの PGP 実装を用いるかを強制します。設定できるのは gpg、pgp および pgp5 のどれかです。

 -- Variable: pgg-default-scheme
     暗号化と署名にどの PGP 実装を用いるかを強制します。設定できるのは gpg、pgp および pgp5 のどれかです。

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

PGG はパスフレーズをキャッシュしておくのに単純なメカニズムを使います。これがデフォルトです。

 -- Variable: pgg-cache-passphrase
     non-nil でなければ、パスフレーズを保持します。初期値は t です。しかし、あなたがセキュリティについて気掛かりなら、これを nil に設定してやれば、パスフレーズの保持をやめさせることができます。

 -- Variable: pgg-passphrase-cache-expiry
     パスフレーズを保持しておく時間を秒で指定します。

Default user identity
=====================

PGP の実装は、通常、暗号化および復号化に使う適切な鍵を選ぶことができますが、あなたが1つ以上の鍵を持っている場合、用いる鍵の id を指定する必要があります。

 -- Variable: pgg-default-user-id
     あなた自身の通常用いるユーザ ID です。指定しない場合、初期値は (user-login-name) の戻値で決定されます。カスタマイズ可能です。

 -- Variable: pgg-gpg-user-id
     GnuPG で使うあなた自身のユーザ ID です。デフォルトは nil です。この値は pgg-default-user-id を上書きします。カスタマイズ可能です。

 -- Variable: pgg-pgp-user-id
     PGP 2.x/6.x で使うあなた自身のユーザ ID です。デフォルトは nil です。この値は pgg-default-user-id を上書きします。カスタマイズ可能です。

 -- Variable: pgg-pgp5-user-id
     PGP 5.x で使うあなた自身のユーザ ID です。デフォルトは nil です。この値は pgg-default-user-id を上書きします。カスタマイズ可能です。

Architecture
************

PGG は「PGP 実装のスキーム(枠組)」という考えを導入します。以後、「スキーム (scheme)」と表記します。この用語は luna object system での singleton object に由来します。

PGG は PGP の機能にアクセスできると同時にそれを開発するために設計されたので、その基本設計では、相互運用性だけでなく拡張性も考えないといけません。この章では、PGG のバックエンドをどのように記述するかを探しながら、PGG がどのようにつくられているかを探検してみましょう。

Initializing
============

スキームは、使う前に初期化されなければなりません。ただひとつのスキームを保つよう保証するのがよいでしょう。

以下のコードは pgg-gpg.el からの抜き書きです。一旦、ある pgg-gpg のスキームが初期化されると、それは pgg-scheme-gpg-instance 変数に保存され、以後、再利用されます。

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

関数の名前は pgg-make-scheme- の後ろにバックエンド名が付加するように付けられなければなりません。

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

各バックエンドにはメソッドが存在しなければなりません。メソッドの実行結果のステータスを知らせなければならないので、メソッドの出力は特別なバッファに保存されます(Getting output)。

 -- Method: pgg-scheme-lookup-key scheme string &optional type
     STRING に関連づけられた鍵を返します。 3番目のオプション引数 TYPE が non-nil ならば、秘密鍵輪から検索します。

 -- Method: pgg-scheme-encrypt-region scheme start end recipients &optional sign
     RECIPIENTS宛のメッセージについて、STARTとENDの間で指定された現在の範囲を暗号化します。オプション引数 SIGN が non-nil ならば、署名と暗号化が同時に行われます。暗号化に成功すると t を、失敗すると nil を返します。

 -- Method: pgg-scheme-decrypt-region scheme start end
     STARTとENDの間で指定された現在の範囲を復号化します。復号化に成功すると t を、失敗すると nil を返します。

 -- Method: pgg-scheme-sign-region scheme start end &optional cleartext
     STARTとENDの間のテキストに署名します。3番目のオプション引数 CLEARTEXT が non-nil であるか、あるいは対話的に呼ばれた場合、分離された署名は作られません。署名に成功すると t を、失敗すると nil を返します。

 -- Method: pgg-scheme-verify-region scheme start end &optional signature
     STARTとENDの間の範囲を検査します。3番目のオプション引数 SIGNATURE が non-nil である場合、分離された署名として取り扱われます。署名が正しく検証された場合、t を、失敗すると nilを返します。

 -- Method: pgg-scheme-insert-key scheme
     ユーザの公開鍵を取得して、ASCII-armored フォーマットで挿入します。成功すると t を、失敗すると nil を返します。

 -- Method: pgg-scheme-snarf-keys-region scheme start end
     STARTとENDの間の範囲にある公開鍵を集め、ユーザの鍵輪 (keyring) に追加します。成功すると t を、失敗すると nil を返します。

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

バックエンドメソッド (Back end methods) の出力は特別なバッファに保存されます。したがって、これらのメソッドは実行結果を伝える必要があります。

 -- Variable: pgg-errors-buffer
     PGP コマンド実行時の標準エラー出力は、このバッファに保存されます。

 -- Variable: pgg-output-buffer
     PGP コマンド実行時の標準出力は、このバッファに保存されます。

 -- Variable: pgg-status-buffer
     PGP コマンド実行時のその他の結果情報は、このバッファに保存されます。

Parsing OpenPGP packets
***********************

OpenPGP のメッセージのフォーマットは、相互運用できるアプリケーション開発に必要なすべての情報を出力するように維持されています。その標準は、RFC2440 に記載されています。

PGG は OpenPGP に対応した独自のメッセージ解析を行います。

 -- Function: pgg-parse-armor string
     STRING 内のパケットの並びを一覧します。

 -- Function: pgg-parse-armor-region start end
     STARTとENDの間の範囲内のパケットの並びを一覧します。

 -- Variable: pgg-ignore-packet-checksum
     non-nil ならば、パケットのチェックサムを検証しません。