Mercurial > emacs
comparison doc/misc/auth.texi @ 107564:be11042041cb
2010-03-27 Teodor Zlatanov <tzz@lifelogs.com>
* auth.texi (Secret Service API): Add TODO node.
(Help for users): Explain the new source options for `auth-sources'.
author | Katsumi Yamaoka <yamaoka@jpl.org> |
---|---|
date | Sun, 28 Mar 2010 23:55:59 +0000 |
parents | 1d1d5d9bd884 |
children | 60516122d066 |
comparison
equal
deleted
inserted
replaced
107563:95c2fdf14356 | 107564:be11042041cb |
---|---|
55 @insertcopying | 55 @insertcopying |
56 | 56 |
57 @menu | 57 @menu |
58 * Overview:: Overview of the auth-source library. | 58 * Overview:: Overview of the auth-source library. |
59 * Help for users:: | 59 * Help for users:: |
60 * Secret Service API:: | |
60 * Help for developers:: | 61 * Help for developers:: |
61 * Index:: | 62 * Index:: |
62 * Function Index:: | 63 * Function Index:: |
63 * Variable Index:: | 64 * Variable Index:: |
64 @end menu | 65 @end menu |
66 | 67 |
67 @node Overview | 68 @node Overview |
68 @chapter Overview | 69 @chapter Overview |
69 | 70 |
70 The auth-source library is simply a way for Emacs and Gnus, among | 71 The auth-source library is simply a way for Emacs and Gnus, among |
71 others, to find the answer to the old burning question ``I have a | 72 others, to answer the old burning question ``I have a server name and |
72 server name and a port, what are my user name and password?'' | 73 a port, what are my user name and password?'' |
73 | 74 |
74 The auth-source library actually supports more than just the user name | 75 The auth-source library actually supports more than just the user name |
75 (known as the login) or the password, but only those two are in use | 76 (known as the login) or the password, but only those two are in use |
76 today in Emacs or Gnus. Similarly, the auth-source library can in | 77 today in Emacs or Gnus. Similarly, the auth-source library supports |
77 theory support multiple storage formats, but currently it only | 78 multiple storage formats, currently either the classic ``netrc'' |
78 understands the classic ``netrc'' format, examples of which you can | 79 format, examples of which you can see later in this document, or the |
79 see later in this document. | 80 Secret Service API. |
80 | 81 |
81 @node Help for users | 82 @node Help for users |
82 @chapter Help for users | 83 @chapter Help for users |
83 | 84 |
84 ``Netrc'' files are a de facto standard. They look like this: | 85 ``Netrc'' files are a de facto standard. They look like this: |
118 @end lisp | 119 @end lisp |
119 | 120 |
120 @defvar auth-sources | 121 @defvar auth-sources |
121 | 122 |
122 The @code{auth-sources} variable tells the auth-source library where | 123 The @code{auth-sources} variable tells the auth-source library where |
123 your netrc files live for a particular host and protocol. While you | 124 your netrc files or Secret Service API collection items live for a |
124 can get fancy, the default and simplest configuration is: | 125 particular host and protocol. While you can get fancy, the default |
125 | 126 and simplest configuration is: |
126 @lisp | 127 |
128 @lisp | |
129 ;;; old default: required :host and :protocol, not needed anymore | |
127 (setq auth-sources '((:source "~/.authinfo.gpg" :host t :protocol t))) | 130 (setq auth-sources '((:source "~/.authinfo.gpg" :host t :protocol t))) |
131 ;;; mostly equivalent (see below about fallbacks) but shorter: | |
132 (setq auth-sources '((:source "~/.authinfo.gpg"))) | |
128 @end lisp | 133 @end lisp |
129 | 134 |
130 This says ``for any host and any protocol, use just that one file.'' | 135 This says ``for any host and any protocol, use just that one file.'' |
131 Sweet simplicity. In fact, this is already the default, so unless you | 136 Sweet simplicity. In fact, the latter is already the default, so |
132 want to move your netrc file, it will just work if you have that | 137 unless you want to move your netrc file, it will just work if you have |
133 file. You may not, though, so make sure it exists. | 138 that file. Make sure it exists. |
134 | 139 |
135 By adding multiple entries to @code{auth-sources} with a particular | 140 By adding multiple entries to @code{auth-sources} with a particular |
136 host or protocol, you can have specific netrc files for that host or | 141 host or protocol, you can have specific netrc files for that host or |
137 protocol. Usually this is unnecessary but may make sense if you have | 142 protocol. Usually this is unnecessary but may make sense if you have |
138 shared netrc files or some other unusual setup (90% of Emacs users | 143 shared netrc files or some other unusual setup (90% of Emacs users |
139 have unusual setups and the remaining 10% are @emph{really} unusual). | 144 have unusual setups and the remaining 10% are @emph{really} unusual). |
140 | 145 |
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 | |
141 @end defvar | 175 @end defvar |
142 | 176 |
143 If you don't customize @code{auth-sources}, you'll have to live with | 177 If you don't customize @code{auth-sources}, you'll have to live with |
144 the defaults: any host and any port are looked up in the netrc | 178 the defaults: any host and any port are looked up in the netrc |
145 file @code{~/.authinfo.gpg}. This is an encrypted file if and only if | 179 file @code{~/.authinfo.gpg}. This is an encrypted file if and only if |
188 Note that the port denotes the Tramp connection method. When you | 222 Note that the port denotes the Tramp connection method. When you |
189 don't use a port entry, you match any Tramp method, as explained | 223 don't use a port entry, you match any Tramp method, as explained |
190 earlier. Since Tramp has about 88 connection methods, this may be | 224 earlier. Since Tramp has about 88 connection methods, this may be |
191 necessary if you have an unusual (see earlier comment on those) setup. | 225 necessary if you have an unusual (see earlier comment on those) setup. |
192 | 226 |
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 | |
193 @node Help for developers | 232 @node Help for developers |
194 @chapter Help for developers | 233 @chapter Help for developers |
195 | 234 |
196 The auth-source library only has one function for external use. | 235 The auth-source library only has one function for external use. |
197 | 236 |
198 @defun auth-source-user-or-password mode host port | 237 @defun auth-source-user-or-password mode host port &optional username |
199 | 238 |
200 Retrieve appropriate authentication tokens, determined by @var{mode}, | 239 Retrieve appropriate authentication tokens, determined by @var{mode}, |
201 for host @var{host} and @var{port}. If @code{auth-source-debug} is t, | 240 for host @var{host} and @var{port}. If @var{username} is provided it |
202 debugging messages will be printed. Set @code{auth-source-debug} to a | 241 will also be checked. If @code{auth-source-debug} is t, debugging |
203 function to use that function for logging. The parameters passed will | 242 messages will be printed. Set @code{auth-source-debug} to a function |
204 be the same that the @code{message} function takes, that is, a string | 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 | |
205 formatting spec and optional parameters. | 245 formatting spec and optional parameters. |
206 | 246 |
207 If @var{mode} is a list of strings, the function will return a list of | 247 If @var{mode} is a list of strings, the function will return a list of |
208 strings or @code{nil} objects (thus you can avoid parsing the netrc | 248 strings or @code{nil} objects (thus you can avoid parsing the netrc |
209 file more than once). If it's a string, the function will return a | 249 file or checking the Secret Service API more than once). If it's a |
210 string or a @code{nil} object. Currently only the modes ``login'' and | 250 string, the function will return a string or a @code{nil} object. |
211 ``password'' are recognized but more may be added in the future. | 251 Currently only the modes ``login'' and ``password'' are recognized but |
252 more may be added in the future. | |
212 | 253 |
213 @var{host} is a string containing the host name. | 254 @var{host} is a string containing the host name. |
214 | 255 |
215 @var{port} contains the protocol name (e.g. ``imap'') or | 256 @var{port} contains the protocol name (e.g. ``imap'') or |
216 a port number. It must be a string, corresponding to the port in the | 257 a port number. It must be a string, corresponding to the port in the |
217 users' netrc files. | 258 users' netrc files. |
259 | |
260 @var{username} contains the user name (e.g. ``joe'') as a string. | |
218 | 261 |
219 @example | 262 @example |
220 ;; IMAP example | 263 ;; IMAP example |
221 (setq auth (auth-source-user-or-password | 264 (setq auth (auth-source-user-or-password |
222 '("login" "password") | 265 '("login" "password") |