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 @xref{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.