Mercurial > emacs
annotate doc/misc/auth.texi @ 111173:c7d5564f0621
Move ns-win.el's rather wacky menu adjustments to menu-bar.el.
* lisp/term/ns-win.el: Do not require easymenu.
(menu-bar-edit-menu) <copy, paste, paste-from-menu, separator-undo>:
<spell>: Move adjustments to menu-bar.el.
* lisp/menu-bar.el (menu-bar-edit-menu) <copy, paste, paste-from-menu>:
<separator-undo, spell>: Move ns-win's adjustments here.
* lisp/loadup.el [ns]: Do not load easymenu.
* src/Makefile.in (SOME_MACHINE_LISP): Remove easymenu.elc.
* lib-src/makefile.w32-in (OTHER_PLATFORM_SUPPORT): Remove easymenu.elc.
author | Glenn Morris <rgm@gnu.org> |
---|---|
date | Sun, 24 Oct 2010 17:48:26 -0700 |
parents | a82eb17e110e |
children | 417b1e4d63cd |
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 |
109274
a91e94388547
Minor doc/misc/*.texi direntry fixes.
Glenn Morris <rgm@gnu.org>
parents:
106815
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 | 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:: |
110859
7aa4fdb60d57
shr.el (shr-insert): Don't insert double spaces.
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
110102
diff
changeset
|
62 * GnuPG and EasyPG Assistant Configuration:: |
102054 | 63 * Index:: |
64 * Function Index:: | |
65 * Variable Index:: | |
66 @end menu | |
102059
9bcea07061a8
consistently use @insertcopying, @direntry, @contents
Karl Berry <karl@gnu.org>
parents:
102054
diff
changeset
|
67 @end ifnottex |
102054 | 68 |
69 @node Overview | |
70 @chapter Overview | |
71 | |
104891
2c607b344f3b
2009-09-02 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
104692
diff
changeset
|
72 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
|
73 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
|
74 a port, what are my user name and password?'' |
104692 | 75 |
76 The auth-source library actually supports more than just the user name | |
77 (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
|
78 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
|
79 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
|
80 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
|
81 Secret Service API. |
102054 | 82 |
83 @node Help for users | |
84 @chapter Help for users | |
85 | |
104692 | 86 ``Netrc'' files are a de facto standard. They look like this: |
87 @example | |
104891
2c607b344f3b
2009-09-02 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
104692
diff
changeset
|
88 machine @var{mymachine} login @var{myloginname} password @var{mypassword} port @var{myport} |
104692 | 89 @end example |
102054 | 90 |
104891
2c607b344f3b
2009-09-02 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
104692
diff
changeset
|
91 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
|
92 |
104692 | 93 The port is optional. If it's missing, auth-source will assume any |
94 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
|
95 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
|
96 @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
|
97 you don't need it. |
2c607b344f3b
2009-09-02 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
104692
diff
changeset
|
98 |
2c607b344f3b
2009-09-02 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
104692
diff
changeset
|
99 The login and password are simply your login credentials to the server. |
104692 | 100 |
104891
2c607b344f3b
2009-09-02 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
104692
diff
changeset
|
101 ``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
|
102 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
|
103 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
|
104 see later. |
104692 | 105 |
104891
2c607b344f3b
2009-09-02 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
104692
diff
changeset
|
106 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
|
107 @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
|
108 @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
|
109 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
|
110 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
|
111 the comments. |
2c607b344f3b
2009-09-02 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
104692
diff
changeset
|
112 |
2c607b344f3b
2009-09-02 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
104692
diff
changeset
|
113 You can customize the variable @code{auth-sources}. The following may |
104692 | 114 be needed if you are using an older version of Emacs or if the |
115 auth-source library is not loaded for some other reason. | |
102054 | 116 |
117 @lisp | |
104692 | 118 (require 'auth-source) ;; probably not necessary |
102054 | 119 (customize-variable 'auth-sources) ;; optional, do it once |
120 @end lisp | |
121 | |
122 @defvar auth-sources | |
123 | |
104891
2c607b344f3b
2009-09-02 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
104692
diff
changeset
|
124 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
|
125 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
|
126 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
|
127 and simplest configuration is: |
102054 | 128 |
129 @lisp | |
107564
be11042041cb
2010-03-27 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
106815
diff
changeset
|
130 ;;; old default: required :host and :protocol, not needed anymore |
102054 | 131 (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
|
132 ;;; 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
|
133 (setq auth-sources '((:source "~/.authinfo.gpg"))) |
102054 | 134 @end lisp |
135 | |
104692 | 136 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
|
137 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
|
138 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
|
139 that file. Make sure it exists. |
104692 | 140 |
104891
2c607b344f3b
2009-09-02 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
104692
diff
changeset
|
141 By adding multiple entries to @code{auth-sources} with a particular |
104692 | 142 host or protocol, you can have specific netrc files for that host or |
143 protocol. Usually this is unnecessary but may make sense if you have | |
144 shared netrc files or some other unusual setup (90% of Emacs users | |
145 have unusual setups and the remaining 10% are @emph{really} unusual). | |
102054 | 146 |
107564
be11042041cb
2010-03-27 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
106815
diff
changeset
|
147 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
|
148 using the default collection: |
be11042041cb
2010-03-27 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
106815
diff
changeset
|
149 |
be11042041cb
2010-03-27 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
106815
diff
changeset
|
150 @lisp |
be11042041cb
2010-03-27 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
106815
diff
changeset
|
151 (setq auth-sources '((:source (:secrets default)))) |
be11042041cb
2010-03-27 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
106815
diff
changeset
|
152 @end lisp |
be11042041cb
2010-03-27 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
106815
diff
changeset
|
153 |
be11042041cb
2010-03-27 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
106815
diff
changeset
|
154 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
|
155 |
be11042041cb
2010-03-27 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
106815
diff
changeset
|
156 @lisp |
be11042041cb
2010-03-27 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
106815
diff
changeset
|
157 (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
|
158 (:source "~/.authinfo.gpg"))) |
be11042041cb
2010-03-27 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
106815
diff
changeset
|
159 @end lisp |
be11042041cb
2010-03-27 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
106815
diff
changeset
|
160 |
be11042041cb
2010-03-27 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
106815
diff
changeset
|
161 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
|
162 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
|
163 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
|
164 @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
|
165 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
|
166 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
|
167 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
|
168 |
be11042041cb
2010-03-27 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
106815
diff
changeset
|
169 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
|
170 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
|
171 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
|
172 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
|
173 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
|
174 for details. |
be11042041cb
2010-03-27 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
106815
diff
changeset
|
175 |
102054 | 176 @end defvar |
177 | |
104891
2c607b344f3b
2009-09-02 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
104692
diff
changeset
|
178 If you don't customize @code{auth-sources}, you'll have to live with |
102054 | 179 the defaults: any host and any port are looked up in the netrc |
110968
3958dbde1223
Merge changes made in Gnus trunk.
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
110933
diff
changeset
|
180 file @code{~/.authinfo.gpg}, which is a GnuPG encrypted file |
3958dbde1223
Merge changes made in Gnus trunk.
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
110933
diff
changeset
|
181 (@pxref{GnuPG and EasyPG Assistant Configuration}). |
102054 | 182 |
104692 | 183 The simplest working netrc line example is one without a port. |
184 | |
185 @example | |
186 machine YOURMACHINE login YOU password YOURPASSWORD | |
187 @end example | |
188 | |
189 This will match any authentication port. Simple, right? But what if | |
190 there's a SMTP server on port 433 of that machine that needs a | |
191 different password from the IMAP server? | |
192 | |
193 @example | |
194 machine YOURMACHINE login YOU password SMTPPASSWORD port 433 | |
195 machine YOURMACHINE login YOU password GENERALPASSWORD | |
196 @end example | |
197 | |
102054 | 198 For url-auth authentication (HTTP/HTTPS), you need to put this in your |
199 netrc file: | |
200 | |
201 @example | |
202 machine yourmachine.com:80 port http login testuser password testpass | |
203 @end example | |
204 | |
104692 | 205 This will match any realm and authentication method (basic or digest) |
206 over HTTP. HTTPS is set up similarly. If you want finer controls, | |
207 explore the url-auth source code and variables. | |
102054 | 208 |
209 For Tramp authentication, use: | |
210 | |
211 @example | |
212 machine yourmachine.com port scp login testuser password testpass | |
213 @end example | |
214 | |
215 Note that the port denotes the Tramp connection method. When you | |
216 don't use a port entry, you match any Tramp method, as explained | |
104692 | 217 earlier. Since Tramp has about 88 connection methods, this may be |
218 necessary if you have an unusual (see earlier comment on those) setup. | |
102054 | 219 |
107564
be11042041cb
2010-03-27 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
106815
diff
changeset
|
220 @node Secret Service API |
be11042041cb
2010-03-27 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
106815
diff
changeset
|
221 @chapter Secret Service API |
be11042041cb
2010-03-27 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
106815
diff
changeset
|
222 |
be11042041cb
2010-03-27 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
106815
diff
changeset
|
223 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
|
224 |
102054 | 225 @node Help for developers |
226 @chapter Help for developers | |
227 | |
228 The auth-source library only has one function for external use. | |
229 | |
107564
be11042041cb
2010-03-27 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
106815
diff
changeset
|
230 @defun auth-source-user-or-password mode host port &optional username |
102054 | 231 |
232 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
|
233 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
|
234 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
|
235 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
|
236 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
|
237 same that the @code{message} function takes, that is, a string |
104692 | 238 formatting spec and optional parameters. |
102054 | 239 |
240 If @var{mode} is a list of strings, the function will return a list of | |
104692 | 241 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
|
242 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
|
243 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
|
244 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
|
245 more may be added in the future. |
102054 | 246 |
247 @var{host} is a string containing the host name. | |
248 | |
249 @var{port} contains the protocol name (e.g. ``imap'') or | |
250 a port number. It must be a string, corresponding to the port in the | |
251 users' netrc files. | |
252 | |
107564
be11042041cb
2010-03-27 Teodor Zlatanov <tzz@lifelogs.com>
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
106815
diff
changeset
|
253 @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
|
254 |
102054 | 255 @example |
256 ;; IMAP example | |
257 (setq auth (auth-source-user-or-password | |
258 '("login" "password") | |
259 "anyhostnamehere" | |
260 "imap")) | |
261 (nth 0 auth) ; the login name | |
262 (nth 1 auth) ; the password | |
263 @end example | |
264 | |
265 @end defun | |
266 | |
110859
7aa4fdb60d57
shr.el (shr-insert): Don't insert double spaces.
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
110102
diff
changeset
|
267 @node GnuPG and EasyPG Assistant Configuration |
7aa4fdb60d57
shr.el (shr-insert): Don't insert double spaces.
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
110102
diff
changeset
|
268 @appendix GnuPG and EasyPG Assistant Configuration |
7aa4fdb60d57
shr.el (shr-insert): Don't insert double spaces.
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
110102
diff
changeset
|
269 |
110933
7c7fd71d22c7
Clarify the doc about caching passphrases.
Daiki Ueno <ueno@unixuser.org>
parents:
110859
diff
changeset
|
270 If you don't customize @code{auth-sources}, the auth-source library |
7c7fd71d22c7
Clarify the doc about caching passphrases.
Daiki Ueno <ueno@unixuser.org>
parents:
110859
diff
changeset
|
271 reads @code{~/.authinfo.gpg}, which is a GnuPG encrypted file. |
7c7fd71d22c7
Clarify the doc about caching passphrases.
Daiki Ueno <ueno@unixuser.org>
parents:
110859
diff
changeset
|
272 |
110859
7aa4fdb60d57
shr.el (shr-insert): Don't insert double spaces.
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
110102
diff
changeset
|
273 In Emacs 23 or later there is an option @code{auto-encryption-mode} to |
110968
3958dbde1223
Merge changes made in Gnus trunk.
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
110933
diff
changeset
|
274 automatically decrypt @code{*.gpg} files. It is enabled by default. |
3958dbde1223
Merge changes made in Gnus trunk.
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
110933
diff
changeset
|
275 If you are using earlier versions of Emacs, you will need: |
110859
7aa4fdb60d57
shr.el (shr-insert): Don't insert double spaces.
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
110102
diff
changeset
|
276 |
7aa4fdb60d57
shr.el (shr-insert): Don't insert double spaces.
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
110102
diff
changeset
|
277 @lisp |
7aa4fdb60d57
shr.el (shr-insert): Don't insert double spaces.
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
110102
diff
changeset
|
278 (require 'epa-file) |
7aa4fdb60d57
shr.el (shr-insert): Don't insert double spaces.
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
110102
diff
changeset
|
279 (epa-file-enable) |
7aa4fdb60d57
shr.el (shr-insert): Don't insert double spaces.
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
110102
diff
changeset
|
280 @end lisp |
7aa4fdb60d57
shr.el (shr-insert): Don't insert double spaces.
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
110102
diff
changeset
|
281 |
110933
7c7fd71d22c7
Clarify the doc about caching passphrases.
Daiki Ueno <ueno@unixuser.org>
parents:
110859
diff
changeset
|
282 If you want your GnuPG passwords to be cached, set up @code{gpg-agent} |
110859
7aa4fdb60d57
shr.el (shr-insert): Don't insert double spaces.
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
110102
diff
changeset
|
283 or EasyPG Assitant |
111004
a82eb17e110e
auth.texi (GnuPG and EasyPG Assistant Configuration): Fix markup.
Eli Zaretskii <eliz@gnu.org>
parents:
110968
diff
changeset
|
284 (@pxref{Caching Passphrases, , Caching Passphrases, epa}). |
110859
7aa4fdb60d57
shr.el (shr-insert): Don't insert double spaces.
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
110102
diff
changeset
|
285 |
110933
7c7fd71d22c7
Clarify the doc about caching passphrases.
Daiki Ueno <ueno@unixuser.org>
parents:
110859
diff
changeset
|
286 To quick start, here are some questions: |
110859
7aa4fdb60d57
shr.el (shr-insert): Don't insert double spaces.
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
110102
diff
changeset
|
287 |
7aa4fdb60d57
shr.el (shr-insert): Don't insert double spaces.
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
110102
diff
changeset
|
288 @enumerate |
110968
3958dbde1223
Merge changes made in Gnus trunk.
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
110933
diff
changeset
|
289 @item |
3958dbde1223
Merge changes made in Gnus trunk.
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
110933
diff
changeset
|
290 Do you use GnuPG version 2 instead of GnuPG version 1? |
3958dbde1223
Merge changes made in Gnus trunk.
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
110933
diff
changeset
|
291 @item |
3958dbde1223
Merge changes made in Gnus trunk.
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
110933
diff
changeset
|
292 Do you use symmetric encryption rather than public key encryption? |
3958dbde1223
Merge changes made in Gnus trunk.
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
110933
diff
changeset
|
293 @item |
3958dbde1223
Merge changes made in Gnus trunk.
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
110933
diff
changeset
|
294 Do you want to use gpg-agent? |
110859
7aa4fdb60d57
shr.el (shr-insert): Don't insert double spaces.
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
110102
diff
changeset
|
295 @end enumerate |
7aa4fdb60d57
shr.el (shr-insert): Don't insert double spaces.
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
110102
diff
changeset
|
296 |
7aa4fdb60d57
shr.el (shr-insert): Don't insert double spaces.
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
110102
diff
changeset
|
297 Here are configurations depending on your answers: |
7aa4fdb60d57
shr.el (shr-insert): Don't insert double spaces.
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
110102
diff
changeset
|
298 |
7aa4fdb60d57
shr.el (shr-insert): Don't insert double spaces.
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
110102
diff
changeset
|
299 @multitable {111} {222} {333} {configuration configuration configuration} |
7aa4fdb60d57
shr.el (shr-insert): Don't insert double spaces.
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
110102
diff
changeset
|
300 @item @b{1} @tab @b{2} @tab @b{3} @tab Configuration |
110933
7c7fd71d22c7
Clarify the doc about caching passphrases.
Daiki Ueno <ueno@unixuser.org>
parents:
110859
diff
changeset
|
301 @item Yes @tab Yes @tab Yes @tab Set up gpg-agent. |
110859
7aa4fdb60d57
shr.el (shr-insert): Don't insert double spaces.
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
110102
diff
changeset
|
302 @item Yes @tab Yes @tab No @tab You can't, without gpg-agent. |
110933
7c7fd71d22c7
Clarify the doc about caching passphrases.
Daiki Ueno <ueno@unixuser.org>
parents:
110859
diff
changeset
|
303 @item Yes @tab No @tab Yes @tab Set up gpg-agent. |
110859
7aa4fdb60d57
shr.el (shr-insert): Don't insert double spaces.
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
110102
diff
changeset
|
304 @item Yes @tab No @tab No @tab You can't, without gpg-agent. |
7aa4fdb60d57
shr.el (shr-insert): Don't insert double spaces.
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
110102
diff
changeset
|
305 @item No @tab Yes @tab Yes @tab Set up elisp passphrase cache. |
7aa4fdb60d57
shr.el (shr-insert): Don't insert double spaces.
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
110102
diff
changeset
|
306 @item No @tab Yes @tab No @tab Set up elisp passphrase cache. |
110933
7c7fd71d22c7
Clarify the doc about caching passphrases.
Daiki Ueno <ueno@unixuser.org>
parents:
110859
diff
changeset
|
307 @item No @tab No @tab Yes @tab Set up gpg-agent. |
110859
7aa4fdb60d57
shr.el (shr-insert): Don't insert double spaces.
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
110102
diff
changeset
|
308 @item No @tab No @tab No @tab You can't, without gpg-agent. |
7aa4fdb60d57
shr.el (shr-insert): Don't insert double spaces.
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
110102
diff
changeset
|
309 @end multitable |
7aa4fdb60d57
shr.el (shr-insert): Don't insert double spaces.
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
110102
diff
changeset
|
310 |
110968
3958dbde1223
Merge changes made in Gnus trunk.
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
110933
diff
changeset
|
311 To set up gpg-agent, follow the instruction in GnuPG manual |
3958dbde1223
Merge changes made in Gnus trunk.
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
110933
diff
changeset
|
312 (@pxref{Invoking GPG-AGENT, , Invoking GPG-AGENT, gnupg}). |
110859
7aa4fdb60d57
shr.el (shr-insert): Don't insert double spaces.
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
110102
diff
changeset
|
313 |
7aa4fdb60d57
shr.el (shr-insert): Don't insert double spaces.
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
110102
diff
changeset
|
314 To set up elisp passphrase cache, set |
7aa4fdb60d57
shr.el (shr-insert): Don't insert double spaces.
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
110102
diff
changeset
|
315 @code{epa-file-cache-passphrase-for-symmetric-encryption}. |
7aa4fdb60d57
shr.el (shr-insert): Don't insert double spaces.
Katsumi Yamaoka <yamaoka@jpl.org>
parents:
110102
diff
changeset
|
316 |
102054 | 317 @node Index |
318 @chapter Index | |
319 @printindex cp | |
320 | |
321 @node Function Index | |
322 @chapter Function Index | |
323 @printindex fn | |
324 | |
325 @node Variable Index | |
326 @chapter Variable Index | |
327 @printindex vr | |
328 | |
329 @bye | |
330 | |
331 @c End: |