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

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

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

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

Copyright © 2008, 2009, 2010 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 ライブラリーは、「サーバー名とポートはわかってるんだけど、ユーザー名とパスワードは何だっけ?」という昔ながらの熱烈な問いに答えるための、 Emacs と Gnus 用の数ある単純な手段の一つです。

実際には auth-source ライブラリーは単なるユーザー名 (いわゆる login) やパスワード以外のものも扱うことができますが、今日の Emacs と Gnus ではそれら 2つだけが使われています。同様に auth-source ライブラリーは多くの記録形式、現在は伝統的な ``netrc'' 形式 (この文書の後の方にあります) またはシークレットサービス API をサポートします。

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

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

     machine MYMACHINE login MYLOGINNAME password MYPASSWORD port MYPORT

machine はサーバーです (DNS 名または IP アドレス)。

ポートの指定は無くても構いません。無い場合、auth-source はどんなポートも OK なのだと解釈します。実際のところ、ポートはプロトコルの名前かポート番号のどちらでも良いので、もしそうしたいのならば、ポート 143 とプロトコル imap のための項目を別々に持つことができます。ともあれ、もしポートの指定が要らない場合は省略しても構いません。

login と password は、サーバーに対して簡潔にあなたのログイン資格を証明するためのものです。

``Netrc'' ファイルは通常 .authinfo または .netrc と呼ばれます。今では .authinfo の方が普及しているようなので、後でわかるように auth-source ライブラリーはそれをディフォルトにすることによって、この混乱を助長しています。

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

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

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

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

          ;;; 旧ディフォルト: :host と :protocol が必要だったが、もはや不要。
          (setq auth-sources '((:source "~/.authinfo.gpg" :host t :protocol t)))
          ;;; ほぼ等価だが、より短い (後述の fallback についての記述を参照)。
          (setq auth-sources '((:source "~/.authinfo.gpg")))

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

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

     これは、すべての参照にシークレットサービス API を使う例です。デフォルトの収集物を使います:

          (setq auth-sources '((:source (:secrets default))))

     そしてこれは、混在する 2つのソースを使う例です:

          (setq auth-sources '((:source (:secrets default) :host "myserver" :user "joe")
                               (:source "~/.authinfo.gpg")))

     最善の合致は、初回の走査だけで (下から始まる) 順序によって決定されます (各要素は厳密に照合されます)。上の例では、初回の走査でホスト myserver への単一の合致を見つけるでしょう。Netrc 選択では、それがどんなホストやプロトコルにも暗に (fallback として) 合致してしまうので、失敗するでしょう。auth-sources における :host t の設定値は、:host が無い場合と違って、初回の走査における合致を目論んだものであると考慮されます。

     さて、もし ``未設定'' のホストを探そうとすると、それはどんなソースにも明らかな合致はしないでしょう。2回目の走査 (fallback パス) では、すべての暗黙の合致を調べて、それらを収集します。それらはスコア付けされ、スコアによって並べ変えられます。スコアは、合致する明示的なパラメーターの数値に基づいています。詳細は auth-pick 関数を参照してください。

     訳注 fallback: ある要素が指定されていないために厳密な合致が起こらなくても、ある規則によって選択する目的物、あるいは選択すること。

もし auth-sources をカスタマイズしないと、ディフォルトで生活することになるでしょう。そのディフォルトとは、どんなホストもポートについても netrc ファイル ~/.authinfo.gpg を参照するということです。これは GnuPG で暗号化されたファイルです (see GnuPG and EasyPG Assistant Configuration)。

実際に使える最も簡単な 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 種類の接続方法があるので、変わった設定がある場合はこれが必要かもしれません (それらについての以前のコメントを見てください)。

シークレットサービス API
**************

TODO: どう働くかを一般的に、secrets.el はどうやるか、いくつかの例。

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

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

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

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

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

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

     USERNAME はユーザー名の文字列 (例えば ``joe'') です。

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

GnuPG および EasyPG アシスタントの設定
**************************

auth-sources をカスタマイズしない場合、auth-source ライブラリーは ~/.authinfo.gpg (GnuPG で暗号化されたファイル) を読み込みます。

Emacs 23 以降では *.gpg ファイルの暗号を自動的に解くためのオプション auto-encryption-mode があります。ディフォルトで有効です。もし何らかの理由で Emacs の初期の版を使っている場合は、以下が必要です:

     (require 'epa-file)
     (epa-file-enable)

あなたの GnuPG のパスワードがキャッシュされるようにしたいなら、 gpg-agent または EasyPG アシスアントを設定してください (see Caching Passphrases (epa))。

手早く使い始めるには、まず以下の設問に対する答を用意してください:

 1. GnuPG のバージョン 1 ではなく、バージョン 2 を使っていますか?

 2. 公開鍵暗号でななく、共通鍵暗号を使っていますか?

 3. gpg-agent を使いたいですか?

以下は上記の質疑に対するあなたの回答に基づいた設定です:

1   2   3   Configuration
Yes   Yes   Yes   gpg-agent を設定してください。
Yes   Yes   No   gpg-agent 無しではできません。
Yes   No   Yes   gpg-agent を設定してください。
Yes   No   No   gpg-agent 無しではできません。
No   Yes   Yes   ELisp 版のパスワード・キャッシュを設定してください。
No   Yes   No   ELisp 版のパスワード・キャッシュを設定してください。
No   No   Yes   gpg-agent を設定してください。
No   No   No   gpg-agent 無しではできません。

gpg-agent を設定するには GnuPG マニュアル (see Invoking GPG-AGENT (gnupg)) の説明に従ってください。

ELisp 版のパスワード・キャッシュを使う場合は epa-file-cache-passphrase-for-symmetric-encryption を設定してください。