1 \input texinfo @c -*-texinfo-*-
3 @include gnus-overrides.texi
5 @setfilename ../../info/auth
6 @settitle Emacs auth-source Library @value{VERSION}
11 This file describes the Emacs auth-source library.
13 Copyright @copyright{} 2008--2012 Free Software Foundation, Inc.
16 Permission is granted to copy, distribute and/or modify this document
17 under the terms of the GNU Free Documentation License, Version 1.3 or
18 any later version published by the Free Software Foundation; with no
19 Invariant Sections, with the Front-Cover texts being ``A GNU Manual,''
20 and with the Back-Cover Texts as in (a) below. A copy of the license
21 is included in the section entitled ``GNU Free Documentation License''.
23 (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
24 modify this GNU manual.''
28 @dircategory Emacs lisp libraries
30 * Auth-source: (auth). The Emacs auth-source library.
35 @title Emacs auth-source Library (DEVELOPMENT VERSION)
38 @title Emacs auth-source Library
40 @author by Ted Zlatanov
42 @vskip 0pt plus 1filll
50 @top Emacs auth-source
51 This manual describes the Emacs auth-source library.
53 It is a way for multiple applications to share a single configuration
54 (in Emacs and in files) for user convenience.
59 * Overview:: Overview of the auth-source library.
61 * Secret Service API::
62 * Help for developers::
63 * GnuPG and EasyPG Assistant Configuration::
64 * GNU Free Documentation License:: The license for this documentation.
74 The auth-source library is simply a way for Emacs and Gnus, among
75 others, to answer the old burning question ``What are my user name and
78 (This is different from the old question about burning ``Where is the
79 fire extinguisher, please?''.)
81 The auth-source library supports more than just the user name or the
82 password (known as the secret).
84 Similarly, the auth-source library supports multiple storage backend,
85 currently either the classic ``netrc'' backend, examples of which you
86 can see later in this document, or the Secret Service API@. This is
87 done with EIEIO-based backends and you can write your own if you want.
90 @chapter Help for users
92 ``Netrc'' files are a de facto standard. They look like this:
94 machine @var{mymachine} login @var{myloginname} password @var{mypassword} port @var{myport}
97 The @code{machine} is the server (either a DNS name or an IP address).
98 It's known as @var{:host} in @code{auth-source-search} queries. You
99 can also use @code{host}.
101 The @code{port} is the connection port or protocol. It's known as
102 @var{:port} in @code{auth-source-search} queries.
104 The @code{user} is the user name. It's known as @var{:user} in
105 @code{auth-source-search} queries. You can also use @code{login} and
108 Spaces are always OK as far as auth-source is concerned (but other
109 programs may not like them). Just put the data in quotes, escaping
110 quotes as you'd expect with @samp{\}.
112 All these are optional. You could just say (but we don't recommend
113 it, we're just showing that it's possible)
116 password @var{mypassword}
119 to use the same password everywhere. Again, @emph{DO NOT DO THIS} or
120 you will be pwned as the kids say.
122 ``Netrc'' files are usually called @file{.authinfo} or @file{.netrc};
123 nowadays @file{.authinfo} seems to be more popular and the auth-source
124 library encourages this confusion by accepting both, as you'll see
127 If you have problems with the search, set @code{auth-source-debug} to
128 @code{'trivia} and see what host, port, and user the library is
129 checking in the @samp{*Messages*} buffer. Ditto for any other
130 problems, your first step is always to see what's being checked. The
131 second step, of course, is to write a blog entry about it and wait for
132 the answer in the comments.
134 You can customize the variable @code{auth-sources}. The following may
135 be needed if you are using an older version of Emacs or if the
136 auth-source library is not loaded for some other reason.
139 (require 'auth-source) ;; probably not necessary
140 (customize-variable 'auth-sources) ;; optional, do it once
145 The @code{auth-sources} variable tells the auth-source library where
146 your netrc files or Secret Service API collection items live for a
147 particular host and protocol. While you can get fancy, the default
148 and simplest configuration is:
151 ;;; old default: required :host and :port, not needed anymore
152 (setq auth-sources '((:source "~/.authinfo.gpg" :host t :port t)))
153 ;;; mostly equivalent (see below about fallbacks) but shorter:
154 (setq auth-sources '((:source "~/.authinfo.gpg")))
155 ;;; even shorter and the @emph{default}:
156 (setq auth-sources '("~/.authinfo.gpg" "~/.authinfo" "~/.netrc"))
157 ;;; use the Secrets API @var{Login} collection (@pxref{Secret Service API})
158 (setq auth-sources '("secrets:Login"))
161 By adding multiple entries to @code{auth-sources} with a particular
162 host or protocol, you can have specific netrc files for that host or
163 protocol. Usually this is unnecessary but may make sense if you have
164 shared netrc files or some other unusual setup (90% of Emacs users
165 have unusual setups and the remaining 10% are @emph{really} unusual).
167 Here's a mixed example using two sources:
170 (setq auth-sources '((:source (:secrets default) :host "myserver" :user "joe")
176 If you don't customize @code{auth-sources}, you'll have to live with
177 the defaults: the unencrypted netrc file @file{~/.authinfo} will be
178 used for any host and any port.
180 If that fails, any host and any port are looked up in the netrc file
181 @file{~/.authinfo.gpg}, which is a GnuPG encrypted file (@pxref{GnuPG
182 and EasyPG Assistant Configuration}).
184 Finally, the unencrypted netrc file @file{~/.netrc} will be used for
185 any host and any port.
187 The typical netrc line example is without a port.
190 machine YOURMACHINE login YOU password YOURPASSWORD
193 This will match any authentication port. Simple, right? But what if
194 there's a SMTP server on port 433 of that machine that needs a
195 different password from the IMAP server?
198 machine YOURMACHINE login YOU password SMTPPASSWORD port 433
199 machine YOURMACHINE login YOU password GENERALPASSWORD
202 For url-auth authentication (HTTP/HTTPS), you need to put this in your
206 machine yourmachine.com:80 port http login testuser password testpass
209 This will match any realm and authentication method (basic or digest)
210 over HTTP@. HTTPS is set up similarly. If you want finer controls,
211 explore the url-auth source code and variables.
213 For Tramp authentication, use:
216 machine yourmachine.com port scp login testuser password testpass
219 Note that the port denotes the Tramp connection method. When you
220 don't use a port entry, you match any Tramp method, as explained
221 earlier. Since Tramp has about 88 connection methods, this may be
222 necessary if you have an unusual (see earlier comment on those) setup.
224 @node Secret Service API
225 @chapter Secret Service API
227 The @dfn{Secret Service API} is a standard from
228 @uref{http://www.freedesktop.org/wiki/Specifications/secret-storage-spec,,freedesktop.org}
229 to securely store passwords and other confidential information. This
230 API is implemented by system daemons such as the GNOME Keyring and the
231 KDE Wallet (these are GNOME and KDE packages respectively and should
232 be available on most modern GNU/Linux systems).
234 The auth-source library uses the @file{secrets.el} library to connect
235 through the Secret Service API@. You can also use that library in
236 other packages, it's not exclusive to auth-source.
238 @defvar secrets-enabled
239 After loading @file{secrets.el}, a non-@code{nil} value of this
240 variable indicates the existence of a daemon providing the Secret
244 @deffn Command secrets-show-secrets
245 This command shows all collections, items, and their attributes.
248 The atomic objects managed by the Secret Service API are @dfn{secret
249 items}, which contain things an application wishes to store securely,
250 like a password. Secret items have a label (a name), the @dfn{secret}
251 (which is the string we want, like a password), and a set of lookup
252 attributes. The attributes can be used to search and retrieve a
253 secret item at a later date.
255 Secret items are grouped in @dfn{collections}. A collection is
256 sometimes called a @samp{keyring} or @samp{wallet} in GNOME Keyring
257 and KDE Wallet but it's the same thing, a group of secrets.
258 Collections are personal and protected so only the owner can open them.
260 The most common collection is called @code{"login"}.
262 A collection can have an alias. The alias @code{"default"} is
263 commonly used so the clients don't have to know the specific name of
264 the collection they open. Other aliases are not supported yet.
265 Since aliases are globally accessible, set the @code{"default"} alias
266 only when you're sure it's appropriate.
268 @defun secrets-list-collections
269 This function returns all the collection names as a list.
272 @defun secrets-set-alias collection alias
273 Set @var{alias} as alias of collection labeled @var{collection}.
274 Currently only the alias @code{"default"} is supported.
277 @defun secrets-get-alias alias
278 Return the collection name @var{alias} is referencing to.
279 Currently only the alias @code{"default"} is supported.
282 Collections can be created and deleted by the functions
283 @code{secrets-create-collection} and @code{secrets-delete-collection}.
284 Usually, this is not done from within Emacs. Do not delete standard
285 collections such as @code{"login"}.
287 The special collection @code{"session"} exists for the lifetime of the
288 corresponding client session (in our case, Emacs's lifetime). It is
289 created automatically when Emacs uses the Secret Service interface and
290 it is deleted when Emacs is killed. Therefore, it can be used to
291 store and retrieve secret items temporarily. The @code{"session"}
292 collection is better than a persistent collection when the secret
293 items should not live longer than Emacs. The session collection can
294 be specified either by the string @code{"session"}, or by @code{nil},
295 whenever a collection parameter is needed in the following functions.
297 @defun secrets-list-items collection
298 Returns all the item labels of @var{collection} as a list.
301 @defun secrets-create-item collection item password &rest attributes
302 This function creates a new item in @var{collection} with label
303 @var{item} and password @var{password}. @var{attributes} are
304 key-value pairs set for the created item. The keys are keyword
305 symbols, starting with a colon. Example:
308 ;;; The session "session", the label is "my item"
309 ;;; and the secret (password) is "geheim"
310 (secrets-create-item "session" "my item" "geheim"
311 :method "sudo" :user "joe" :host "remote-host")
315 @defun secrets-get-secret collection item
316 Return the secret of item labeled @var{item} in @var{collection}.
317 If there is no such item, return @code{nil}.
320 @defun secrets-delete-item collection item
321 This function deletes item @var{item} in @var{collection}.
324 The lookup attributes, which are specified during creation of a
325 secret item, must be a key-value pair. Keys are keyword symbols,
326 starting with a colon; values are strings. They can be retrieved
327 from a given secret item and they can be used for searching of items.
329 @defun secrets-get-attribute collection item attribute
330 Returns the value of key @var{attribute} of item labeled @var{item} in
331 @var{collection}. If there is no such item, or the item doesn't own
332 this key, the function returns @code{nil}.
335 @defun secrets-get-attributes collection item
336 Return the lookup attributes of item labeled @var{item} in
337 @var{collection}. If there is no such item, or the item has no
338 attributes, it returns @code{nil}. Example:
341 (secrets-get-attributes "session" "my item")
342 @result{} ((:user . "joe") (:host ."remote-host"))
346 @defun secrets-search-items collection &rest attributes
347 Search for the items in @var{collection} with matching
348 @var{attributes}. The @var{attributes} are key-value pairs, as used
349 in @code{secrets-create-item}. Example:
352 (secrets-search-items "session" :user "joe")
353 @result{} ("my item" "another item")
357 The auth-source library uses the @file{secrets.el} library and thus
358 the Secret Service API when you specify a source matching
359 @code{"secrets:COLLECTION"}. For instance, you could use
360 @code{"secrets:session"} to use the @code{"session"} collection, open only
361 for the lifetime of Emacs. Or you could use @code{"secrets:Login"} to
362 open the @code{"Login"} collection. As a special case, you can use the
363 symbol @code{default} in @code{auth-sources} (not a string, but a
364 symbol) to specify the @code{"default"} alias. Here is a contrived
365 example that sets @code{auth-sources} to search three collections and
366 then fall back to @file{~/.authinfo.gpg}.
369 (setq auth-sources '(default
375 @node Help for developers
376 @chapter Help for developers
378 The auth-source library lets you control logging output easily.
380 @defvar auth-source-debug
381 Set this variable to @code{'trivia} to see lots of output in
382 @samp{*Messages*}, or set it to a function that behaves like
383 @code{message} to do your own logging.
386 The auth-source library only has a few functions for external use.
388 @defun auth-source-search &rest spec &key type max host user port secret require create delete &allow-other-keys
389 This function searches (or modifies) authentication backends according
390 to @var{spec}. See the function's doc-string for details.
391 @c TODO more details.
394 Let's take a look at an example of using @code{auth-source-search}
395 from Gnus's @code{nnimap.el}.
398 (defun nnimap-credentials (address ports)
399 (let* ((auth-source-creation-prompts
400 '((user . "IMAP user at %h: ")
401 (secret . "IMAP password for %u@@%h: ")))
402 (found (nth 0 (auth-source-search :max 1
405 :require '(:user :secret)
408 (list (plist-get found :user)
409 (let ((secret (plist-get found :secret)))
410 (if (functionp secret)
413 (plist-get found :save-function))
417 This call requires the user and password (secret) to be in the
418 results. It also requests that an entry be created if it doesn't
419 exist already. While the created entry is being assembled, the shown
420 prompts will be used to interact with the user. The caller can also
421 pass data in @code{auth-source-creation-defaults} to supply defaults
422 for any of the prompts.
424 Note that the password needs to be evaluated if it's a function. It's
425 wrapped in a function to provide some security.
427 Later, after a successful login, @code{nnimap.el} calls the
428 @code{:save-function} like so:
431 (when (functionp (nth 2 credentials))
432 (funcall (nth 2 credentials)))
435 This will work whether the @code{:save-function} was provided or not.
436 @code{:save-function} will be provided only when a new entry was
437 created, so this effectively says ``after a successful login, save the
438 authentication information we just used, if it was newly created.''
440 After the first time it's called, the @code{:save-function} will not
441 run again (but it will log something if you have set
442 @code{auth-source-debug} to @code{'trivia}). This is so it won't ask
443 the same question again, which is annoying. This is so it won't ask
444 the same question again, which is annoying. This is so it won't ask
445 the same question again, which is annoying.
447 So the responsibility of the API user that specified @code{:create t}
448 is to call the @code{:save-function} if it's provided.
450 @defun auth-source-delete &rest spec &key delete &allow-other-keys
451 This function deletes entries matching @var{spec} from the
452 authentication backends. It returns the entries that were deleted.
453 The backend may not actually delete the entries.
456 @defun auth-source-forget spec
457 This function forgets any cached data that exactly matches @var{spec}.
458 It returns @code{t} if it forget some data, and @code{nil} if no
459 matching data was found.
462 @defun auth-source-forget+ &rest spec &allow-other-keys
463 This function forgets any cached data matching @var{spec}.
464 It returns the number of items forgotten.
467 @node GnuPG and EasyPG Assistant Configuration
468 @appendix GnuPG and EasyPG Assistant Configuration
470 If you don't customize @code{auth-sources}, the auth-source library
471 reads @file{~/.authinfo.gpg}, which is a GnuPG encrypted file. Then
472 it will check @file{~/.authinfo} but it's not recommended to use such
475 In Emacs 23 or later there is an option @code{auto-encryption-mode} to
476 automatically decrypt @file{*.gpg} files. It is enabled by default.
477 If you are using earlier versions of Emacs, you will need:
484 If you want your GnuPG passwords to be cached, set up @code{gpg-agent}
486 (@pxref{Caching Passphrases, , Caching Passphrases, epa}).
488 To quick start, here are some questions:
492 Do you use GnuPG version 2 instead of GnuPG version 1?
494 Do you use symmetric encryption rather than public key encryption?
496 Do you want to use gpg-agent?
499 Here are configurations depending on your answers:
501 @multitable {111} {222} {333} {configuration configuration configuration}
502 @item @b{1} @tab @b{2} @tab @b{3} @tab Configuration
503 @item Yes @tab Yes @tab Yes @tab Set up gpg-agent.
504 @item Yes @tab Yes @tab No @tab You can't, without gpg-agent.
505 @item Yes @tab No @tab Yes @tab Set up gpg-agent.
506 @item Yes @tab No @tab No @tab You can't, without gpg-agent.
507 @item No @tab Yes @tab Yes @tab Set up elisp passphrase cache.
508 @item No @tab Yes @tab No @tab Set up elisp passphrase cache.
509 @item No @tab No @tab Yes @tab Set up gpg-agent.
510 @item No @tab No @tab No @tab You can't, without gpg-agent.
513 To set up gpg-agent, follow the instruction in GnuPG manual
514 (@pxref{Invoking GPG-AGENT, , Invoking GPG-AGENT, gnupg}).
516 To set up elisp passphrase cache, set
517 @code{epa-file-cache-passphrase-for-symmetric-encryption}.
519 @node GNU Free Documentation License
520 @appendix GNU Free Documentation License
521 @include doclicense.texi
528 @unnumbered Function Index
532 @unnumbered Variable Index