Mercurial > emacs
annotate doc/misc/auth.texi @ 107712:6a80fb868018
Change name of default value of calc-settings-file to ~/.emacs.d/calc.el throughout.
author | Jay Belanger <jay.p.belanger@gmail.com> |
---|---|
date | Tue, 30 Mar 2010 22:47:52 -0500 |
parents | be11042041cb |
children | 60516122d066 |
rev | line source |
---|---|
102054 | 1 \input texinfo @c -*-texinfo-*- |
102371 | 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 | 4 |
104692 | 5 @set VERSION 0.2 |
102054 | 6 |
7 @copying | |
8 This file describes the Emacs auth-source library. | |
9 | |
106815 | 10 Copyright @copyright{} 2008, 2009, 2010 Free Software Foundation, Inc. |
102054 | 11 |
12 @quotation | |
13 Permission is granted to copy, distribute and/or modify this document | |
14 under the terms of the GNU Free Documentation License, Version 1.3 or | |
15 any later version published by the Free Software Foundation; with no | |
16 Invariant Sections, with the Front-Cover texts being ``A GNU Manual,'' | |
17 and with the Back-Cover Texts as in (a) below. A copy of the license | |
18 is included in the section entitled ``GNU Free Documentation License'' | |
19 in the Emacs manual. | |
20 | |
21 (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and | |
22 modify this GNU manual. Buying copies from the FSF supports it in | |
23 developing GNU and promoting software freedom.'' | |
24 | |
25 This document is part of a collection distributed under the GNU Free | |
26 Documentation License. If you want to distribute this document | |
27 separately from the collection, you can do so by adding a copy of the | |
28 license to the document, as described in section 6 of the license. | |
29 @end quotation | |
30 @end copying | |
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 | 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 | 36 |
37 @titlepage | |
38 @title Emacs auth-source Library | |
39 @author by Ted Zlatanov | |
40 @page | |
41 @vskip 0pt plus 1filll | |
42 @insertcopying | |
43 @end titlepage | |
44 | |
102059
9bcea07061a8
consistently use @insertcopying, @direntry, @contents
Karl Berry <karl@gnu.org>
parents:
102054
diff
changeset
|
45 @contents |
102054 | 46 |
102059
9bcea07061a8
consistently use @insertcopying, @direntry, @contents
Karl Berry <karl@gnu.org>
parents:
102054
diff
changeset
|
47 @ifnottex |
102054 | 48 @node Top |
49 @top Emacs auth-source | |
50 This manual describes the Emacs auth-source library. | |
51 | |
52 It is a way for multiple applications to share a single configuration | |
53 (in Emacs and in files) for user convenience. | |
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 | 57 @menu |
58 * Overview:: Overview of the auth-source library. | |
59 * Help for users:: | |
107564
be11042041cb
2010-03-27 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
106815
diff
changeset
|
60 * Secret Service API:: |
102054 | 61 * Help for developers:: |
62 * Index:: | |
63 * Function Index:: | |
64 * Variable Index:: | |
65 @end menu | |
102059
9bcea07061a8
consistently use @insertcopying, @direntry, @contents
Karl Berry <karl@gnu.org>
parents:
102054
diff
changeset
|
66 @end ifnottex |
102054 | 67 |
68 @node Overview | |
69 @chapter Overview | |
70 | |
104891
2c607b344f3b
2009-09-02 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
104692
diff
changeset
|
71 The auth-source library is simply a way for Emacs and Gnus, among |
107564
be11042041cb
2010-03-27 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
106815
diff
changeset
|
72 others, to answer the old burning question ``I have a server name and |
be11042041cb
2010-03-27 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
106815
diff
changeset
|
73 a port, what are my user name and password?'' |
104692 | 74 |
75 The auth-source library actually supports more than just the user name | |
76 (known as the login) or the password, but only those two are in use | |
107564
be11042041cb
2010-03-27 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
106815
diff
changeset
|
77 today in Emacs or Gnus. Similarly, the auth-source library supports |
be11042041cb
2010-03-27 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
106815
diff
changeset
|
78 multiple storage formats, currently either the classic ``netrc'' |
be11042041cb
2010-03-27 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
106815
diff
changeset
|
79 format, examples of which you can see later in this document, or the |
be11042041cb
2010-03-27 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
106815
diff
changeset
|
80 Secret Service API. |
102054 | 81 |
82 @node Help for users | |
83 @chapter Help for users | |
84 | |
104692 | 85 ``Netrc'' files are a de facto standard. They look like this: |
86 @example | |
104891
2c607b344f3b
2009-09-02 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
104692
diff
changeset
|
87 machine @var{mymachine} login @var{myloginname} password @var{mypassword} port @var{myport} |
104692 | 88 @end example |
102054 | 89 |
104891
2c607b344f3b
2009-09-02 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
104692
diff
changeset
|
90 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
|
91 |
104692 | 92 The port is optional. If it's missing, auth-source will assume any |
93 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
|
94 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
|
95 @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
|
96 you don't need it. |
2c607b344f3b
2009-09-02 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
104692
diff
changeset
|
97 |
2c607b344f3b
2009-09-02 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
104692
diff
changeset
|
98 The login and password are simply your login credentials to the server. |
104692 | 99 |
104891
2c607b344f3b
2009-09-02 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
104692
diff
changeset
|
100 ``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
|
101 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
|
102 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
|
103 see later. |
104692 | 104 |
104891
2c607b344f3b
2009-09-02 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
104692
diff
changeset
|
105 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
|
106 @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
|
107 @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
|
108 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
|
109 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
|
110 the comments. |
2c607b344f3b
2009-09-02 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
104692
diff
changeset
|
111 |
2c607b344f3b
2009-09-02 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
104692
diff
changeset
|
112 You can customize the variable @code{auth-sources}. The following may |
104692 | 113 be needed if you are using an older version of Emacs or if the |
114 auth-source library is not loaded for some other reason. | |
102054 | 115 |
116 @lisp | |
104692 | 117 (require 'auth-source) ;; probably not necessary |
102054 | 118 (customize-variable 'auth-sources) ;; optional, do it once |
119 @end lisp | |
120 | |
121 @defvar auth-sources | |
122 | |
104891
2c607b344f3b
2009-09-02 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
104692
diff
changeset
|
123 The @code{auth-sources} variable tells the auth-source library where |
107564
be11042041cb
2010-03-27 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
106815
diff
changeset
|
124 your netrc files or Secret Service API collection items live for a |
be11042041cb
2010-03-27 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
106815
diff
changeset
|
125 particular host and protocol. While you can get fancy, the default |
be11042041cb
2010-03-27 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
106815
diff
changeset
|
126 and simplest configuration is: |
102054 | 127 |
128 @lisp | |
107564
be11042041cb
2010-03-27 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
106815
diff
changeset
|
129 ;;; old default: required :host and :protocol, not needed anymore |
102054 | 130 (setq auth-sources '((:source "~/.authinfo.gpg" :host t :protocol t))) |
107564
be11042041cb
2010-03-27 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
106815
diff
changeset
|
131 ;;; mostly equivalent (see below about fallbacks) but shorter: |
be11042041cb
2010-03-27 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
106815
diff
changeset
|
132 (setq auth-sources '((:source "~/.authinfo.gpg"))) |
102054 | 133 @end lisp |
134 | |
104692 | 135 This says ``for any host and any protocol, use just that one file.'' |
107564
be11042041cb
2010-03-27 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
106815
diff
changeset
|
136 Sweet simplicity. In fact, the latter is already the default, so |
be11042041cb
2010-03-27 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
106815
diff
changeset
|
137 unless you want to move your netrc file, it will just work if you have |
be11042041cb
2010-03-27 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
106815
diff
changeset
|
138 that file. Make sure it exists. |
104692 | 139 |
104891
2c607b344f3b
2009-09-02 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
104692
diff
changeset
|
140 By adding multiple entries to @code{auth-sources} with a particular |
104692 | 141 host or protocol, you can have specific netrc files for that host or |
142 protocol. Usually this is unnecessary but may make sense if you have | |
143 shared netrc files or some other unusual setup (90% of Emacs users | |
144 have unusual setups and the remaining 10% are @emph{really} unusual). | |
102054 | 145 |
107564
be11042041cb
2010-03-27 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
106815
diff
changeset
|
146 Here's an example that uses the Secret Service API for all lookups, |
be11042041cb
2010-03-27 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
106815
diff
changeset
|
147 using the default collection: |
be11042041cb
2010-03-27 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
106815
diff
changeset
|
148 |
be11042041cb
2010-03-27 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
106815
diff
changeset
|
149 @lisp |
be11042041cb
2010-03-27 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
106815
diff
changeset
|
150 (setq auth-sources '((:source (:secrets default)))) |
be11042041cb
2010-03-27 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
106815
diff
changeset
|
151 @end lisp |
be11042041cb
2010-03-27 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
106815
diff
changeset
|
152 |
be11042041cb
2010-03-27 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
106815
diff
changeset
|
153 And here's a mixed example, using two sources: |
be11042041cb
2010-03-27 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
106815
diff
changeset
|
154 |
be11042041cb
2010-03-27 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
106815
diff
changeset
|
155 @lisp |
be11042041cb
2010-03-27 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
106815
diff
changeset
|
156 (setq auth-sources '((:source (:secrets default) :host "myserver" :user "joe") |
be11042041cb
2010-03-27 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
106815
diff
changeset
|
157 (:source "~/.authinfo.gpg"))) |
be11042041cb
2010-03-27 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
106815
diff
changeset
|
158 @end lisp |
be11042041cb
2010-03-27 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
106815
diff
changeset
|
159 |
be11042041cb
2010-03-27 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
106815
diff
changeset
|
160 The best match is determined by order (starts from the bottom) only |
be11042041cb
2010-03-27 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
106815
diff
changeset
|
161 for the first pass, where things are checked exactly. In the example |
be11042041cb
2010-03-27 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
106815
diff
changeset
|
162 above, the first pass would find a single match for host |
be11042041cb
2010-03-27 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
106815
diff
changeset
|
163 @code{myserver}. The netrc choice would fail because it matches any |
be11042041cb
2010-03-27 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
106815
diff
changeset
|
164 host and protocol implicitly (as a @emph{fallback}). A specified |
be11042041cb
2010-03-27 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
106815
diff
changeset
|
165 value of @code{:host t} in @code{auth-sources} is considered a match |
be11042041cb
2010-03-27 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
106815
diff
changeset
|
166 on the first pass, unlike a missing @code{:host}. |
be11042041cb
2010-03-27 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
106815
diff
changeset
|
167 |
be11042041cb
2010-03-27 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
106815
diff
changeset
|
168 Now if you look for host @code{missing}, it won't match either source |
be11042041cb
2010-03-27 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
106815
diff
changeset
|
169 explicitly. The second pass (the @emph{fallback} pass) will look at |
be11042041cb
2010-03-27 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
106815
diff
changeset
|
170 all the implicit matches and collect them. They will be scored and |
be11042041cb
2010-03-27 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
106815
diff
changeset
|
171 returned sorted by score. The score is based on the number of |
be11042041cb
2010-03-27 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
106815
diff
changeset
|
172 explicit parameters that matched. See the @code{auth-pick} function |
be11042041cb
2010-03-27 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
106815
diff
changeset
|
173 for details. |
be11042041cb
2010-03-27 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
106815
diff
changeset
|
174 |
102054 | 175 @end defvar |
176 | |
104891
2c607b344f3b
2009-09-02 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
104692
diff
changeset
|
177 If you don't customize @code{auth-sources}, you'll have to live with |
102054 | 178 the defaults: any host and any port are looked up in the netrc |
179 file @code{~/.authinfo.gpg}. This is an encrypted file if and only if | |
180 you set up EPA, which is strongly recommended. | |
181 | |
182 @lisp | |
183 (require 'epa-file) | |
184 (epa-file-enable) | |
104692 | 185 ;;; VERY important if you want symmetric encryption |
186 ;;; irrelevant if you don't | |
187 (setq epa-file-cache-passphrase-for-symmetric-encryption t) | |
102054 | 188 @end lisp |
189 | |
104692 | 190 The simplest working netrc line example is one without a port. |
191 | |
192 @example | |
193 machine YOURMACHINE login YOU password YOURPASSWORD | |
194 @end example | |
195 | |
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? | |
199 | |
200 @example | |
201 machine YOURMACHINE login YOU password SMTPPASSWORD port 433 | |
202 machine YOURMACHINE login YOU password GENERALPASSWORD | |
203 @end example | |
204 | |
102054 | 205 For url-auth authentication (HTTP/HTTPS), you need to put this in your |
206 netrc file: | |
207 | |
208 @example | |
209 machine yourmachine.com:80 port http login testuser password testpass | |
210 @end example | |
211 | |
104692 | 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. | |
102054 | 215 |
216 For Tramp authentication, use: | |
217 | |
218 @example | |
219 machine yourmachine.com port scp login testuser password testpass | |
220 @end example | |
221 | |
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 | |
104692 | 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. | |
102054 | 226 |
107564
be11042041cb
2010-03-27 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
106815
diff
changeset
|
227 @node Secret Service API |
be11042041cb
2010-03-27 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
106815
diff
changeset
|
228 @chapter Secret Service API |
be11042041cb
2010-03-27 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
106815
diff
changeset
|
229 |
be11042041cb
2010-03-27 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
106815
diff
changeset
|
230 TODO: how does it work generally, how does secrets.el work, some examples. |
be11042041cb
2010-03-27 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
106815
diff
changeset
|
231 |
102054 | 232 @node Help for developers |
233 @chapter Help for developers | |
234 | |
235 The auth-source library only has one function for external use. | |
236 | |
107564
be11042041cb
2010-03-27 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
106815
diff
changeset
|
237 @defun auth-source-user-or-password mode host port &optional username |
102054 | 238 |
239 Retrieve appropriate authentication tokens, determined by @var{mode}, | |
107564
be11042041cb
2010-03-27 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
106815
diff
changeset
|
240 for host @var{host} and @var{port}. If @var{username} is provided it |
be11042041cb
2010-03-27 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
106815
diff
changeset
|
241 will also be checked. If @code{auth-source-debug} is t, debugging |
be11042041cb
2010-03-27 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
106815
diff
changeset
|
242 messages will be printed. Set @code{auth-source-debug} to a function |
be11042041cb
2010-03-27 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
106815
diff
changeset
|
243 to use that function for logging. The parameters passed will be the |
be11042041cb
2010-03-27 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
106815
diff
changeset
|
244 same that the @code{message} function takes, that is, a string |
104692 | 245 formatting spec and optional parameters. |
102054 | 246 |
247 If @var{mode} is a list of strings, the function will return a list of | |
104692 | 248 strings or @code{nil} objects (thus you can avoid parsing the netrc |
107564
be11042041cb
2010-03-27 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
106815
diff
changeset
|
249 file or checking the Secret Service API more than once). If it's a |
be11042041cb
2010-03-27 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
106815
diff
changeset
|
250 string, the function will return a string or a @code{nil} object. |
be11042041cb
2010-03-27 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
106815
diff
changeset
|
251 Currently only the modes ``login'' and ``password'' are recognized but |
be11042041cb
2010-03-27 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
106815
diff
changeset
|
252 more may be added in the future. |
102054 | 253 |
254 @var{host} is a string containing the host name. | |
255 | |
256 @var{port} contains the protocol name (e.g. ``imap'') or | |
257 a port number. It must be a string, corresponding to the port in the | |
258 users' netrc files. | |
259 | |
107564
be11042041cb
2010-03-27 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
106815
diff
changeset
|
260 @var{username} contains the user name (e.g. ``joe'') as a string. |
be11042041cb
2010-03-27 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
106815
diff
changeset
|
261 |
102054 | 262 @example |
263 ;; IMAP example | |
264 (setq auth (auth-source-user-or-password | |
265 '("login" "password") | |
266 "anyhostnamehere" | |
267 "imap")) | |
268 (nth 0 auth) ; the login name | |
269 (nth 1 auth) ; the password | |
270 @end example | |
271 | |
272 @end defun | |
273 | |
274 @node Index | |
275 @chapter Index | |
276 @printindex cp | |
277 | |
278 @node Function Index | |
279 @chapter Function Index | |
280 @printindex fn | |
281 | |
282 @node Variable Index | |
283 @chapter Variable Index | |
284 @printindex vr | |
285 | |
286 @bye | |
287 | |
288 @c End: | |
289 | |
290 @ignore | |
291 arch-tag: 7b835fd3-473f-40fc-9776-1c4e49d26c94 | |
292 @end ignore |