Emacs auth-source
*****************

このマニュアルは Emacs auth-source ライブラリーを説明します。

利用者の便宜のために、複数のアプリケーションで、(Emacs またはファイルにある) 一つの設定を共有するための手段です。

このファイルは Emacs auth-source ライブラリーを説明します。

Copyright © 2008, 2009 Free Software Foundation, Inc.

     Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, with the Front-Cover texts being ``A GNU Manual,'' and with the Back-Cover Texts as in (a) below.  A copy of the license is included in the section entitled ``GNU Free Documentation License'' in the Emacs manual.

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

     (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and modify this GNU manual.  Buying copies from the FSF supports it in developing GNU and promoting software freedom.''

     (a) FSF の裏表紙テキスト:「あなたにはこの GNU Manual を複製したり変更する自由があります。FSF からの複写の購入は GNU の開発とソフトウェアの自由の促進を支援します。」

     This document is part of a collection distributed under the GNU Free Documentation License.  If you want to distribute this document separately from the collection, you can do so by adding a copy of the license to the document, as described in section 6 of the license.

     この文書は「GNU フリー文書利用許諾契約書」に基づいて配布された収集著作物の一部です。もしあなたがこの文書を収集著作物から分離して配布したいときは、契約書の第 6 項に記述されているように、文書に契約書の複写を付加することによって、行なうことができます。

概要
**

auth-source は先進的で拡張性があり、エンタープライズ級の認証ライブラリーです。最新のデザインパターンを使用、1800 の単体デストを有し、21 の工業会の基調講演で取り上げられました。将来性があり、バグが無いことが数学的に証明されていて、メモリーを食い潰すための 6つの XML 解析器を内蔵しています。

ほんの冗談ですよ。auth-source ライブラリーは、「サーバー名とポートはわかってるんだけど、ユーザー名とパスワードは何だっけ?」という昔ながらの熱烈な問いへの答を見つけるための、Emacs と Gnus 用の数ある単純な手段の一つです。

実際には auth-source ライブラリーは単なるユーザー名 (いわゆる login) とパスワード以外のものも扱うことができますが、今日の Emacs と Gnus ではそれら 2つだけが使われています。同様に、auth-source ライブラリーは理論的には多くの記録形式を扱うことができますが、今のところ伝統的な ``netrc'' 形式 (この文書の後の方にあります) しか理解しません。

利用者のためのヘルプ
**********

``Netrc'' ファイルは事実上の標準です。それらはこのようになっています:

     machine mymachine login myloginname password mypassword port myport

ポートの指定は無くても構いません。無い場合、auth-source はどんなポートも OK なのだと解釈します。実際のところ、ポートはプロトコルの名前かポート番号のどちらでも良いので、もしそうしたいのならば、ポート 143 とプロトコル ``imap'' のための項目を別々に持つことができます。ともあれ、もしポートの指定が要らない場合は省略しても構いません。``Netrc'' ファイルは通常 .authinfo または .netrc と呼ばれます。今では .authinfo の方が普及しているようなので、後でわかるように auth-source ライブラリーはそれをディフォルトにすることによって、この混乱を助長しています。

もしポートで問題があるのなら AUTH-SOURCE-DEBUG を t に設定して、ライブラリーがどのポートをチェックしているかを *Messages* バッファーで見てください。同様に他のどんな問題についても、何がチェックされているかを調べるのが、あなたの第 1歩です。第2 のステップはもちろんそれについての blog を書いて、コメントで回答を待つことです。

変数 AUTH-SOURCES をカスタマイズすることができます。もし古いバージョンの Emacs を使っているか、何かの理由のために auth-source ライブラリーが読み込まれない場合、次のものが必要になるでしょう。

     (require 'auth-source)             ;; おそらく不要
     (customize-variable 'auth-sources) ;; 任意、一回だけ行なってください

 -- Variable: auth-sources
     AUTH-SOURCES 変数は、個々のホストとプロトコルのための netrc ファイルがどこに在るかを auth-source ライブラリーに知らせます。好みに応じてどうにでもできますが、ディフォルトの最も簡潔な設定は次の通りです:

          (setq auth-sources '((:source "~/.authinfo.gpg" :host t :protocol t)))

     これは「どんなホストのどのポートでも、この単一のファイルを使う」という意味です。素晴らしく簡単でしょう。実際これはすでにディフォルトになっているので、そのファイルがあれば、これは機能します。あなたが netrc ファイルを移設しない限り。

     特定のホストかプロトコルのエントリーを複数 AUTH-SOURCES に追加することによって、そのホストかプロトコルに特化した netrc ファイルを持つことができます。普通これは必要ありませんが、netrc ファイルを共有したり変わった設定がある場合は意味があるかもしれません (90% の Emacs ユーザーは変な設定を持っていて、残りの 10% は 本当に 変わっています)。

もし AUTH-SOURCES をカスタマイズしないと、ディフォルトで生活することになるでしょう。そのディフォルトとは、どんなホストもポートについても netrc ファイル ~/.authinfo.gpg を参照するということです。これは暗号化されたファイルです。EPA を使えるようにしている場合に限りますが、それが強く推奨されます。

     (require 'epa-file)
     (epa-file-enable)
     ;;; 対称暗号が必要ならとても重要
     ;;; そうでなければ無意味
     (setq epa-file-cache-passphrase-for-symmetric-encryption t)

実際に使える最も簡単な netrc 行の例は、ポートが無いものです。

     machine YOURMACHINE login YOU password YOURPASSWORD

これはどの認証ポートにも対応します。簡単でしょう?  でも SMTP サーバーが IMAP サーバーと異なるパスワードを必要とするそのマシンのポート 433 にあるならば、どうですか？

     machine YOURMACHINE login YOU password SMTPPASSWORD port 433
     machine YOURMACHINE login YOU password GENERALPASSWORD

url-auth 認証 (HTTP/HTTPS) のためには、これを netrc ファイルに置いておく必要があります:

     machine yourmachine.com:80 port http login testuser password testpass

これは HTTP で接続するどんな界面と認証方式 (basic または digest) にも対応します。HTTPS も同様に設定します。もっときめ細かい制御が必要なら、 url-auth のソースコードと変数を調べてください。

Tramp の認証にはこれを使ってください:

     machine yourmachine.com port scp login testuser password testpass

ポートは Tramp の接続方法を意味することに注意してください。もしポートの項を使わなければ、最初の方で説明したように、すべての Tramp の方式に合致します。Tramp には 88 種類の接続方法があるので、変わった設定がある場合はこれが必要かもしれません (それらについての以前のコメントを見てください)。

開発者のためのヘルプ
**********

auth-source ライブラリーには、外部で使うための関数は一つしかありません。

 -- Function: auth-source-user-or-password mode host port
     ホスト HOST およびポート PORT のための MODE で決まる、適切な認証トークンを取り込みます。 AUTH-SOURCE-DEBUG が t だったらデバッグのためのメッセージを表示します。ログを採るための関数を使うには、AUTH-SOURCE-DEBUG をその関数に設定してください。渡されるパラメーターは message 関数が受け取るものと同じです。つまり様式使用の文字列と任意のパラメーターです。

     もし MODE が文字列のリストならば、関数は文字列のリストか nil を返します (そのため、もう 1回 netrc ファイルを解析せずに済みます)。今のところ ``login'' と ``password'' だけが認められていますが、将来はもっと多くのものが追加されるでしょう。

     HOST はホスト名の文字列です。

     PORT はプロトコル名 (例えば ``imap'') またはポート番号です。ユーザーの netrc ファイルにあるポートに対応する文字列でなければなりません。

          ;; IMAP example
          (setq auth (auth-source-user-or-password
                      '("login" "password")
                      "anyhostnamehere"
                      "imap"))
          (nth 0 auth) ; ログイン名
          (nth 1 auth) ; パスワード