Mercurial > emacs
annotate doc/misc/auth.texi @ 104692:b99b3dda298b
Merge from gnus--devo--0
Revision: emacs@sv.gnu.org/emacs--devo--0--patch-1629
author | Miles Bader <miles@gnu.org> |
---|---|
date | Sat, 29 Aug 2009 00:27:12 +0000 |
parents | 3e7c6b40afdd |
children | 2c607b344f3b |
rev | line source |
---|---|
102054 | 1 \input texinfo @c -*-texinfo-*- |
102371 | 2 @setfilename ../../info/auth |
102059
9bcea07061a8
consistently use @insertcopying, @direntry, @contents
Karl Berry <karl@gnu.org>
parents:
102054
diff
changeset
|
3 @settitle Emacs auth-source Library @value{VERSION} |
102054 | 4 |
104692 | 5 @set VERSION 0.2 |
102054 | 6 |
7 @copying | |
8 This file describes the Emacs auth-source library. | |
9 | |
102059
9bcea07061a8
consistently use @insertcopying, @direntry, @contents
Karl Berry <karl@gnu.org>
parents:
102054
diff
changeset
|
10 Copyright @copyright{} 2008, 2009 Free Software Foundation, Inc. |
102054 | 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 | |
102059
9bcea07061a8
consistently use @insertcopying, @direntry, @contents
Karl Berry <karl@gnu.org>
parents:
102054
diff
changeset
|
32 @dircategory Emacs |
9bcea07061a8
consistently use @insertcopying, @direntry, @contents
Karl Berry <karl@gnu.org>
parents:
102054
diff
changeset
|
33 @direntry |
102820 | 34 * Auth-source: (auth). The Emacs auth-source library. |
102059
9bcea07061a8
consistently use @insertcopying, @direntry, @contents
Karl Berry <karl@gnu.org>
parents:
102054
diff
changeset
|
35 @end direntry |
102054 | 36 |
37 @titlepage | |
38 @title Emacs auth-source Library | |
39 @author by Ted Zlatanov | |
40 @page | |
41 @vskip 0pt plus 1filll | |
42 @insertcopying | |
43 @end titlepage | |
44 | |
102059
9bcea07061a8
consistently use @insertcopying, @direntry, @contents
Karl Berry <karl@gnu.org>
parents:
102054
diff
changeset
|
45 @contents |
102054 | 46 |
102059
9bcea07061a8
consistently use @insertcopying, @direntry, @contents
Karl Berry <karl@gnu.org>
parents:
102054
diff
changeset
|
47 @ifnottex |
102054 | 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 | |
102059
9bcea07061a8
consistently use @insertcopying, @direntry, @contents
Karl Berry <karl@gnu.org>
parents:
102054
diff
changeset
|
55 @insertcopying |
9bcea07061a8
consistently use @insertcopying, @direntry, @contents
Karl Berry <karl@gnu.org>
parents:
102054
diff
changeset
|
56 |
102054 | 57 @menu |
58 * Overview:: Overview of the auth-source library. | |
59 * Help for users:: | |
60 * Help for developers:: | |
61 * Index:: | |
62 * Function Index:: | |
63 * Variable Index:: | |
64 @end menu | |
102059
9bcea07061a8
consistently use @insertcopying, @direntry, @contents
Karl Berry <karl@gnu.org>
parents:
102054
diff
changeset
|
65 @end ifnottex |
102054 | 66 |
67 @node Overview | |
68 @chapter Overview | |
69 | |
104692 | 70 The auth-source library is a modern, extensible, enterprise-class |
71 authentication library. It uses the latest design patterns, has 1800 | |
72 unit tests, and has been featured in 21 industry conference keynote | |
73 talks. It's future-proof, mathematically proven to be bug-free, and | |
74 has 6 internal XML parsers just in case you ever need to eat up some | |
75 memory. | |
76 | |
77 Just kidding. The auth-source library is simply a way for Emacs and | |
78 Gnus, among others, to find the answer to the old burning question ``I | |
79 have a server name and a port, what are my user name and password?'' | |
80 | |
81 The auth-source library actually supports more than just the user name | |
82 (known as the login) or the password, but only those two are in use | |
83 today in Emacs or Gnus. Similarly, the auth-source library can in | |
84 theory support multiple storage formats, but currently it only | |
85 understands the classic ``netrc'' format, examples of which you can | |
86 see later in this document. | |
102054 | 87 |
88 @node Help for users | |
89 @chapter Help for users | |
90 | |
104692 | 91 ``Netrc'' files are a de facto standard. They look like this: |
92 @example | |
93 machine mymachine login myloginname password mypassword port myport | |
94 @end example | |
102054 | 95 |
104692 | 96 The port is optional. If it's missing, auth-source will assume any |
97 port is OK. Actually the port is a protocol name or a port number so | |
98 you can have separate entries for port 143 and for protocol ``imap'' | |
99 if you fancy that. Anyway, you can just omit the port if you don't | |
100 need it. ``Netrc'' files are usually called @code{.authinfo} or | |
101 @code{.netrc}; nowadays @code{.authinfo} seems to be more popular and | |
102 the auth-source library encourages this confusion by making it the | |
103 default, as you'll see later. | |
104 | |
105 If you have problems with the port, set @var{auth-source-debug} to t | |
106 and see what port the library is checking in the @code{*Messages*} | |
107 buffer. Ditto for any other problems, your first step is always to | |
108 see what's being checked. The second step, of course, is to write a | |
109 blog entry about it and wait for the answer in the comments. | |
110 | |
111 You can customize the variable @var{auth-sources}. The following may | |
112 be needed if you are using an older version of Emacs or if the | |
113 auth-source library is not loaded for some other reason. | |
102054 | 114 |
115 @lisp | |
104692 | 116 (require 'auth-source) ;; probably not necessary |
102054 | 117 (customize-variable 'auth-sources) ;; optional, do it once |
118 @end lisp | |
119 | |
120 @defvar auth-sources | |
121 | |
122 The @var{auth-sources} variable tells the auth-source library where | |
123 your netrc files live for a particular host and protocol. While you | |
124 can get fancy, the default and simplest configuration is: | |
125 | |
126 @lisp | |
127 (setq auth-sources '((:source "~/.authinfo.gpg" :host t :protocol t))) | |
128 @end lisp | |
129 | |
104692 | 130 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 | |
132 want to move your netrc file, it will just work if you have that | |
133 file. You may not, though, so make sure it exists. | |
134 | |
135 By adding multiple entries to @var{auth-sources} with a particular | |
136 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 | |
138 shared netrc files or some other unusual setup (90% of Emacs users | |
139 have unusual setups and the remaining 10% are @emph{really} unusual). | |
102054 | 140 |
141 @end defvar | |
142 | |
143 If you don't customize @var{auth-sources}, you'll have to live with | |
144 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 | |
146 you set up EPA, which is strongly recommended. | |
147 | |
148 @lisp | |
149 (require 'epa-file) | |
150 (epa-file-enable) | |
104692 | 151 ;;; VERY important if you want symmetric encryption |
152 ;;; irrelevant if you don't | |
153 (setq epa-file-cache-passphrase-for-symmetric-encryption t) | |
102054 | 154 @end lisp |
155 | |
104692 | 156 The simplest working netrc line example is one without a port. |
157 | |
158 @example | |
159 machine YOURMACHINE login YOU password YOURPASSWORD | |
160 @end example | |
161 | |
162 This will match any authentication port. Simple, right? But what if | |
163 there's a SMTP server on port 433 of that machine that needs a | |
164 different password from the IMAP server? | |
165 | |
166 @example | |
167 machine YOURMACHINE login YOU password SMTPPASSWORD port 433 | |
168 machine YOURMACHINE login YOU password GENERALPASSWORD | |
169 @end example | |
170 | |
102054 | 171 For url-auth authentication (HTTP/HTTPS), you need to put this in your |
172 netrc file: | |
173 | |
174 @example | |
175 machine yourmachine.com:80 port http login testuser password testpass | |
176 @end example | |
177 | |
104692 | 178 This will match any realm and authentication method (basic or digest) |
179 over HTTP. HTTPS is set up similarly. If you want finer controls, | |
180 explore the url-auth source code and variables. | |
102054 | 181 |
182 For Tramp authentication, use: | |
183 | |
184 @example | |
185 machine yourmachine.com port scp login testuser password testpass | |
186 @end example | |
187 | |
188 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 | |
104692 | 190 earlier. Since Tramp has about 88 connection methods, this may be |
191 necessary if you have an unusual (see earlier comment on those) setup. | |
102054 | 192 |
193 @node Help for developers | |
194 @chapter Help for developers | |
195 | |
196 The auth-source library only has one function for external use. | |
197 | |
198 @defun auth-source-user-or-password mode host port | |
199 | |
200 Retrieve appropriate authentication tokens, determined by @var{mode}, | |
104692 | 201 for host @var{host} and @var{port}. If @var{auth-source-debug} is t, |
202 debugging messages will be printed. Set @var{auth-source-debug} to a | |
203 function to use that function for logging. The parameters passed will | |
204 be the same that the @code{message} function takes, that is, a string | |
205 formatting spec and optional parameters. | |
102054 | 206 |
207 If @var{mode} is a list of strings, the function will return a list of | |
104692 | 208 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 | |
210 string or a @code{nil} object. Currently only the modes ``login'' and | |
211 ``password'' are recognized but more may be added in the future. | |
102054 | 212 |
213 @var{host} is a string containing the host name. | |
214 | |
215 @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 | |
217 users' netrc files. | |
218 | |
219 @example | |
220 ;; IMAP example | |
221 (setq auth (auth-source-user-or-password | |
222 '("login" "password") | |
223 "anyhostnamehere" | |
224 "imap")) | |
225 (nth 0 auth) ; the login name | |
226 (nth 1 auth) ; the password | |
227 @end example | |
228 | |
229 @end defun | |
230 | |
231 @node Index | |
232 @chapter Index | |
233 @printindex cp | |
234 | |
235 @node Function Index | |
236 @chapter Function Index | |
237 @printindex fn | |
238 | |
239 @node Variable Index | |
240 @chapter Variable Index | |
241 @printindex vr | |
242 | |
243 @bye | |
244 | |
245 @c End: | |
246 | |
247 @ignore | |
248 arch-tag: 7b835fd3-473f-40fc-9776-1c4e49d26c94 | |
249 @end ignore |