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 | |
c8a28261 | 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:: | |
60 | * Help for developers:: | |
61 | * Index:: | |
62 | * Function Index:: | |
63 | * Variable Index:: | |
64 | @end menu | |
5dc584b5 | 65 | @end ifnottex |
9eb59592 MB |
66 | |
67 | @node Overview | |
68 | @chapter Overview | |
69 | ||
38dc51ba KY |
70 | 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 | server name and a port, what are my user name and password?'' | |
b0b63450 MB |
73 | |
74 | 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 | today in Emacs or Gnus. Similarly, the auth-source library can in | |
77 | theory support multiple storage formats, but currently it only | |
78 | understands the classic ``netrc'' format, examples of which you can | |
79 | see later in this document. | |
9eb59592 MB |
80 | |
81 | @node Help for users | |
82 | @chapter Help for users | |
83 | ||
b0b63450 MB |
84 | ``Netrc'' files are a de facto standard. They look like this: |
85 | @example | |
38dc51ba | 86 | machine @var{mymachine} login @var{myloginname} password @var{mypassword} port @var{myport} |
b0b63450 | 87 | @end example |
9eb59592 | 88 | |
38dc51ba KY |
89 | The machine is the server (either a DNS name or an IP address). |
90 | ||
b0b63450 MB |
91 | The port is optional. If it's missing, auth-source will assume any |
92 | port is OK. Actually the port is a protocol name or a port number so | |
38dc51ba KY |
93 | you can have separate entries for port @var{143} and for protocol |
94 | @var{imap} if you fancy that. Anyway, you can just omit the port if | |
95 | you don't need it. | |
96 | ||
97 | The login and password are simply your login credentials to the server. | |
98 | ||
99 | ``Netrc'' files are usually called @code{.authinfo} or @code{.netrc}; | |
100 | nowadays @code{.authinfo} seems to be more popular and the auth-source | |
101 | library encourages this confusion by making it the default, as you'll | |
102 | see later. | |
103 | ||
104 | If you have problems with the port, set @code{auth-source-debug} to | |
105 | @code{t} and see what port the library is checking in the | |
106 | @code{*Messages*} buffer. Ditto for any other problems, your first | |
107 | step is always to see what's being checked. The second step, of | |
108 | course, is to write a blog entry about it and wait for the answer in | |
109 | the comments. | |
110 | ||
111 | You can customize the variable @code{auth-sources}. The following may | |
b0b63450 MB |
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. | |
9eb59592 MB |
114 | |
115 | @lisp | |
b0b63450 | 116 | (require 'auth-source) ;; probably not necessary |
9eb59592 MB |
117 | (customize-variable 'auth-sources) ;; optional, do it once |
118 | @end lisp | |
119 | ||
120 | @defvar auth-sources | |
121 | ||
38dc51ba | 122 | The @code{auth-sources} variable tells the auth-source library where |
9eb59592 MB |
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 | ||
b0b63450 MB |
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. | |
9eb59592 | 134 | |
38dc51ba | 135 | By adding multiple entries to @code{auth-sources} with a particular |
b0b63450 MB |
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). | |
9eb59592 | 140 | |
b0b63450 | 141 | @end defvar |
9eb59592 | 142 | |
38dc51ba | 143 | If you don't customize @code{auth-sources}, you'll have to live with |
9eb59592 MB |
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) | |
b0b63450 MB |
151 | ;;; VERY important if you want symmetric encryption |
152 | ;;; irrelevant if you don't | |
153 | (setq epa-file-cache-passphrase-for-symmetric-encryption t) | |
9eb59592 MB |
154 | @end lisp |
155 | ||
b0b63450 MB |
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 | ||
9eb59592 MB |
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 | ||
b0b63450 MB |
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. | |
9eb59592 MB |
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 | |
b0b63450 MB |
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. | |
9eb59592 MB |
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}, | |
38dc51ba KY |
201 | for host @var{host} and @var{port}. If @code{auth-source-debug} is t, |
202 | debugging messages will be printed. Set @code{auth-source-debug} to a | |
b0b63450 MB |
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. | |
9eb59592 MB |
206 | |
207 | If @var{mode} is a list of strings, the function will return a list of | |
b0b63450 MB |
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. | |
9eb59592 MB |
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 | ||
9eb59592 MB |
243 | @bye |
244 | ||
245 | @c End: | |
246 | ||
247 | @ignore | |
248 | arch-tag: 7b835fd3-473f-40fc-9776-1c4e49d26c94 | |
249 | @end ignore |