* auth.texi (Multiple GMail accounts with Gnus): Add FAQ.
[gnus] / texi / auth.texi
1 \input texinfo                  @c -*-texinfo-*-
2
3 @include gnus-overrides.texi
4
5 @set VERSION 0.3
6
7 @setfilename auth.info
8 @settitle Emacs auth-source Library @value{VERSION}
9 @documentencoding UTF-8
10
11 @copying
12 This file describes the Emacs auth-source library.
13
14 Copyright @copyright{} 2008--2015 Free Software Foundation, Inc.
15
16 @quotation
17 Permission is granted to copy, distribute and/or modify this document
18 under the terms of the GNU Free Documentation License, Version 1.3 or
19 any later version published by the Free Software Foundation; with no
20 Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,''
21 and with the Back-Cover Texts as in (a) below.  A copy of the license
22 is included in the section entitled ``GNU Free Documentation License''.
23
24 (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
25 modify this GNU manual.''
26 @end quotation
27 @end copying
28
29 @dircategory Emacs lisp libraries
30 @direntry
31 * Auth-source: (auth).          The Emacs auth-source library.
32 @end direntry
33
34 @titlepage
35 @ifset WEBHACKDEVEL
36 @title Emacs auth-source Library (DEVELOPMENT VERSION)
37 @end ifset
38 @ifclear WEBHACKDEVEL
39 @title Emacs auth-source Library
40 @end ifclear
41 @author by Ted Zlatanov
42 @page
43 @vskip 0pt plus 1filll
44 @insertcopying
45 @end titlepage
46
47 @contents
48
49 @ifnottex
50 @node Top
51 @top Emacs auth-source
52 This manual describes the Emacs auth-source library.
53
54 It is a way for multiple applications to share a single configuration
55 (in Emacs and in files) for user convenience.
56
57 @insertcopying
58
59 @menu
60 * Overview::                    Overview of the auth-source library.
61 * Help for users::
62 * Multiple GMail accounts with Gnus::
63 * Secret Service API::
64 * Help for developers::
65 * GnuPG and EasyPG Assistant Configuration::
66 * GNU Free Documentation License::  The license for this documentation.
67 * Index::
68 * Function Index::
69 * Variable Index::
70 @end menu
71 @end ifnottex
72
73 @node Overview
74 @chapter Overview
75
76 The auth-source library is simply a way for Emacs and Gnus, among
77 others, to answer the old burning question ``What are my user name and
78 password?''
79
80 (This is different from the old question about burning ``Where is the
81 fire extinguisher, please?''.)
82
83 The auth-source library supports more than just the user name or the
84 password (known as the secret).
85
86 Similarly, the auth-source library supports multiple storage backend,
87 currently either the classic ``netrc'' backend, examples of which you
88 can see later in this document, or the Secret Service API@.  This is
89 done with EIEIO-based backends and you can write your own if you want.
90
91 @node Help for users
92 @chapter Help for users
93
94 ``Netrc'' files are a de facto standard.  They look like this:
95 @example
96 machine @var{mymachine} login @var{myloginname} password @var{mypassword} port @var{myport}
97 @end example
98
99 The @code{machine} is the server (either a DNS name or an IP address).
100 It's known as @var{:host} in @code{auth-source-search} queries.  You
101 can also use @code{host}.
102
103 The @code{port} is the connection port or protocol.  It's known as
104 @var{:port} in @code{auth-source-search} queries.
105
106 The @code{user} is the user name.  It's known as @var{:user} in
107 @code{auth-source-search} queries.  You can also use @code{login} and
108 @code{account}.
109
110 You can use spaces inside a password or other token by surrounding the
111 token with either single or double quotes.
112
113 You can use single quotes inside a password or other token by
114 surrounding it with double quotes, e.g. @code{"he'llo"}. Similarly you
115 can use double quotes inside a password or other token by surrounding
116 it with single quotes, e.g. @code{'he"llo'}. You can't mix both (so a
117 password or other token can't have both single and double quotes).
118
119 All this is optional. You could just say (but we don't recommend it,
120 we're just showing that it's possible)
121
122 @example
123 password @var{mypassword}
124 @end example
125
126 to use the same password everywhere.  Again, @emph{DO NOT DO THIS} or
127 you will be pwned as the kids say.
128
129 ``Netrc'' files are usually called @file{.authinfo} or @file{.netrc};
130 nowadays @file{.authinfo} seems to be more popular and the auth-source
131 library encourages this confusion by accepting both, as you'll see
132 later.
133
134 If you have problems with the search, set @code{auth-source-debug} to
135 @code{'trivia} and see what host, port, and user the library is
136 checking in the @file{*Messages*} buffer.  Ditto for any other
137 problems, your first step is always to see what's being checked.  The
138 second step, of course, is to write a blog entry about it and wait for
139 the answer in the comments.
140
141 You can customize the variable @code{auth-sources}.  The following may
142 be needed if you are using an older version of Emacs or if the
143 auth-source library is not loaded for some other reason.
144
145 @lisp
146 (require 'auth-source)             ;; probably not necessary
147 (customize-variable 'auth-sources) ;; optional, do it once
148 @end lisp
149
150 @defvar auth-sources
151
152 The @code{auth-sources} variable tells the auth-source library where
153 your netrc files or Secret Service API collection items live for a
154 particular host and protocol.  While you can get fancy, the default
155 and simplest configuration is:
156
157 @lisp
158 ;;; old default: required :host and :port, not needed anymore
159 (setq auth-sources '((:source "~/.authinfo.gpg" :host t :port t)))
160 ;;; mostly equivalent (see below about fallbacks) but shorter:
161 (setq auth-sources '((:source "~/.authinfo.gpg")))
162 ;;; even shorter and the @emph{default}:
163 (setq auth-sources '("~/.authinfo.gpg" "~/.authinfo" "~/.netrc"))
164 ;;; use the Secrets API @var{Login} collection
165 ;;; (@pxref{Secret Service API})
166 (setq auth-sources '("secrets:Login"))
167 @end lisp
168
169 By adding multiple entries to @code{auth-sources} with a particular
170 host or protocol, you can have specific netrc files for that host or
171 protocol.  Usually this is unnecessary but may make sense if you have
172 shared netrc files or some other unusual setup (90% of Emacs users
173 have unusual setups and the remaining 10% are @emph{really} unusual).
174
175 Here's a mixed example using two sources:
176
177 @lisp
178 (setq auth-sources '((:source (:secrets default)
179                       :host "myserver" :user "joe")
180                      "~/.authinfo.gpg"))
181 @end lisp
182
183 @end defvar
184
185 If you don't customize @code{auth-sources}, you'll have to live with
186 the defaults: the unencrypted netrc file @file{~/.authinfo} will be
187 used for any host and any port.
188
189 If that fails, any host and any port are looked up in the netrc file
190 @file{~/.authinfo.gpg}, which is a GnuPG encrypted file (@pxref{GnuPG
191 and EasyPG Assistant Configuration}).
192
193 Finally, the unencrypted netrc file @file{~/.netrc} will be used for
194 any host and any port.
195
196 The typical netrc line example is without a port.
197
198 @example
199 machine YOURMACHINE login YOU password YOURPASSWORD
200 @end example
201
202 This will match any authentication port.  Simple, right?  But what if
203 there's a SMTP server on port 433 of that machine that needs a
204 different password from the IMAP server?
205
206 @example
207 machine YOURMACHINE login YOU password SMTPPASSWORD port 433
208 machine YOURMACHINE login YOU password GENERALPASSWORD
209 @end example
210
211 For url-auth authentication (HTTP/HTTPS), you need to put this in your
212 netrc file:
213
214 @example
215 machine yourmachine.com:80 port http login testuser password testpass
216 @end example
217
218 This will match any realm and authentication method (basic or digest)
219 over HTTP@.  HTTPS is set up similarly.  If you want finer controls,
220 explore the url-auth source code and variables.
221
222 For Tramp authentication, use:
223
224 @example
225 machine yourmachine.com port scp login testuser password testpass
226 @end example
227
228 Note that the port denotes the Tramp connection method.  When you
229 don't use a port entry, you match any Tramp method, as explained
230 earlier.  Since Tramp has about 88 connection methods, this may be
231 necessary if you have an unusual (see earlier comment on those) setup.
232
233 @node Multiple GMail accounts with Gnus
234 @chapter Multiple GMail accounts with Gnus
235
236 For multiple GMail accounts with Gnus, you have to make two nnimap
237 entries in your @code{gnus-secondary-select-methods} with distinct
238 names:
239
240 @example
241 (setq gnus-secondary-select-methods '((nnimap "gmail"
242                                          (nnimap-address "imap.gmail.com"))
243                                       (nnimap "gmail2"
244                                          (nnimap-address "imap.gmail.com"))))
245 @end example
246
247 Your netrc entries will then be:
248
249 @example
250 machine gmail login account@gmail.com password "accountpassword" port imap
251 machine gmail2 login account2@gmail.com password "account2password" port imap
252 @end example
253
254 @node Secret Service API
255 @chapter Secret Service API
256
257 The @dfn{Secret Service API} is a standard from
258 @uref{http://www.freedesktop.org/wiki/Specifications/secret-storage-spec,,freedesktop.org}
259 to securely store passwords and other confidential information.  This
260 API is implemented by system daemons such as the GNOME Keyring and the
261 KDE Wallet (these are GNOME and KDE packages respectively and should
262 be available on most modern GNU/Linux systems).
263
264 The auth-source library uses the @file{secrets.el} library to connect
265 through the Secret Service API@.  You can also use that library in
266 other packages, it's not exclusive to auth-source.
267
268 @defvar secrets-enabled
269 After loading @file{secrets.el}, a non-@code{nil} value of this
270 variable indicates the existence of a daemon providing the Secret
271 Service API.
272 @end defvar
273
274 @deffn Command secrets-show-secrets
275 This command shows all collections, items, and their attributes.
276 @end deffn
277
278 The atomic objects managed by the Secret Service API are @dfn{secret
279 items}, which contain things an application wishes to store securely,
280 like a password.  Secret items have a label (a name), the @dfn{secret}
281 (which is the string we want, like a password), and a set of lookup
282 attributes.  The attributes can be used to search and retrieve a
283 secret item at a later date.
284
285 Secret items are grouped in @dfn{collections}.  A collection is
286 sometimes called a @samp{keyring} or @samp{wallet} in GNOME Keyring
287 and KDE Wallet but it's the same thing, a group of secrets.
288 Collections are personal and protected so only the owner can open them.
289
290 The most common collection is called @code{"login"}.
291
292 A collection can have an alias.  The alias @code{"default"} is
293 commonly used so the clients don't have to know the specific name of
294 the collection they open.  Other aliases are not supported yet.
295 Since aliases are globally accessible, set the @code{"default"} alias
296 only when you're sure it's appropriate.
297
298 @defun secrets-list-collections
299 This function returns all the collection names as a list.
300 @end defun
301
302 @defun secrets-set-alias collection alias
303 Set @var{alias} as alias of collection labeled @var{collection}.
304 Currently only the alias @code{"default"} is supported.
305 @end defun
306
307 @defun secrets-get-alias alias
308 Return the collection name @var{alias} is referencing to.
309 Currently only the alias @code{"default"} is supported.
310 @end defun
311
312 Collections can be created and deleted by the functions
313 @code{secrets-create-collection} and @code{secrets-delete-collection}.
314 Usually, this is not done from within Emacs.  Do not delete standard
315 collections such as @code{"login"}.
316
317 The special collection @code{"session"} exists for the lifetime of the
318 corresponding client session (in our case, Emacs's lifetime).  It is
319 created automatically when Emacs uses the Secret Service interface and
320 it is deleted when Emacs is killed.  Therefore, it can be used to
321 store and retrieve secret items temporarily.  The @code{"session"}
322 collection is better than a persistent collection when the secret
323 items should not live longer than Emacs.  The session collection can
324 be specified either by the string @code{"session"}, or by @code{nil},
325 whenever a collection parameter is needed in the following functions.
326
327 @defun secrets-list-items collection
328 Returns all the item labels of @var{collection} as a list.
329 @end defun
330
331 @defun secrets-create-item collection item password &rest attributes
332 This function creates a new item in @var{collection} with label
333 @var{item} and password @var{password}.  @var{attributes} are
334 key-value pairs set for the created item.  The keys are keyword
335 symbols, starting with a colon.  Example:
336
337 @example
338 ;;; The session "session", the label is "my item"
339 ;;; and the secret (password) is "geheim"
340 (secrets-create-item "session" "my item" "geheim"
341  :method "sudo" :user "joe" :host "remote-host")
342 @end example
343 @end defun
344
345 @defun secrets-get-secret collection item
346 Return the secret of item labeled @var{item} in @var{collection}.
347 If there is no such item, return @code{nil}.
348 @end defun
349
350 @defun secrets-delete-item collection item
351 This function deletes item @var{item} in @var{collection}.
352 @end defun
353
354 The lookup attributes, which are specified during creation of a
355 secret item, must be a key-value pair.  Keys are keyword symbols,
356 starting with a colon; values are strings.  They can be retrieved
357 from a given secret item and they can be used for searching of items.
358
359 @defun secrets-get-attribute collection item attribute
360 Returns the value of key @var{attribute} of item labeled @var{item} in
361 @var{collection}.  If there is no such item, or the item doesn't own
362 this key, the function returns @code{nil}.
363 @end defun
364
365 @defun secrets-get-attributes collection item
366 Return the lookup attributes of item labeled @var{item} in
367 @var{collection}.  If there is no such item, or the item has no
368 attributes, it returns @code{nil}.  Example:
369
370 @example
371 (secrets-get-attributes "session" "my item")
372      @result{} ((:user . "joe") (:host ."remote-host"))
373 @end example
374 @end defun
375
376 @defun secrets-search-items collection &rest attributes
377 Search for the items in @var{collection} with matching
378 @var{attributes}.  The @var{attributes} are key-value pairs, as used
379 in @code{secrets-create-item}.  Example:
380
381 @example
382 (secrets-search-items "session" :user "joe")
383      @result{} ("my item" "another item")
384 @end example
385 @end defun
386
387 The auth-source library uses the @file{secrets.el} library and thus
388 the Secret Service API when you specify a source matching
389 @code{"secrets:COLLECTION"}.  For instance, you could use
390 @code{"secrets:session"} to use the @code{"session"} collection, open only
391 for the lifetime of Emacs.  Or you could use @code{"secrets:Login"} to
392 open the @code{"Login"} collection.  As a special case, you can use the
393 symbol @code{default} in @code{auth-sources} (not a string, but a
394 symbol) to specify the @code{"default"} alias.  Here is a contrived
395 example that sets @code{auth-sources} to search three collections and
396 then fall back to @file{~/.authinfo.gpg}.
397
398 @example
399 (setq auth-sources '(default
400                      "secrets:session"
401                      "secrets:Login"
402                      "~/.authinfo.gpg"))
403 @end example
404
405 @node Help for developers
406 @chapter Help for developers
407
408 The auth-source library lets you control logging output easily.
409
410 @defvar auth-source-debug
411 Set this variable to @code{'trivia} to see lots of output in
412 @file{*Messages*}, or set it to a function that behaves like
413 @code{message} to do your own logging.
414 @end defvar
415
416 The auth-source library only has a few functions for external use.
417
418 @defun auth-source-search &rest spec &key type max host user port secret require create delete &allow-other-keys
419 This function searches (or modifies) authentication backends according
420 to @var{spec}.  See the function's doc-string for details.
421 @c TODO more details.
422 @end defun
423
424 Let's take a look at an example of using @code{auth-source-search}
425 from Gnus's @code{nnimap.el}.
426
427 @example
428 (defun nnimap-credentials (address ports)
429   (let* ((auth-source-creation-prompts
430           '((user  . "IMAP user at %h: ")
431             (secret . "IMAP password for %u@@%h: ")))
432          (found (nth 0 (auth-source-search :max 1
433                                            :host address
434                                            :port ports
435                                            :require '(:user :secret)
436                                            :create t))))
437     (if found
438         (list (plist-get found :user)
439               (let ((secret (plist-get found :secret)))
440                 (if (functionp secret)
441                     (funcall secret)
442                   secret))
443               (plist-get found :save-function))
444       nil)))
445 @end example
446
447 This call requires the user and password (secret) to be in the
448 results.  It also requests that an entry be created if it doesn't
449 exist already.  While the created entry is being assembled, the shown
450 prompts will be used to interact with the user.  The caller can also
451 pass data in @code{auth-source-creation-defaults} to supply defaults
452 for any of the prompts.
453
454 Note that the password needs to be evaluated if it's a function.  It's
455 wrapped in a function to provide some security.
456
457 Later, after a successful login, @code{nnimap.el} calls the
458 @code{:save-function} like so:
459
460 @example
461 (when (functionp (nth 2 credentials))
462    (funcall (nth 2 credentials)))
463 @end example
464
465 This will work whether the @code{:save-function} was provided or not.
466 @code{:save-function} will be provided only when a new entry was
467 created, so this effectively says ``after a successful login, save the
468 authentication information we just used, if it was newly created.''
469
470 After the first time it's called, the @code{:save-function} will not
471 run again (but it will log something if you have set
472 @code{auth-source-debug} to @code{'trivia}).  This is so it won't ask
473 the same question again, which is annoying.  This is so it won't ask
474 the same question again, which is annoying.  This is so it won't ask
475 the same question again, which is annoying.
476
477 So the responsibility of the API user that specified @code{:create t}
478 is to call the @code{:save-function} if it's provided.
479
480 @defun auth-source-delete &rest spec &key delete &allow-other-keys
481 This function deletes entries matching @var{spec} from the
482 authentication backends.  It returns the entries that were deleted.
483 The backend may not actually delete the entries.
484 @end defun
485
486 @defun auth-source-forget spec
487 This function forgets any cached data that exactly matches @var{spec}.
488 It returns @code{t} if it forget some data, and @code{nil} if no
489 matching data was found.
490 @end defun
491
492 @defun auth-source-forget+ &rest spec &allow-other-keys
493 This function forgets any cached data matching @var{spec}.
494 It returns the number of items forgotten.
495 @end defun
496
497 @node GnuPG and EasyPG Assistant Configuration
498 @appendix GnuPG and EasyPG Assistant Configuration
499
500 If the @code{auth-sources} variable contains @file{~/.authinfo.gpg}
501 before @file{~/.authinfo}, the auth-source library will try to
502 read the GnuPG encrypted @file{.gpg} file first, before
503 the unencrypted file.
504
505 In Emacs 23 or later there is an option @code{auto-encryption-mode} to
506 automatically decrypt @file{*.gpg} files.  It is enabled by default.
507 If you are using earlier versions of Emacs, you will need:
508
509 @lisp
510 (require 'epa-file)
511 (epa-file-enable)
512 @end lisp
513
514 If you want your GnuPG passwords to be cached, set up @code{gpg-agent}
515 or EasyPG Assistant
516 (@pxref{Caching Passphrases, , Caching Passphrases, epa}).
517
518 To quick start, here are some questions:
519
520 @enumerate
521 @item
522 Do you use GnuPG version 2 instead of GnuPG version 1?
523 @item
524 Do you use symmetric encryption rather than public key encryption?
525 @item
526 Do you want to use gpg-agent?
527 @end enumerate
528
529 Here are configurations depending on your answers:
530
531 @multitable {111} {222} {333} {configuration configuration configuration}
532 @item @b{1} @tab @b{2} @tab @b{3} @tab Configuration
533 @item Yes @tab Yes @tab Yes @tab Set up gpg-agent.
534 @item Yes @tab Yes @tab No @tab You can't, without gpg-agent.
535 @item Yes @tab No @tab Yes @tab Set up gpg-agent.
536 @item Yes @tab No @tab No @tab You can't, without gpg-agent.
537 @item No @tab Yes @tab Yes @tab Set up elisp passphrase cache.
538 @item No @tab Yes @tab No @tab Set up elisp passphrase cache.
539 @item No @tab No @tab Yes @tab Set up gpg-agent.
540 @item No @tab No @tab No @tab You can't, without gpg-agent.
541 @end multitable
542
543 To set up gpg-agent, follow the instruction in GnuPG manual
544 (@pxref{Invoking GPG-AGENT, , Invoking GPG-AGENT, gnupg}).
545
546 To set up elisp passphrase cache, set
547 @code{epa-file-cache-passphrase-for-symmetric-encryption}.
548
549 @node GNU Free Documentation License
550 @appendix GNU Free Documentation License
551 @include doclicense.texi
552
553 @node Index
554 @unnumbered Index
555 @printindex cp
556
557 @node Function Index
558 @unnumbered Function Index
559 @printindex fn
560
561 @node Variable Index
562 @unnumbered Variable Index
563 @printindex vr
564
565 @bye
566
567 @c End: