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