* nnimap.el: Use nnheader-message throughout.
[gnus] / texi / auth.texi
1 \input texinfo                  @c -*-texinfo-*-
2 @setfilename auth
3 @settitle Emacs auth-source Library @value{VERSION}
4
5 @set VERSION 0.2
6
7 @copying
8 This file describes the Emacs auth-source library.
9
10 Copyright @copyright{} 2008, 2009, 2010 Free Software Foundation, Inc.
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
32 @dircategory Emacs
33 @direntry
34 * Auth-source: (auth).          The Emacs auth-source library.
35 @end direntry
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
45 @contents
46
47 @ifnottex
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
55 @insertcopying
56
57 @menu
58 * Overview::                    Overview of the auth-source library.
59 * Help for users::              
60 * Secret Service API::          
61 * Help for developers::         
62 * GnuPG and EasyPG Assistant Configuration::  
63 * Index::                       
64 * Function Index::              
65 * Variable Index::              
66 @end menu
67 @end ifnottex
68
69 @node Overview
70 @chapter Overview
71
72 The auth-source library is simply a way for Emacs and Gnus, among
73 others, to answer the old burning question ``I have a server name and
74 a port, what are my user name and password?''
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
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.
82
83 @node Help for users
84 @chapter Help for users
85
86 ``Netrc'' files are a de facto standard.  They look like this:
87 @example
88 machine @var{mymachine} login @var{myloginname} password @var{mypassword} port @var{myport}
89 @end example
90
91 The machine is the server (either a DNS name or an IP address).
92
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
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
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.
116
117 @lisp
118 (require 'auth-source)             ;; probably not necessary
119 (customize-variable 'auth-sources) ;; optional, do it once
120 @end lisp
121
122 @defvar auth-sources
123
124 The @code{auth-sources} variable tells the auth-source library where
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:
128
129 @lisp
130 ;;; old default: required :host and :protocol, not needed anymore
131 (setq auth-sources '((:source "~/.authinfo.gpg" :host t :protocol t)))
132 ;;; mostly equivalent (see below about fallbacks) but shorter:
133 (setq auth-sources '((:source "~/.authinfo.gpg")))
134 @end lisp
135
136 This says ``for any host and any protocol, use just that one file.''
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.
140
141 By adding multiple entries to @code{auth-sources} with a particular
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).
146
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
176 @end defvar
177
178 If you don't customize @code{auth-sources}, you'll have to live with
179 the defaults: any host and any port are looked up in the netrc
180 file @code{~/.authinfo.gpg}, which is a GnuPG encrypted file
181 (@pxref{GnuPG and EasyPG Assistant Configuration}).
182
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
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
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.
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
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.
219
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
225 @node Help for developers
226 @chapter Help for developers
227
228 The auth-source library only has one function for external use.
229
230 @defun auth-source-user-or-password mode host port &optional username
231
232 Retrieve appropriate authentication tokens, determined by @var{mode},
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
238 formatting spec and optional parameters.
239
240 If @var{mode} is a list of strings, the function will return a list of
241 strings or @code{nil} objects (thus you can avoid parsing the netrc
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.
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
253 @var{username} contains the user name (e.g. ``joe'') as a string.
254
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
267 @node GnuPG and EasyPG Assistant Configuration
268 @appendix GnuPG and EasyPG Assistant Configuration
269
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
273 In Emacs 23 or later there is an option @code{auto-encryption-mode} to
274 automatically decrypt @code{*.gpg} files.  It is enabled by default.
275 If you are using earlier versions of Emacs, you will need:
276
277 @lisp
278 (require 'epa-file)
279 (epa-file-enable)
280 @end lisp
281
282 If you want your GnuPG passwords to be cached, set up @code{gpg-agent}
283 or EasyPG Assitant
284 @xref{Caching Passphrases, , Caching Passphrases, epa}
285
286 To quick start, here are some questions:
287
288 @enumerate
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?
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
301 @item Yes @tab Yes @tab Yes @tab Set up gpg-agent.
302 @item Yes @tab Yes @tab No @tab You can't, without gpg-agent.
303 @item Yes @tab No @tab Yes @tab Set up gpg-agent.
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.
307 @item No @tab No @tab Yes @tab Set up gpg-agent.
308 @item No @tab No @tab No @tab You can't, without gpg-agent.
309 @end multitable
310
311 To set up gpg-agent, follow the instruction in GnuPG manual
312 (@pxref{Invoking GPG-AGENT, , Invoking GPG-AGENT, gnupg}).
313
314 To set up elisp passphrase cache, set
315 @code{epa-file-cache-passphrase-for-symmetric-encryption}.
316
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
329 @bye
330
331 @c End: