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 | ||
114f9c96 | 10 | Copyright @copyright{} 2008, 2009, 2010 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 MB |
61 | * Help for developers:: |
62 | * Index:: | |
63 | * Function Index:: | |
64 | * Variable Index:: | |
65 | @end menu | |
5dc584b5 | 66 | @end ifnottex |
9eb59592 MB |
67 | |
68 | @node Overview | |
69 | @chapter Overview | |
70 | ||
38dc51ba | 71 | The auth-source library is simply a way for Emacs and Gnus, among |
bd3e840f KY |
72 | others, to answer the old burning question ``I have a server name and |
73 | a port, what are my user name and password?'' | |
b0b63450 MB |
74 | |
75 | The auth-source library actually supports more than just the user name | |
76 | (known as the login) or the password, but only those two are in use | |
bd3e840f KY |
77 | today in Emacs or Gnus. Similarly, the auth-source library supports |
78 | multiple storage formats, currently either the classic ``netrc'' | |
79 | format, examples of which you can see later in this document, or the | |
80 | Secret Service API. | |
9eb59592 MB |
81 | |
82 | @node Help for users | |
83 | @chapter Help for users | |
84 | ||
b0b63450 MB |
85 | ``Netrc'' files are a de facto standard. They look like this: |
86 | @example | |
38dc51ba | 87 | machine @var{mymachine} login @var{myloginname} password @var{mypassword} port @var{myport} |
b0b63450 | 88 | @end example |
9eb59592 | 89 | |
38dc51ba KY |
90 | The machine is the server (either a DNS name or an IP address). |
91 | ||
b0b63450 MB |
92 | The port is optional. If it's missing, auth-source will assume any |
93 | port is OK. Actually the port is a protocol name or a port number so | |
38dc51ba KY |
94 | you can have separate entries for port @var{143} and for protocol |
95 | @var{imap} if you fancy that. Anyway, you can just omit the port if | |
96 | you don't need it. | |
97 | ||
98 | The login and password are simply your login credentials to the server. | |
99 | ||
100 | ``Netrc'' files are usually called @code{.authinfo} or @code{.netrc}; | |
101 | nowadays @code{.authinfo} seems to be more popular and the auth-source | |
102 | library encourages this confusion by making it the default, as you'll | |
103 | see later. | |
104 | ||
105 | If you have problems with the port, set @code{auth-source-debug} to | |
106 | @code{t} and see what port the library is checking in the | |
107 | @code{*Messages*} buffer. Ditto for any other problems, your first | |
108 | step is always to see what's being checked. The second step, of | |
109 | course, is to write a blog entry about it and wait for the answer in | |
110 | the comments. | |
111 | ||
112 | You can customize the variable @code{auth-sources}. The following may | |
b0b63450 MB |
113 | be needed if you are using an older version of Emacs or if the |
114 | auth-source library is not loaded for some other reason. | |
9eb59592 MB |
115 | |
116 | @lisp | |
b0b63450 | 117 | (require 'auth-source) ;; probably not necessary |
9eb59592 MB |
118 | (customize-variable 'auth-sources) ;; optional, do it once |
119 | @end lisp | |
120 | ||
121 | @defvar auth-sources | |
122 | ||
38dc51ba | 123 | The @code{auth-sources} variable tells the auth-source library where |
bd3e840f KY |
124 | your netrc files or Secret Service API collection items live for a |
125 | particular host and protocol. While you can get fancy, the default | |
126 | and simplest configuration is: | |
9eb59592 MB |
127 | |
128 | @lisp | |
bd3e840f | 129 | ;;; old default: required :host and :protocol, not needed anymore |
9eb59592 | 130 | (setq auth-sources '((:source "~/.authinfo.gpg" :host t :protocol t))) |
bd3e840f KY |
131 | ;;; mostly equivalent (see below about fallbacks) but shorter: |
132 | (setq auth-sources '((:source "~/.authinfo.gpg"))) | |
9eb59592 MB |
133 | @end lisp |
134 | ||
b0b63450 | 135 | This says ``for any host and any protocol, use just that one file.'' |
bd3e840f KY |
136 | Sweet simplicity. In fact, the latter is already the default, so |
137 | unless you want to move your netrc file, it will just work if you have | |
138 | that file. Make sure it exists. | |
9eb59592 | 139 | |
38dc51ba | 140 | By adding multiple entries to @code{auth-sources} with a particular |
b0b63450 MB |
141 | host or protocol, you can have specific netrc files for that host or |
142 | protocol. Usually this is unnecessary but may make sense if you have | |
143 | shared netrc files or some other unusual setup (90% of Emacs users | |
144 | have unusual setups and the remaining 10% are @emph{really} unusual). | |
9eb59592 | 145 | |
bd3e840f KY |
146 | Here's an example that uses the Secret Service API for all lookups, |
147 | using the default collection: | |
148 | ||
149 | @lisp | |
150 | (setq auth-sources '((:source (:secrets default)))) | |
151 | @end lisp | |
152 | ||
153 | And here's a mixed example, using two sources: | |
154 | ||
155 | @lisp | |
156 | (setq auth-sources '((:source (:secrets default) :host "myserver" :user "joe") | |
157 | (:source "~/.authinfo.gpg"))) | |
158 | @end lisp | |
159 | ||
160 | The best match is determined by order (starts from the bottom) only | |
161 | for the first pass, where things are checked exactly. In the example | |
162 | above, the first pass would find a single match for host | |
163 | @code{myserver}. The netrc choice would fail because it matches any | |
164 | host and protocol implicitly (as a @emph{fallback}). A specified | |
165 | value of @code{:host t} in @code{auth-sources} is considered a match | |
166 | on the first pass, unlike a missing @code{:host}. | |
167 | ||
168 | Now if you look for host @code{missing}, it won't match either source | |
169 | explicitly. The second pass (the @emph{fallback} pass) will look at | |
170 | all the implicit matches and collect them. They will be scored and | |
171 | returned sorted by score. The score is based on the number of | |
172 | explicit parameters that matched. See the @code{auth-pick} function | |
173 | for details. | |
174 | ||
b0b63450 | 175 | @end defvar |
9eb59592 | 176 | |
38dc51ba | 177 | If you don't customize @code{auth-sources}, you'll have to live with |
9eb59592 MB |
178 | the defaults: any host and any port are looked up in the netrc |
179 | file @code{~/.authinfo.gpg}. This is an encrypted file if and only if | |
180 | you set up EPA, which is strongly recommended. | |
181 | ||
182 | @lisp | |
183 | (require 'epa-file) | |
184 | (epa-file-enable) | |
b0b63450 MB |
185 | ;;; VERY important if you want symmetric encryption |
186 | ;;; irrelevant if you don't | |
187 | (setq epa-file-cache-passphrase-for-symmetric-encryption t) | |
9eb59592 MB |
188 | @end lisp |
189 | ||
b0b63450 MB |
190 | The simplest working netrc line example is one without a port. |
191 | ||
192 | @example | |
193 | machine YOURMACHINE login YOU password YOURPASSWORD | |
194 | @end example | |
195 | ||
196 | This will match any authentication port. Simple, right? But what if | |
197 | there's a SMTP server on port 433 of that machine that needs a | |
198 | different password from the IMAP server? | |
199 | ||
200 | @example | |
201 | machine YOURMACHINE login YOU password SMTPPASSWORD port 433 | |
202 | machine YOURMACHINE login YOU password GENERALPASSWORD | |
203 | @end example | |
204 | ||
9eb59592 MB |
205 | For url-auth authentication (HTTP/HTTPS), you need to put this in your |
206 | netrc file: | |
207 | ||
208 | @example | |
209 | machine yourmachine.com:80 port http login testuser password testpass | |
210 | @end example | |
211 | ||
b0b63450 MB |
212 | This will match any realm and authentication method (basic or digest) |
213 | over HTTP. HTTPS is set up similarly. If you want finer controls, | |
214 | explore the url-auth source code and variables. | |
9eb59592 MB |
215 | |
216 | For Tramp authentication, use: | |
217 | ||
218 | @example | |
219 | machine yourmachine.com port scp login testuser password testpass | |
220 | @end example | |
221 | ||
222 | Note that the port denotes the Tramp connection method. When you | |
223 | don't use a port entry, you match any Tramp method, as explained | |
b0b63450 MB |
224 | earlier. Since Tramp has about 88 connection methods, this may be |
225 | necessary if you have an unusual (see earlier comment on those) setup. | |
9eb59592 | 226 | |
bd3e840f KY |
227 | @node Secret Service API |
228 | @chapter Secret Service API | |
229 | ||
230 | TODO: how does it work generally, how does secrets.el work, some examples. | |
231 | ||
9eb59592 MB |
232 | @node Help for developers |
233 | @chapter Help for developers | |
234 | ||
235 | The auth-source library only has one function for external use. | |
236 | ||
bd3e840f | 237 | @defun auth-source-user-or-password mode host port &optional username |
9eb59592 MB |
238 | |
239 | Retrieve appropriate authentication tokens, determined by @var{mode}, | |
bd3e840f KY |
240 | for host @var{host} and @var{port}. If @var{username} is provided it |
241 | will also be checked. If @code{auth-source-debug} is t, debugging | |
242 | messages will be printed. Set @code{auth-source-debug} to a function | |
243 | to use that function for logging. The parameters passed will be the | |
244 | same that the @code{message} function takes, that is, a string | |
b0b63450 | 245 | formatting spec and optional parameters. |
9eb59592 MB |
246 | |
247 | If @var{mode} is a list of strings, the function will return a list of | |
b0b63450 | 248 | strings or @code{nil} objects (thus you can avoid parsing the netrc |
bd3e840f KY |
249 | file or checking the Secret Service API more than once). If it's a |
250 | string, the function will return a string or a @code{nil} object. | |
251 | Currently only the modes ``login'' and ``password'' are recognized but | |
252 | more may be added in the future. | |
9eb59592 MB |
253 | |
254 | @var{host} is a string containing the host name. | |
255 | ||
256 | @var{port} contains the protocol name (e.g. ``imap'') or | |
257 | a port number. It must be a string, corresponding to the port in the | |
258 | users' netrc files. | |
259 | ||
bd3e840f KY |
260 | @var{username} contains the user name (e.g. ``joe'') as a string. |
261 | ||
9eb59592 MB |
262 | @example |
263 | ;; IMAP example | |
264 | (setq auth (auth-source-user-or-password | |
265 | '("login" "password") | |
266 | "anyhostnamehere" | |
267 | "imap")) | |
268 | (nth 0 auth) ; the login name | |
269 | (nth 1 auth) ; the password | |
270 | @end example | |
271 | ||
272 | @end defun | |
273 | ||
274 | @node Index | |
275 | @chapter Index | |
276 | @printindex cp | |
277 | ||
278 | @node Function Index | |
279 | @chapter Function Index | |
280 | @printindex fn | |
281 | ||
282 | @node Variable Index | |
283 | @chapter Variable Index | |
284 | @printindex vr | |
285 | ||
9eb59592 MB |
286 | @bye |
287 | ||
288 | @c End: |