     [file gnus-overrides-ja.texi not included]

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

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

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

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

Copyright © 2008-2011 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 ライブラリーは単なるユーザー名やパスワード (いわゆる秘密) 以外のものも扱うことができます。

同様に auth-source ライブラリーは多くの貯蔵バックエンド、現在は伝統的な ``netrc'' バクエンド (この文書の後の方にあります) またはシークレットサービス API をサポートします。これは EIEIO に基づいたバクエンドで行なわれ、もし必要ならあなた独自のものを書くことができます。

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

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

     machine MYMACHINE login MYLOGINNAME password MYPASSWORD port MYPORT

machine はサーバーです (DNS 名または IP アドレスのどちらか)。 auth-source-search 検索における :HOST でもあります。 host も使うことができます。

port は接続するポートまたはプロトコルです。 auth-source-search 検索における :PORT でもあります。

user はユーザー名です。auth-source-search 検索における :USER でもあります。login および account も使うことができます。

空白文字は auth-source に関しては常に OK です (他のプログラムには良くないかもしれませんが)。データは引用符で囲んでください。データ中の引用符はあなたの予想通り \ でエスケープしてください。

すべてこれらは任意です。どこでも同じパスワードを使うために、ただ単に

     password MYPASSWORD

と設定することができます---ということが可能であることを示しているのであって、それを推奨しているわけではありません。繰り返しますが これは使わないでください。さもないとひどい目に会うでしょう。

``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 と :port が必要だったが、もはや不要。
          (setq auth-sources '((:source "~/.authinfo.gpg" :host t :port t)))
          ;;; ほぼ等価だが、より短い (後述の fallback についての記述を参照)。
          (setq auth-sources '((:source "~/.authinfo.gpg")))
          ;;; さらに短い ディフォルト:
          (setq auth-sources '("~/.authinfo.gpg" "~/.authinfo"))
          ;;; シークレット API の LOGIN コレクションを使う
          ;;; (see Secret Service API)
          (setq auth-sources '("secrets:Login"))

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

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

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

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

もしその読み込みに失敗すると、暗号化されていない netrc ファイル ~/.authinfo が使われます。

代表的な 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-search SPEC

     TODO: どうやって docstring を含める?

 -- Function: auth-source-delete SPEC

     TODO: どうやって docstring を含める?

 -- Function: auth-source-forget SPEC

     TODO: どうやって docstring を含める?

 -- Function: auth-source-forget+ SPEC

     TODO: どうやって docstring を含める?

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

auth-sources をカスタマイズしない場合、auth-source ライブラリーは ~/.authinfo.gpg (GnuPG で暗号化されたファイル) を読み込みます。その後で ~/.authinfo を検査しますが、そのような暗号化されていないファイルを使うことは推奨しません。

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 を設定してください。