1 \input texinfo @c -*-texinfo-*-
3 @include gnus-overrides.texi
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''
24 (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
25 modify this GNU manual. Buying copies from the FSF supports it in
26 developing GNU and promoting software freedom.''
28 This document is part of a collection distributed under the GNU Free
29 Documentation License. If you want to distribute this document
30 separately from the collection, you can do so by adding a copy of the
31 license to the document, as described in section 6 of the license.
35 @dircategory Emacs lisp libraries
37 * Auth-source: (auth). The Emacs auth-source library.
42 @title Emacs auth-source Library (DEVELOPMENT VERSION)
45 @title Emacs auth-source Library
47 @author by Ted Zlatanov
49 @vskip 0pt plus 1filll
57 @top Emacs auth-source
58 This manual describes the Emacs auth-source library.
60 It is a way for multiple applications to share a single configuration
61 (in Emacs and in files) for user convenience.
66 * Overview:: Overview of the auth-source library.
68 * Secret Service API::
69 * Help for developers::
70 * GnuPG and EasyPG Assistant Configuration::
80 The auth-source library is simply a way for Emacs and Gnus, among
81 others, to answer the old burning question ``What are my user name and
84 (This is different from the old question about burning ``Where is the
85 fire extinguisher, please?''.)
87 The auth-source library supports more than just the user name or the
88 password (known as the secret).
90 Similarly, the auth-source library supports multiple storage backend,
91 currently either the classic ``netrc'' backend, examples of which you
92 can see later in this document, or the Secret Service API. This is
93 done with EIEIO-based backends and you can write your own if you want.
96 @chapter Help for users
98 ``Netrc'' files are a de facto standard. They look like this:
100 machine @var{mymachine} login @var{myloginname} password @var{mypassword} port @var{myport}
103 The @code{machine} is the server (either a DNS name or an IP address).
104 It's known as @var{:host} in @code{auth-source-search} queries. You
105 can also use @code{host}.
107 The @code{port} is the connection port or protocol. It's known as
108 @var{:port} in @code{auth-source-search} queries.
110 The @code{user} is the user name. It's known as @var{:user} in
111 @code{auth-source-search} queries. You can also use @code{login} and
114 Spaces are always OK as far as auth-source is concerned (but other
115 programs may not like them). Just put the data in quotes, escaping
116 quotes as you'd expect with @samp{\}.
118 All these are optional. You could just say (but we don't recommend
119 it, we're just showing that it's possible)
122 password @var{mypassword}
125 to use the same password everywhere. Again, @emph{DO NOT DO THIS} or
126 you will be pwned as the kids say.
128 ``Netrc'' files are usually called @file{.authinfo} or @file{.netrc};
129 nowadays @file{.authinfo} seems to be more popular and the auth-source
130 library encourages this confusion by accepting both, as you'll see
133 If you have problems with the search, set @code{auth-source-debug} to
134 @code{'trivia} and see what host, port, and user the library is
135 checking in the @samp{*Messages*} buffer. Ditto for any other
136 problems, your first step is always to see what's being checked. The
137 second step, of course, is to write a blog entry about it and wait for
138 the answer in the comments.
140 You can customize the variable @code{auth-sources}. The following may
141 be needed if you are using an older version of Emacs or if the
142 auth-source library is not loaded for some other reason.
145 (require 'auth-source) ;; probably not necessary
146 (customize-variable 'auth-sources) ;; optional, do it once
151 The @code{auth-sources} variable tells the auth-source library where
152 your netrc files or Secret Service API collection items live for a
153 particular host and protocol. While you can get fancy, the default
154 and simplest configuration is:
157 ;;; old default: required :host and :port, not needed anymore
158 (setq auth-sources '((:source "~/.authinfo.gpg" :host t :port t)))
159 ;;; mostly equivalent (see below about fallbacks) but shorter:
160 (setq auth-sources '((:source "~/.authinfo.gpg")))
161 ;;; even shorter and the @emph{default}:
162 (setq auth-sources '("~/.authinfo.gpg" "~/.authinfo" "~/.netrc"))
163 ;;; use the Secrets API @var{Login} collection (@pxref{Secret Service API})
164 (setq auth-sources '("secrets:Login"))
167 By adding multiple entries to @code{auth-sources} with a particular
168 host or protocol, you can have specific netrc files for that host or
169 protocol. Usually this is unnecessary but may make sense if you have
170 shared netrc files or some other unusual setup (90% of Emacs users
171 have unusual setups and the remaining 10% are @emph{really} unusual).
173 Here's a mixed example using two sources:
176 (setq auth-sources '((:source (:secrets default) :host "myserver" :user "joe")
182 If you don't customize @code{auth-sources}, you'll have to live with
183 the defaults: any host and any port are looked up in the netrc
184 file @file{~/.authinfo.gpg}, which is a GnuPG encrypted file
185 (@pxref{GnuPG and EasyPG Assistant Configuration}).
187 If that fails, the unencrypted netrc files @file{~/.authinfo} and
188 @file{~/.netrc} will be used.
190 The typical netrc line example is without a port.
193 machine YOURMACHINE login YOU password YOURPASSWORD
196 This will match any authentication port. Simple, right? But what if
197 there's a SMTP server on port 433 of that machine that needs a
198 different password from the IMAP server?
201 machine YOURMACHINE login YOU password SMTPPASSWORD port 433
202 machine YOURMACHINE login YOU password GENERALPASSWORD
205 For url-auth authentication (HTTP/HTTPS), you need to put this in your
209 machine yourmachine.com:80 port http login testuser password testpass
212 This will match any realm and authentication method (basic or digest)
213 over HTTP. HTTPS is set up similarly. If you want finer controls,
214 explore the url-auth source code and variables.
216 For Tramp authentication, use:
219 machine yourmachine.com port scp login testuser password testpass
222 Note that the port denotes the Tramp connection method. When you
223 don't use a port entry, you match any Tramp method, as explained
224 earlier. Since Tramp has about 88 connection methods, this may be
225 necessary if you have an unusual (see earlier comment on those) setup.
227 @node Secret Service API
228 @chapter Secret Service API
230 The @dfn{Secret Service API} is a standard from
231 @uref{http://www.freedesktop.org/wiki/Specifications/secret-storage-spec,,freedesktop.org}
232 to securely store passwords and other confidential information.
233 Implementations of compliant daemons are the GNOME Keyring and the KDE
236 The auth-source library uses the @file{secrets.el} library as an
237 interface to this feature. You can also use that library in other
240 @defvar secrets-enabled
241 After loading @file{secrets.el}, a non-@code{nil} value of this
242 variable indicates the existence of a daemon providing the Secret
246 @deffn Command secrets-show-secrets
247 This command inspects all collections, items, and their attributes.
250 The atomic objects to be managed by the Secret Service API are
251 @dfn{secret items}, which are something an application wishes to store
252 securely. A good example is a password that an application needs to
253 save and use at a later date.
255 Secret items are grouped in @dfn{collections}. A collection is
256 similar in concept to the terms @samp{keyring} or @samp{wallet}. A
257 common collection is called @samp{"login"}. A collection is stored
258 permanently under the user's permissions, and can be accessed in a
259 user session context.
261 A collection can have an alias name. The use case for this is to
262 set the alias @samp{"default"} for a given collection, making it
263 transparent to clients as to which collection is used. Other aliases
264 are not supported (yet). Since an alias is visible to all
265 applications, this setting should be performed with care.
267 @defun secrets-list-collections
268 This function returns a list of collection names.
271 @defun secrets-set-alias collection alias
272 Set @var{alias} as alias of collection labeled @var{collection}.
273 For the time being, only the alias @samp{"default"} is supported.
276 @defun secrets-get-alias alias
277 Return the collection name @var{alias} is referencing to.
278 For the time being, only the alias @samp{"default"} is supported.
281 Collections can be created and deleted by the functions
282 @code{secrets-create-collection} and @code{secrets-delete-collection}.
283 Usually, this is not applied from within Emacs. Common collections,
284 like @samp{"login"}, should never be deleted.
286 There exists a special collection called @samp{"session"}, which has
287 the lifetime of the corresponding client session (aka Emacs's
288 lifetime). It is created automatically when Emacs uses the Secret
289 Service interface, and it is deleted when Emacs is killed. Therefore,
290 it can be used to store and retrieve secret items temporarily. This
291 should be preferred over creation of a persistent collection, when the
292 information should not live longer than Emacs. The session collection
293 can be addressed either by the string @samp{"session"}, or by
294 @code{nil}, whenever a collection parameter is needed in the following
297 As already said, a collection is a group of secret items. A secret
298 item has a label, the @dfn{secret} (which is a string), and a set of
299 lookup attributes. The attributes can be used to search and retrieve
300 a secret item at a later date.
302 @defun secrets-list-items collection
303 Returns a list of all item labels of @var{collection}.
306 @defun secrets-create-item collection item password &rest attributes
307 This function creates a new item in @var{collection} with label
308 @var{item} and password @var{password}. @var{attributes} are
309 key-value pairs set for the created item. The keys are keyword
310 symbols, starting with a colon. Example:
313 (secrets-create-item "session" "my item" "geheim"
314 :method "sudo" :user "joe" :host "remote-host")
318 @defun secrets-get-secret collection item
319 Return the secret of item labeled @var{item} in @var{collection}.
320 If there is no such item, return @code{nil}.
323 @defun secrets-delete-item collection item
324 This function deletes item @var{item} in @var{collection}.
327 The lookup attributes, which are specified during creation of a
328 secret item, must be a key-value pair. Keys are keyword symbols,
329 starting with a colon; values are strings. They can be retrieved
330 from a given secret item, and they can be used for searching of items.
332 @defun secrets-get-attribute collection item attribute
333 Returns the value of key @var{attribute} of item labeled @var{item} in
334 @var{collection}. If there is no such item, or the item doesn't own
335 this key, the function returns @code{nil}.
338 @defun secrets-get-attributes collection item
339 Return the lookup attributes of item labeled @var{item} in
340 @var{collection}. If there is no such item, or the item has no
341 attributes, it returns @code{nil}. Example:
344 (secrets-get-attributes "session" "my item")
345 @result{} ((:user . "joe") (:host ."remote-host"))
349 @defun secrets-search-items collection &rest attributes
350 Search items in @var{collection} with @var{attributes}.
351 @var{attributes} are key-value pairs, as used in
352 @code{secrets-create-item}. Example:
355 (secrets-search-items "session" :user "joe")
356 @result{} ("my item" "another item")
360 @node Help for developers
361 @chapter Help for developers
363 The auth-source library lets you control logging output easily.
365 @defvar auth-source-debug
366 Set this variable to @code{'trivia} to see lots of output in
367 @samp{*Messages*}, or set it to a function that behaves like
368 @code{message} to do your own logging.
371 The auth-source library only has a few functions for external use.
373 @defun auth-source-search &rest spec &key type max host user port secret require create delete &allow-other-keys
374 This function searches (or modifies) authentication backends according
375 to @var{spec}. See the function's doc-string for details.
376 @c TODO more details.
379 Let's take a look at an example of using @code{auth-source-search}
380 from Gnus's @code{nnimap.el}.
383 (defun nnimap-credentials (address ports)
384 (let* ((auth-source-creation-prompts
385 '((user . "IMAP user at %h: ")
386 (secret . "IMAP password for %u@@%h: ")))
387 (found (nth 0 (auth-source-search :max 1
390 :require '(:user :secret)
393 (list (plist-get found :user)
394 (let ((secret (plist-get found :secret)))
395 (if (functionp secret)
398 (plist-get found :save-function))
402 This call requires the user and password (secret) to be in the
403 results. It also requests that an entry be created if it doesn't
404 exist already. While the created entry is being assembled, the shown
405 prompts will be used to interact with the user. The caller can also
406 pass data in @code{auth-source-creation-defaults} to supply defaults
407 for any of the prompts.
409 Note that the password needs to be evaluated if it's a function. It's
410 wrapped in a function to provide some security.
412 Later, after a successful login, @code{nnimap.el} calls the
413 @code{:save-function} like so:
416 (when (functionp (nth 2 credentials))
417 (funcall (nth 2 credentials)))
420 This will work whether the @code{:save-function} was provided or not.
421 @code{:save-function} will be provided only when a new entry was
422 created, so this effectively says ``after a successful login, save the
423 authentication information we just used, if it was newly created.''
425 After the first time it's called, the @code{:save-function} will not
426 run again (but it will log something if you have set
427 @code{auth-source-debug} to @code{'trivia}). This is so it won't ask
428 the same question again, which is annoying. This is so it won't ask
429 the same question again, which is annoying. This is so it won't ask
430 the same question again, which is annoying.
432 So the responsibility of the API user that specified @code{:create t}
433 is to call the @code{:save-function} if it's provided.
435 @defun auth-source-delete &rest spec &key delete &allow-other-keys
436 This function deletes entries matching @var{spec} from the
437 authentication backends. It returns the entries that were deleted.
438 The backend may not actually delete the entries.
441 @defun auth-source-forget spec
442 This function forgets any cached data that exactly matches @var{spec}.
443 It returns @code{t} if it forget some data, and @code{nil} if no
444 matching data was found.
447 @defun auth-source-forget+ &rest spec &allow-other-keys
448 This function forgets any cached data matching @var{spec}.
449 It returns the number of items forgotten.
452 @node GnuPG and EasyPG Assistant Configuration
453 @appendix GnuPG and EasyPG Assistant Configuration
455 If you don't customize @code{auth-sources}, the auth-source library
456 reads @file{~/.authinfo.gpg}, which is a GnuPG encrypted file. Then
457 it will check @file{~/.authinfo} but it's not recommended to use such
460 In Emacs 23 or later there is an option @code{auto-encryption-mode} to
461 automatically decrypt @file{*.gpg} files. It is enabled by default.
462 If you are using earlier versions of Emacs, you will need:
469 If you want your GnuPG passwords to be cached, set up @code{gpg-agent}
471 (@pxref{Caching Passphrases, , Caching Passphrases, epa}).
473 To quick start, here are some questions:
477 Do you use GnuPG version 2 instead of GnuPG version 1?
479 Do you use symmetric encryption rather than public key encryption?
481 Do you want to use gpg-agent?
484 Here are configurations depending on your answers:
486 @multitable {111} {222} {333} {configuration configuration configuration}
487 @item @b{1} @tab @b{2} @tab @b{3} @tab Configuration
488 @item Yes @tab Yes @tab Yes @tab Set up gpg-agent.
489 @item Yes @tab Yes @tab No @tab You can't, without gpg-agent.
490 @item Yes @tab No @tab Yes @tab Set up gpg-agent.
491 @item Yes @tab No @tab No @tab You can't, without gpg-agent.
492 @item No @tab Yes @tab Yes @tab Set up elisp passphrase cache.
493 @item No @tab Yes @tab No @tab Set up elisp passphrase cache.
494 @item No @tab No @tab Yes @tab Set up gpg-agent.
495 @item No @tab No @tab No @tab You can't, without gpg-agent.
498 To set up gpg-agent, follow the instruction in GnuPG manual
499 (@pxref{Invoking GPG-AGENT, , Invoking GPG-AGENT, gnupg}).
501 To set up elisp passphrase cache, set
502 @code{epa-file-cache-passphrase-for-symmetric-encryption}.
509 @chapter Function Index
513 @chapter Variable Index