Commit | Line | Data |
---|---|---|
9eb59592 | 1 | \input texinfo @c -*-texinfo-*- |
7fbf7cae TZ |
2 | |
3 | @include gnus-overrides.texi | |
4 | ||
e280480a | 5 | @setfilename ../../info/auth |
5dc584b5 | 6 | @settitle Emacs auth-source Library @value{VERSION} |
9eb59592 | 7 | |
b8e0f0cd | 8 | @set VERSION 0.3 |
9eb59592 | 9 | |
9eb59592 MB |
10 | @copying |
11 | This file describes the Emacs auth-source library. | |
12 | ||
73b0cd50 | 13 | Copyright @copyright{} 2008-2011 Free Software Foundation, Inc. |
9eb59592 MB |
14 | |
15 | @quotation | |
16 | Permission is granted to copy, distribute and/or modify this document | |
17 | under the terms of the GNU Free Documentation License, Version 1.3 or | |
18 | any later version published by the Free Software Foundation; with no | |
19 | Invariant Sections, with the Front-Cover texts being ``A GNU Manual,'' | |
20 | and with the Back-Cover Texts as in (a) below. A copy of the license | |
21 | is included in the section entitled ``GNU Free Documentation License'' | |
22 | in the Emacs manual. | |
23 | ||
24 | (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and | |
25 | modify this GNU manual. Buying copies from the FSF supports it in | |
26 | developing GNU and promoting software freedom.'' | |
27 | ||
28 | This document is part of a collection distributed under the GNU Free | |
29 | Documentation License. If you want to distribute this document | |
30 | separately from the collection, you can do so by adding a copy of the | |
31 | license to the document, as described in section 6 of the license. | |
32 | @end quotation | |
33 | @end copying | |
34 | ||
5dc584b5 KB |
35 | @dircategory Emacs |
36 | @direntry | |
62e034c2 | 37 | * Auth-source: (auth). The Emacs auth-source library. |
5dc584b5 | 38 | @end direntry |
9eb59592 MB |
39 | |
40 | @titlepage | |
7fbf7cae TZ |
41 | @ifset WEBHACKDEVEL |
42 | @title Emacs auth-source Library (DEVELOPMENT VERSION) | |
43 | @end ifset | |
44 | @ifclear WEBHACKDEVEL | |
9eb59592 | 45 | @title Emacs auth-source Library |
7fbf7cae | 46 | @end ifclear |
9eb59592 MB |
47 | @author by Ted Zlatanov |
48 | @page | |
9eb59592 MB |
49 | @vskip 0pt plus 1filll |
50 | @insertcopying | |
51 | @end titlepage | |
9eb59592 | 52 | |
5dc584b5 | 53 | @contents |
9eb59592 | 54 | |
5dc584b5 | 55 | @ifnottex |
9eb59592 MB |
56 | @node Top |
57 | @top Emacs auth-source | |
58 | This manual describes the Emacs auth-source library. | |
59 | ||
60 | It is a way for multiple applications to share a single configuration | |
61 | (in Emacs and in files) for user convenience. | |
62 | ||
5dc584b5 KB |
63 | @insertcopying |
64 | ||
9eb59592 MB |
65 | @menu |
66 | * Overview:: Overview of the auth-source library. | |
67 | * Help for users:: | |
bd3e840f | 68 | * Secret Service API:: |
9eb59592 | 69 | * Help for developers:: |
36d3245f | 70 | * GnuPG and EasyPG Assistant Configuration:: |
9eb59592 MB |
71 | * Index:: |
72 | * Function Index:: | |
73 | * Variable Index:: | |
74 | @end menu | |
5dc584b5 | 75 | @end ifnottex |
9eb59592 MB |
76 | |
77 | @node Overview | |
78 | @chapter Overview | |
79 | ||
38dc51ba | 80 | The auth-source library is simply a way for Emacs and Gnus, among |
b8e0f0cd G |
81 | others, to answer the old burning question ``What are my user name and |
82 | password?'' | |
b0b63450 | 83 | |
b8e0f0cd G |
84 | (This is different from the old question about burning ``Where is the |
85 | fire extinguisher, please?''.) | |
86 | ||
87 | The auth-source library supports more than just the user name or the | |
88 | password (known as the secret). | |
89 | ||
90 | Similarly, the auth-source library supports multiple storage backend, | |
91 | currently either the classic ``netrc'' backend, examples of which you | |
92 | can see later in this document, or the Secret Service API. This is | |
93 | done with EIEIO-based backends and you can write your own if you want. | |
9eb59592 MB |
94 | |
95 | @node Help for users | |
96 | @chapter Help for users | |
97 | ||
b0b63450 MB |
98 | ``Netrc'' files are a de facto standard. They look like this: |
99 | @example | |
38dc51ba | 100 | machine @var{mymachine} login @var{myloginname} password @var{mypassword} port @var{myport} |
b0b63450 | 101 | @end example |
9eb59592 | 102 | |
b8e0f0cd G |
103 | The @code{machine} is the server (either a DNS name or an IP address). |
104 | It's known as @var{:host} in @code{auth-source-search} queries. You | |
105 | can also use @code{host}. | |
106 | ||
107 | The @code{port} is the connection port or protocol. It's known as | |
108 | @var{:port} in @code{auth-source-search} queries. You can also use | |
109 | @code{protocol}. | |
110 | ||
111 | The @code{user} is the user name. It's known as @var{:user} in | |
112 | @code{auth-source-search} queries. You can also use @code{login} and | |
113 | @code{account}. | |
114 | ||
115 | Spaces are always OK as far as auth-source is concerned (but other | |
116 | programs may not like them). Just put the data in quotes, escaping | |
117 | quotes as you'd expect with @code{\}. | |
118 | ||
119 | All these are optional. You could just say (but we don't recommend | |
120 | it, we're just showing that it's possible) | |
38dc51ba | 121 | |
b8e0f0cd G |
122 | @example |
123 | password @var{mypassword} | |
124 | @end example | |
38dc51ba | 125 | |
b8e0f0cd G |
126 | to use the same password everywhere. Again, @emph{DO NOT DO THIS} or |
127 | you will be pwned as the kids say. | |
38dc51ba KY |
128 | |
129 | ``Netrc'' files are usually called @code{.authinfo} or @code{.netrc}; | |
130 | nowadays @code{.authinfo} seems to be more popular and the auth-source | |
131 | library encourages this confusion by making it the default, as you'll | |
132 | see later. | |
133 | ||
b8e0f0cd G |
134 | If you have problems with the search, set @code{auth-source-debug} to |
135 | @code{t} and see what host, port, and user the library is checking in | |
136 | the @code{*Messages*} buffer. Ditto for any other problems, your | |
137 | first step is always to see what's being checked. The second step, of | |
38dc51ba KY |
138 | course, is to write a blog entry about it and wait for the answer in |
139 | the comments. | |
140 | ||
141 | You can customize the variable @code{auth-sources}. The following may | |
b0b63450 MB |
142 | be needed if you are using an older version of Emacs or if the |
143 | auth-source library is not loaded for some other reason. | |
9eb59592 MB |
144 | |
145 | @lisp | |
b0b63450 | 146 | (require 'auth-source) ;; probably not necessary |
9eb59592 MB |
147 | (customize-variable 'auth-sources) ;; optional, do it once |
148 | @end lisp | |
149 | ||
150 | @defvar auth-sources | |
151 | ||
38dc51ba | 152 | The @code{auth-sources} variable tells the auth-source library where |
bd3e840f KY |
153 | your netrc files or Secret Service API collection items live for a |
154 | particular host and protocol. While you can get fancy, the default | |
155 | and simplest configuration is: | |
9eb59592 MB |
156 | |
157 | @lisp | |
bd3e840f | 158 | ;;; old default: required :host and :protocol, not needed anymore |
9eb59592 | 159 | (setq auth-sources '((:source "~/.authinfo.gpg" :host t :protocol t))) |
bd3e840f KY |
160 | ;;; mostly equivalent (see below about fallbacks) but shorter: |
161 | (setq auth-sources '((:source "~/.authinfo.gpg"))) | |
b8e0f0cd G |
162 | ;;; even shorter and the @emph{default}: |
163 | (setq auth-sources '("~/.authinfo.gpg" "~/.authinfo")) | |
5415d076 G |
164 | ;;; use the Secrets API @var{Login} collection (@pxref{Secret Service API}) |
165 | (setq auth-sources '("secrets:Login")) | |
9eb59592 MB |
166 | @end lisp |
167 | ||
38dc51ba | 168 | By adding multiple entries to @code{auth-sources} with a particular |
b0b63450 MB |
169 | host or protocol, you can have specific netrc files for that host or |
170 | protocol. Usually this is unnecessary but may make sense if you have | |
171 | shared netrc files or some other unusual setup (90% of Emacs users | |
172 | have unusual setups and the remaining 10% are @emph{really} unusual). | |
9eb59592 | 173 | |
b8e0f0cd | 174 | Here's a mixed example using two sources: |
bd3e840f KY |
175 | |
176 | @lisp | |
177 | (setq auth-sources '((:source (:secrets default) :host "myserver" :user "joe") | |
b8e0f0cd | 178 | "~/.authinfo.gpg")) |
bd3e840f KY |
179 | @end lisp |
180 | ||
b0b63450 | 181 | @end defvar |
9eb59592 | 182 | |
38dc51ba | 183 | If you don't customize @code{auth-sources}, you'll have to live with |
9eb59592 | 184 | the defaults: any host and any port are looked up in the netrc |
a1d16a7b | 185 | file @code{~/.authinfo.gpg}, which is a GnuPG encrypted file |
b8e0f0cd G |
186 | (@pxref{GnuPG and EasyPG Assistant Configuration}). |
187 | ||
188 | If that fails, the unencrypted netrc file @code{~/.authinfo} will | |
189 | be used. | |
9eb59592 | 190 | |
b8e0f0cd | 191 | The typical netrc line example is without a port. |
b0b63450 MB |
192 | |
193 | @example | |
194 | machine YOURMACHINE login YOU password YOURPASSWORD | |
195 | @end example | |
196 | ||
197 | This will match any authentication port. Simple, right? But what if | |
198 | there's a SMTP server on port 433 of that machine that needs a | |
199 | different password from the IMAP server? | |
200 | ||
201 | @example | |
202 | machine YOURMACHINE login YOU password SMTPPASSWORD port 433 | |
203 | machine YOURMACHINE login YOU password GENERALPASSWORD | |
204 | @end example | |
205 | ||
9eb59592 MB |
206 | For url-auth authentication (HTTP/HTTPS), you need to put this in your |
207 | netrc file: | |
208 | ||
209 | @example | |
210 | machine yourmachine.com:80 port http login testuser password testpass | |
211 | @end example | |
212 | ||
b0b63450 MB |
213 | This will match any realm and authentication method (basic or digest) |
214 | over HTTP. HTTPS is set up similarly. If you want finer controls, | |
215 | explore the url-auth source code and variables. | |
9eb59592 MB |
216 | |
217 | For Tramp authentication, use: | |
218 | ||
219 | @example | |
220 | machine yourmachine.com port scp login testuser password testpass | |
221 | @end example | |
222 | ||
223 | Note that the port denotes the Tramp connection method. When you | |
224 | don't use a port entry, you match any Tramp method, as explained | |
b0b63450 MB |
225 | earlier. Since Tramp has about 88 connection methods, this may be |
226 | necessary if you have an unusual (see earlier comment on those) setup. | |
9eb59592 | 227 | |
bd3e840f KY |
228 | @node Secret Service API |
229 | @chapter Secret Service API | |
230 | ||
231 | TODO: how does it work generally, how does secrets.el work, some examples. | |
232 | ||
9eb59592 MB |
233 | @node Help for developers |
234 | @chapter Help for developers | |
235 | ||
b8e0f0cd | 236 | The auth-source library only has a few functions for external use. |
9eb59592 | 237 | |
b8e0f0cd | 238 | @defun auth-source-search SPEC |
9eb59592 | 239 | |
b8e0f0cd | 240 | TODO: how to include docstring? |
9eb59592 | 241 | |
b8e0f0cd | 242 | @end defun |
9eb59592 | 243 | |
b8e0f0cd | 244 | @defun auth-source-delete SPEC |
9eb59592 | 245 | |
b8e0f0cd | 246 | TODO: how to include docstring? |
9eb59592 | 247 | |
b8e0f0cd | 248 | @end defun |
bd3e840f | 249 | |
b8e0f0cd G |
250 | @defun auth-source-forget SPEC |
251 | ||
252 | TODO: how to include docstring? | |
253 | ||
254 | @end defun | |
255 | ||
256 | @defun auth-source-forget+ SPEC | |
257 | ||
258 | TODO: how to include docstring? | |
9eb59592 MB |
259 | |
260 | @end defun | |
261 | ||
36d3245f G |
262 | @node GnuPG and EasyPG Assistant Configuration |
263 | @appendix GnuPG and EasyPG Assistant Configuration | |
264 | ||
98e2b864 DU |
265 | If you don't customize @code{auth-sources}, the auth-source library |
266 | reads @code{~/.authinfo.gpg}, which is a GnuPG encrypted file. | |
267 | ||
36d3245f | 268 | In Emacs 23 or later there is an option @code{auto-encryption-mode} to |
a1d16a7b G |
269 | automatically decrypt @code{*.gpg} files. It is enabled by default. |
270 | If you are using earlier versions of Emacs, you will need: | |
36d3245f G |
271 | |
272 | @lisp | |
273 | (require 'epa-file) | |
274 | (epa-file-enable) | |
275 | @end lisp | |
276 | ||
98e2b864 | 277 | If you want your GnuPG passwords to be cached, set up @code{gpg-agent} |
36d3245f | 278 | or EasyPG Assitant |
c56dfd36 | 279 | (@pxref{Caching Passphrases, , Caching Passphrases, epa}). |
36d3245f | 280 | |
98e2b864 | 281 | To quick start, here are some questions: |
36d3245f G |
282 | |
283 | @enumerate | |
a1d16a7b G |
284 | @item |
285 | Do you use GnuPG version 2 instead of GnuPG version 1? | |
286 | @item | |
287 | Do you use symmetric encryption rather than public key encryption? | |
288 | @item | |
289 | Do you want to use gpg-agent? | |
36d3245f G |
290 | @end enumerate |
291 | ||
292 | Here are configurations depending on your answers: | |
293 | ||
294 | @multitable {111} {222} {333} {configuration configuration configuration} | |
295 | @item @b{1} @tab @b{2} @tab @b{3} @tab Configuration | |
98e2b864 | 296 | @item Yes @tab Yes @tab Yes @tab Set up gpg-agent. |
36d3245f | 297 | @item Yes @tab Yes @tab No @tab You can't, without gpg-agent. |
98e2b864 | 298 | @item Yes @tab No @tab Yes @tab Set up gpg-agent. |
36d3245f G |
299 | @item Yes @tab No @tab No @tab You can't, without gpg-agent. |
300 | @item No @tab Yes @tab Yes @tab Set up elisp passphrase cache. | |
301 | @item No @tab Yes @tab No @tab Set up elisp passphrase cache. | |
98e2b864 | 302 | @item No @tab No @tab Yes @tab Set up gpg-agent. |
36d3245f G |
303 | @item No @tab No @tab No @tab You can't, without gpg-agent. |
304 | @end multitable | |
305 | ||
a1d16a7b G |
306 | To set up gpg-agent, follow the instruction in GnuPG manual |
307 | (@pxref{Invoking GPG-AGENT, , Invoking GPG-AGENT, gnupg}). | |
36d3245f G |
308 | |
309 | To set up elisp passphrase cache, set | |
310 | @code{epa-file-cache-passphrase-for-symmetric-encryption}. | |
311 | ||
9eb59592 MB |
312 | @node Index |
313 | @chapter Index | |
314 | @printindex cp | |
315 | ||
316 | @node Function Index | |
317 | @chapter Function Index | |
318 | @printindex fn | |
319 | ||
320 | @node Variable Index | |
321 | @chapter Variable Index | |
322 | @printindex vr | |
323 | ||
9eb59592 MB |
324 | @bye |
325 | ||
326 | @c End: |