1 \input texinfo @c -*-texinfo-*-
3 @settitle Emacs auth-source Library @value{VERSION}
8 This file describes the Emacs auth-source library.
10 Copyright @copyright{} 2008, 2009, 2010 Free Software Foundation, Inc.
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''
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.''
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.
34 * Auth-source: (auth). The Emacs auth-source library.
38 @title Emacs auth-source Library
39 @author by Ted Zlatanov
41 @vskip 0pt plus 1filll
49 @top Emacs auth-source
50 This manual describes the Emacs auth-source library.
52 It is a way for multiple applications to share a single configuration
53 (in Emacs and in files) for user convenience.
58 * Overview:: Overview of the auth-source library.
60 * Secret Service API::
61 * Help for developers::
62 * GnuPG and EasyPG Assistant Configuration::
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?''
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
84 @chapter Help for users
86 ``Netrc'' files are a de facto standard. They look like this:
88 machine @var{mymachine} login @var{myloginname} password @var{mypassword} port @var{myport}
91 The machine is the server (either a DNS name or an IP address).
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
99 The login and password are simply your login credentials to the server.
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
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
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.
118 (require 'auth-source) ;; probably not necessary
119 (customize-variable 'auth-sources) ;; optional, do it once
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:
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")))
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.
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).
147 Here's an example that uses the Secret Service API for all lookups,
148 using the default collection:
151 (setq auth-sources '((:source (:secrets default))))
154 And here's a mixed example, using two sources:
157 (setq auth-sources '((:source (:secrets default) :host "myserver" :user "joe")
158 (:source "~/.authinfo.gpg")))
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}.
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
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}).
183 The simplest working netrc line example is one without a port.
186 machine YOURMACHINE login YOU password YOURPASSWORD
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?
194 machine YOURMACHINE login YOU password SMTPPASSWORD port 433
195 machine YOURMACHINE login YOU password GENERALPASSWORD
198 For url-auth authentication (HTTP/HTTPS), you need to put this in your
202 machine yourmachine.com:80 port http login testuser password testpass
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.
209 For Tramp authentication, use:
212 machine yourmachine.com port scp login testuser password testpass
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.
220 @node Secret Service API
221 @chapter Secret Service API
223 TODO: how does it work generally, how does secrets.el work, some examples.
225 @node Help for developers
226 @chapter Help for developers
228 The auth-source library only has one function for external use.
230 @defun auth-source-user-or-password mode host port &optional username
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.
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.
247 @var{host} is a string containing the host name.
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
253 @var{username} contains the user name (e.g. ``joe'') as a string.
257 (setq auth (auth-source-user-or-password
258 '("login" "password")
261 (nth 0 auth) ; the login name
262 (nth 1 auth) ; the password
267 @node GnuPG and EasyPG Assistant Configuration
268 @appendix GnuPG and EasyPG Assistant Configuration
270 If you don't customize @code{auth-sources}, the auth-source library
271 reads @code{~/.authinfo.gpg}, which is a GnuPG encrypted file.
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:
282 If you want your GnuPG passwords to be cached, set up @code{gpg-agent}
284 (@pxref{Caching Passphrases, , Caching Passphrases, epa}).
286 To quick start, here are some questions:
290 Do you use GnuPG version 2 instead of GnuPG version 1?
292 Do you use symmetric encryption rather than public key encryption?
294 Do you want to use gpg-agent?
297 Here are configurations depending on your answers:
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.
311 To set up gpg-agent, follow the instruction in GnuPG manual
312 (@pxref{Invoking GPG-AGENT, , Invoking GPG-AGENT, gnupg}).
314 To set up elisp passphrase cache, set
315 @code{epa-file-cache-passphrase-for-symmetric-encryption}.
322 @chapter Function Index
326 @chapter Variable Index