annotate doc/misc/auth.texi @ 105182:e77a0b956835

* frame.c (xrdb_get_resource): Return nil for empty string resources; some parts of Emacs code (like font selection) don't grok them. See http://lists.gnu.org/archive/html/emacs-devel/2009-09/msg00528.html
author Juanma Barranquero <lekktu@gmail.com>
date Thu, 24 Sep 2009 16:59:14 +0000
parents 2c607b344f3b
children 1d1d5d9bd884
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
102054
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
1 \input texinfo @c -*-texinfo-*-
102371
0e907e93a720 Fix @setfilename.
Glenn Morris <rgm@gnu.org>
parents: 102059
diff changeset
2 @setfilename ../../info/auth
102059
9bcea07061a8 consistently use @insertcopying, @direntry, @contents
Karl Berry <karl@gnu.org>
parents: 102054
diff changeset
3 @settitle Emacs auth-source Library @value{VERSION}
102054
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
4
104692
b99b3dda298b Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents: 102820
diff changeset
5 @set VERSION 0.2
102054
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
6
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
7 @copying
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
8 This file describes the Emacs auth-source library.
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
9
102059
9bcea07061a8 consistently use @insertcopying, @direntry, @contents
Karl Berry <karl@gnu.org>
parents: 102054
diff changeset
10 Copyright @copyright{} 2008, 2009 Free Software Foundation, Inc.
102054
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
11
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
12 @quotation
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
13 Permission is granted to copy, distribute and/or modify this document
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
14 under the terms of the GNU Free Documentation License, Version 1.3 or
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
15 any later version published by the Free Software Foundation; with no
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
16 Invariant Sections, with the Front-Cover texts being ``A GNU Manual,''
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
17 and with the Back-Cover Texts as in (a) below. A copy of the license
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
18 is included in the section entitled ``GNU Free Documentation License''
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
19 in the Emacs manual.
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
20
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
21 (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
22 modify this GNU manual. Buying copies from the FSF supports it in
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
23 developing GNU and promoting software freedom.''
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
24
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
25 This document is part of a collection distributed under the GNU Free
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
26 Documentation License. If you want to distribute this document
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
27 separately from the collection, you can do so by adding a copy of the
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
28 license to the document, as described in section 6 of the license.
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
29 @end quotation
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
30 @end copying
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
31
102059
9bcea07061a8 consistently use @insertcopying, @direntry, @contents
Karl Berry <karl@gnu.org>
parents: 102054
diff changeset
32 @dircategory Emacs
9bcea07061a8 consistently use @insertcopying, @direntry, @contents
Karl Berry <karl@gnu.org>
parents: 102054
diff changeset
33 @direntry
102820
3e7c6b40afdd Capitalize direntry.
Glenn Morris <rgm@gnu.org>
parents: 102371
diff changeset
34 * Auth-source: (auth). The Emacs auth-source library.
102059
9bcea07061a8 consistently use @insertcopying, @direntry, @contents
Karl Berry <karl@gnu.org>
parents: 102054
diff changeset
35 @end direntry
102054
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
36
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
37 @titlepage
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
38 @title Emacs auth-source Library
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
39 @author by Ted Zlatanov
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
40 @page
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
41 @vskip 0pt plus 1filll
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
42 @insertcopying
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
43 @end titlepage
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
44
102059
9bcea07061a8 consistently use @insertcopying, @direntry, @contents
Karl Berry <karl@gnu.org>
parents: 102054
diff changeset
45 @contents
102054
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
46
102059
9bcea07061a8 consistently use @insertcopying, @direntry, @contents
Karl Berry <karl@gnu.org>
parents: 102054
diff changeset
47 @ifnottex
102054
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
48 @node Top
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
49 @top Emacs auth-source
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
50 This manual describes the Emacs auth-source library.
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
51
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
52 It is a way for multiple applications to share a single configuration
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
53 (in Emacs and in files) for user convenience.
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
54
102059
9bcea07061a8 consistently use @insertcopying, @direntry, @contents
Karl Berry <karl@gnu.org>
parents: 102054
diff changeset
55 @insertcopying
9bcea07061a8 consistently use @insertcopying, @direntry, @contents
Karl Berry <karl@gnu.org>
parents: 102054
diff changeset
56
102054
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
57 @menu
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
58 * Overview:: Overview of the auth-source library.
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
59 * Help for users::
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
60 * Help for developers::
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
61 * Index::
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
62 * Function Index::
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
63 * Variable Index::
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
64 @end menu
102059
9bcea07061a8 consistently use @insertcopying, @direntry, @contents
Karl Berry <karl@gnu.org>
parents: 102054
diff changeset
65 @end ifnottex
102054
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
66
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
67 @node Overview
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
68 @chapter Overview
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
69
104891
2c607b344f3b 2009-09-02 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents: 104692
diff changeset
70 The auth-source library is simply a way for Emacs and Gnus, among
2c607b344f3b 2009-09-02 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents: 104692
diff changeset
71 others, to find the answer to the old burning question ``I have a
2c607b344f3b 2009-09-02 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents: 104692
diff changeset
72 server name and a port, what are my user name and password?''
104692
b99b3dda298b Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents: 102820
diff changeset
73
b99b3dda298b Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents: 102820
diff changeset
74 The auth-source library actually supports more than just the user name
b99b3dda298b Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents: 102820
diff changeset
75 (known as the login) or the password, but only those two are in use
b99b3dda298b Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents: 102820
diff changeset
76 today in Emacs or Gnus. Similarly, the auth-source library can in
b99b3dda298b Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents: 102820
diff changeset
77 theory support multiple storage formats, but currently it only
b99b3dda298b Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents: 102820
diff changeset
78 understands the classic ``netrc'' format, examples of which you can
b99b3dda298b Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents: 102820
diff changeset
79 see later in this document.
102054
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
80
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
81 @node Help for users
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
82 @chapter Help for users
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
83
104692
b99b3dda298b Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents: 102820
diff changeset
84 ``Netrc'' files are a de facto standard. They look like this:
b99b3dda298b Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents: 102820
diff changeset
85 @example
104891
2c607b344f3b 2009-09-02 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents: 104692
diff changeset
86 machine @var{mymachine} login @var{myloginname} password @var{mypassword} port @var{myport}
104692
b99b3dda298b Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents: 102820
diff changeset
87 @end example
102054
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
88
104891
2c607b344f3b 2009-09-02 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents: 104692
diff changeset
89 The machine is the server (either a DNS name or an IP address).
2c607b344f3b 2009-09-02 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents: 104692
diff changeset
90
104692
b99b3dda298b Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents: 102820
diff changeset
91 The port is optional. If it's missing, auth-source will assume any
b99b3dda298b Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents: 102820
diff changeset
92 port is OK. Actually the port is a protocol name or a port number so
104891
2c607b344f3b 2009-09-02 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents: 104692
diff changeset
93 you can have separate entries for port @var{143} and for protocol
2c607b344f3b 2009-09-02 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents: 104692
diff changeset
94 @var{imap} if you fancy that. Anyway, you can just omit the port if
2c607b344f3b 2009-09-02 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents: 104692
diff changeset
95 you don't need it.
2c607b344f3b 2009-09-02 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents: 104692
diff changeset
96
2c607b344f3b 2009-09-02 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents: 104692
diff changeset
97 The login and password are simply your login credentials to the server.
104692
b99b3dda298b Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents: 102820
diff changeset
98
104891
2c607b344f3b 2009-09-02 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents: 104692
diff changeset
99 ``Netrc'' files are usually called @code{.authinfo} or @code{.netrc};
2c607b344f3b 2009-09-02 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents: 104692
diff changeset
100 nowadays @code{.authinfo} seems to be more popular and the auth-source
2c607b344f3b 2009-09-02 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents: 104692
diff changeset
101 library encourages this confusion by making it the default, as you'll
2c607b344f3b 2009-09-02 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents: 104692
diff changeset
102 see later.
104692
b99b3dda298b Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents: 102820
diff changeset
103
104891
2c607b344f3b 2009-09-02 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents: 104692
diff changeset
104 If you have problems with the port, set @code{auth-source-debug} to
2c607b344f3b 2009-09-02 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents: 104692
diff changeset
105 @code{t} and see what port the library is checking in the
2c607b344f3b 2009-09-02 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents: 104692
diff changeset
106 @code{*Messages*} buffer. Ditto for any other problems, your first
2c607b344f3b 2009-09-02 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents: 104692
diff changeset
107 step is always to see what's being checked. The second step, of
2c607b344f3b 2009-09-02 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents: 104692
diff changeset
108 course, is to write a blog entry about it and wait for the answer in
2c607b344f3b 2009-09-02 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents: 104692
diff changeset
109 the comments.
2c607b344f3b 2009-09-02 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents: 104692
diff changeset
110
2c607b344f3b 2009-09-02 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents: 104692
diff changeset
111 You can customize the variable @code{auth-sources}. The following may
104692
b99b3dda298b Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents: 102820
diff changeset
112 be needed if you are using an older version of Emacs or if the
b99b3dda298b Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents: 102820
diff changeset
113 auth-source library is not loaded for some other reason.
102054
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
114
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
115 @lisp
104692
b99b3dda298b Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents: 102820
diff changeset
116 (require 'auth-source) ;; probably not necessary
102054
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
117 (customize-variable 'auth-sources) ;; optional, do it once
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
118 @end lisp
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
119
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
120 @defvar auth-sources
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
121
104891
2c607b344f3b 2009-09-02 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents: 104692
diff changeset
122 The @code{auth-sources} variable tells the auth-source library where
102054
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
123 your netrc files live for a particular host and protocol. While you
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
124 can get fancy, the default and simplest configuration is:
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
125
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
126 @lisp
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
127 (setq auth-sources '((:source "~/.authinfo.gpg" :host t :protocol t)))
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
128 @end lisp
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
129
104692
b99b3dda298b Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents: 102820
diff changeset
130 This says ``for any host and any protocol, use just that one file.''
b99b3dda298b Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents: 102820
diff changeset
131 Sweet simplicity. In fact, this is already the default, so unless you
b99b3dda298b Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents: 102820
diff changeset
132 want to move your netrc file, it will just work if you have that
b99b3dda298b Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents: 102820
diff changeset
133 file. You may not, though, so make sure it exists.
b99b3dda298b Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents: 102820
diff changeset
134
104891
2c607b344f3b 2009-09-02 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents: 104692
diff changeset
135 By adding multiple entries to @code{auth-sources} with a particular
104692
b99b3dda298b Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents: 102820
diff changeset
136 host or protocol, you can have specific netrc files for that host or
b99b3dda298b Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents: 102820
diff changeset
137 protocol. Usually this is unnecessary but may make sense if you have
b99b3dda298b Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents: 102820
diff changeset
138 shared netrc files or some other unusual setup (90% of Emacs users
b99b3dda298b Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents: 102820
diff changeset
139 have unusual setups and the remaining 10% are @emph{really} unusual).
102054
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
140
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
141 @end defvar
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
142
104891
2c607b344f3b 2009-09-02 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents: 104692
diff changeset
143 If you don't customize @code{auth-sources}, you'll have to live with
102054
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
144 the defaults: any host and any port are looked up in the netrc
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
145 file @code{~/.authinfo.gpg}. This is an encrypted file if and only if
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
146 you set up EPA, which is strongly recommended.
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
147
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
148 @lisp
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
149 (require 'epa-file)
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
150 (epa-file-enable)
104692
b99b3dda298b Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents: 102820
diff changeset
151 ;;; VERY important if you want symmetric encryption
b99b3dda298b Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents: 102820
diff changeset
152 ;;; irrelevant if you don't
b99b3dda298b Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents: 102820
diff changeset
153 (setq epa-file-cache-passphrase-for-symmetric-encryption t)
102054
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
154 @end lisp
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
155
104692
b99b3dda298b Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents: 102820
diff changeset
156 The simplest working netrc line example is one without a port.
b99b3dda298b Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents: 102820
diff changeset
157
b99b3dda298b Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents: 102820
diff changeset
158 @example
b99b3dda298b Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents: 102820
diff changeset
159 machine YOURMACHINE login YOU password YOURPASSWORD
b99b3dda298b Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents: 102820
diff changeset
160 @end example
b99b3dda298b Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents: 102820
diff changeset
161
b99b3dda298b Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents: 102820
diff changeset
162 This will match any authentication port. Simple, right? But what if
b99b3dda298b Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents: 102820
diff changeset
163 there's a SMTP server on port 433 of that machine that needs a
b99b3dda298b Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents: 102820
diff changeset
164 different password from the IMAP server?
b99b3dda298b Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents: 102820
diff changeset
165
b99b3dda298b Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents: 102820
diff changeset
166 @example
b99b3dda298b Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents: 102820
diff changeset
167 machine YOURMACHINE login YOU password SMTPPASSWORD port 433
b99b3dda298b Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents: 102820
diff changeset
168 machine YOURMACHINE login YOU password GENERALPASSWORD
b99b3dda298b Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents: 102820
diff changeset
169 @end example
b99b3dda298b Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents: 102820
diff changeset
170
102054
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
171 For url-auth authentication (HTTP/HTTPS), you need to put this in your
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
172 netrc file:
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
173
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
174 @example
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
175 machine yourmachine.com:80 port http login testuser password testpass
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
176 @end example
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
177
104692
b99b3dda298b Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents: 102820
diff changeset
178 This will match any realm and authentication method (basic or digest)
b99b3dda298b Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents: 102820
diff changeset
179 over HTTP. HTTPS is set up similarly. If you want finer controls,
b99b3dda298b Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents: 102820
diff changeset
180 explore the url-auth source code and variables.
102054
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
181
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
182 For Tramp authentication, use:
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
183
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
184 @example
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
185 machine yourmachine.com port scp login testuser password testpass
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
186 @end example
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
187
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
188 Note that the port denotes the Tramp connection method. When you
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
189 don't use a port entry, you match any Tramp method, as explained
104692
b99b3dda298b Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents: 102820
diff changeset
190 earlier. Since Tramp has about 88 connection methods, this may be
b99b3dda298b Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents: 102820
diff changeset
191 necessary if you have an unusual (see earlier comment on those) setup.
102054
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
192
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
193 @node Help for developers
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
194 @chapter Help for developers
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
195
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
196 The auth-source library only has one function for external use.
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
197
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
198 @defun auth-source-user-or-password mode host port
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
199
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
200 Retrieve appropriate authentication tokens, determined by @var{mode},
104891
2c607b344f3b 2009-09-02 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents: 104692
diff changeset
201 for host @var{host} and @var{port}. If @code{auth-source-debug} is t,
2c607b344f3b 2009-09-02 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents: 104692
diff changeset
202 debugging messages will be printed. Set @code{auth-source-debug} to a
104692
b99b3dda298b Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents: 102820
diff changeset
203 function to use that function for logging. The parameters passed will
b99b3dda298b Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents: 102820
diff changeset
204 be the same that the @code{message} function takes, that is, a string
b99b3dda298b Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents: 102820
diff changeset
205 formatting spec and optional parameters.
102054
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
206
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
207 If @var{mode} is a list of strings, the function will return a list of
104692
b99b3dda298b Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents: 102820
diff changeset
208 strings or @code{nil} objects (thus you can avoid parsing the netrc
b99b3dda298b Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents: 102820
diff changeset
209 file more than once). If it's a string, the function will return a
b99b3dda298b Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents: 102820
diff changeset
210 string or a @code{nil} object. Currently only the modes ``login'' and
b99b3dda298b Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents: 102820
diff changeset
211 ``password'' are recognized but more may be added in the future.
102054
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
212
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
213 @var{host} is a string containing the host name.
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
214
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
215 @var{port} contains the protocol name (e.g. ``imap'') or
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
216 a port number. It must be a string, corresponding to the port in the
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
217 users' netrc files.
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
218
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
219 @example
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
220 ;; IMAP example
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
221 (setq auth (auth-source-user-or-password
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
222 '("login" "password")
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
223 "anyhostnamehere"
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
224 "imap"))
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
225 (nth 0 auth) ; the login name
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
226 (nth 1 auth) ; the password
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
227 @end example
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
228
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
229 @end defun
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
230
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
231 @node Index
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
232 @chapter Index
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
233 @printindex cp
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
234
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
235 @node Function Index
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
236 @chapter Function Index
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
237 @printindex fn
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
238
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
239 @node Variable Index
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
240 @chapter Variable Index
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
241 @printindex vr
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
242
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
243 @bye
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
244
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
245 @c End:
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
246
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
247 @ignore
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
248 arch-tag: 7b835fd3-473f-40fc-9776-1c4e49d26c94
c35aac5fa64e Merge from gnus--devo--0
Miles Bader <miles@gnu.org>
parents:
diff changeset
249 @end ignore