Mercurial > emacs
comparison doc/misc/auth.texi @ 104692:b99b3dda298b
Merge from gnus--devo--0
Revision: emacs@sv.gnu.org/emacs--devo--0--patch-1629
author | Miles Bader <miles@gnu.org> |
---|---|
date | Sat, 29 Aug 2009 00:27:12 +0000 |
parents | 3e7c6b40afdd |
children | 2c607b344f3b |
comparison
equal
deleted
inserted
replaced
104691:669c6df8c8b9 | 104692:b99b3dda298b |
---|---|
1 \input texinfo @c -*-texinfo-*- | 1 \input texinfo @c -*-texinfo-*- |
2 @setfilename ../../info/auth | 2 @setfilename ../../info/auth |
3 @settitle Emacs auth-source Library @value{VERSION} | 3 @settitle Emacs auth-source Library @value{VERSION} |
4 | 4 |
5 @set VERSION 0.1 | 5 @set VERSION 0.2 |
6 | 6 |
7 @copying | 7 @copying |
8 This file describes the Emacs auth-source library. | 8 This file describes the Emacs auth-source library. |
9 | 9 |
10 Copyright @copyright{} 2008, 2009 Free Software Foundation, Inc. | 10 Copyright @copyright{} 2008, 2009 Free Software Foundation, Inc. |
65 @end ifnottex | 65 @end ifnottex |
66 | 66 |
67 @node Overview | 67 @node Overview |
68 @chapter Overview | 68 @chapter Overview |
69 | 69 |
70 To be done. | 70 The auth-source library is a modern, extensible, enterprise-class |
71 authentication library. It uses the latest design patterns, has 1800 | |
72 unit tests, and has been featured in 21 industry conference keynote | |
73 talks. It's future-proof, mathematically proven to be bug-free, and | |
74 has 6 internal XML parsers just in case you ever need to eat up some | |
75 memory. | |
76 | |
77 Just kidding. The auth-source library is simply a way for Emacs and | |
78 Gnus, among others, to find the answer to the old burning question ``I | |
79 have a server name and a port, what are my user name and password?'' | |
80 | |
81 The auth-source library actually supports more than just the user name | |
82 (known as the login) or the password, but only those two are in use | |
83 today in Emacs or Gnus. Similarly, the auth-source library can in | |
84 theory support multiple storage formats, but currently it only | |
85 understands the classic ``netrc'' format, examples of which you can | |
86 see later in this document. | |
71 | 87 |
72 @node Help for users | 88 @node Help for users |
73 @chapter Help for users | 89 @chapter Help for users |
74 | 90 |
75 If you have problems with the port, turn up @code{gnus-verbose} and | 91 ``Netrc'' files are a de facto standard. They look like this: |
76 see what port the library is checking. Ditto for any other | 92 @example |
77 problems, your first step is to see what's being checked. | 93 machine mymachine login myloginname password mypassword port myport |
78 | 94 @end example |
79 Setup: | 95 |
96 The port is optional. If it's missing, auth-source will assume any | |
97 port is OK. Actually the port is a protocol name or a port number so | |
98 you can have separate entries for port 143 and for protocol ``imap'' | |
99 if you fancy that. Anyway, you can just omit the port if you don't | |
100 need it. ``Netrc'' files are usually called @code{.authinfo} or | |
101 @code{.netrc}; nowadays @code{.authinfo} seems to be more popular and | |
102 the auth-source library encourages this confusion by making it the | |
103 default, as you'll see later. | |
104 | |
105 If you have problems with the port, set @var{auth-source-debug} to t | |
106 and see what port the library is checking in the @code{*Messages*} | |
107 buffer. Ditto for any other problems, your first step is always to | |
108 see what's being checked. The second step, of course, is to write a | |
109 blog entry about it and wait for the answer in the comments. | |
110 | |
111 You can customize the variable @var{auth-sources}. The following may | |
112 be needed if you are using an older version of Emacs or if the | |
113 auth-source library is not loaded for some other reason. | |
80 | 114 |
81 @lisp | 115 @lisp |
82 (require 'auth-source) | 116 (require 'auth-source) ;; probably not necessary |
83 (customize-variable 'auth-sources) ;; optional, do it once | 117 (customize-variable 'auth-sources) ;; optional, do it once |
84 @end lisp | 118 @end lisp |
85 | 119 |
86 @defvar auth-sources | 120 @defvar auth-sources |
87 | 121 |
91 | 125 |
92 @lisp | 126 @lisp |
93 (setq auth-sources '((:source "~/.authinfo.gpg" :host t :protocol t))) | 127 (setq auth-sources '((:source "~/.authinfo.gpg" :host t :protocol t))) |
94 @end lisp | 128 @end lisp |
95 | 129 |
96 By adding multiple entries to that list with a particular host or | 130 This says ``for any host and any protocol, use just that one file.'' |
97 protocol, you can have specific netrc files for that host or protocol. | 131 Sweet simplicity. In fact, this is already the default, so unless you |
132 want to move your netrc file, it will just work if you have that | |
133 file. You may not, though, so make sure it exists. | |
134 | |
135 By adding multiple entries to @var{auth-sources} with a particular | |
136 host or protocol, you can have specific netrc files for that host or | |
137 protocol. Usually this is unnecessary but may make sense if you have | |
138 shared netrc files or some other unusual setup (90% of Emacs users | |
139 have unusual setups and the remaining 10% are @emph{really} unusual). | |
98 | 140 |
99 @end defvar | 141 @end defvar |
100 | |
101 | |
102 ``Netrc'' files are a de facto standard. They look like this: | |
103 @example | |
104 machine mymachine login myloginname password mypassword port myport | |
105 @end example | |
106 | |
107 The port is optional. If it's missing, auth-source will assume any | |
108 port is OK. Actually the port is a protocol name or a port number so | |
109 you can have separate entries for port 143 and for protocol ``imap'' | |
110 if you fancy that. | |
111 | 142 |
112 If you don't customize @var{auth-sources}, you'll have to live with | 143 If you don't customize @var{auth-sources}, you'll have to live with |
113 the defaults: any host and any port are looked up in the netrc | 144 the defaults: any host and any port are looked up in the netrc |
114 file @code{~/.authinfo.gpg}. This is an encrypted file if and only if | 145 file @code{~/.authinfo.gpg}. This is an encrypted file if and only if |
115 you set up EPA, which is strongly recommended. | 146 you set up EPA, which is strongly recommended. |
116 | 147 |
117 @lisp | 148 @lisp |
118 (require 'epa-file) | 149 (require 'epa-file) |
119 (epa-file-enable) | 150 (epa-file-enable) |
120 (setq epa-file-cache-passphrase-for-symmetric-encryption t) ; VERY important | 151 ;;; VERY important if you want symmetric encryption |
152 ;;; irrelevant if you don't | |
153 (setq epa-file-cache-passphrase-for-symmetric-encryption t) | |
121 @end lisp | 154 @end lisp |
155 | |
156 The simplest working netrc line example is one without a port. | |
157 | |
158 @example | |
159 machine YOURMACHINE login YOU password YOURPASSWORD | |
160 @end example | |
161 | |
162 This will match any authentication port. Simple, right? But what if | |
163 there's a SMTP server on port 433 of that machine that needs a | |
164 different password from the IMAP server? | |
165 | |
166 @example | |
167 machine YOURMACHINE login YOU password SMTPPASSWORD port 433 | |
168 machine YOURMACHINE login YOU password GENERALPASSWORD | |
169 @end example | |
122 | 170 |
123 For url-auth authentication (HTTP/HTTPS), you need to put this in your | 171 For url-auth authentication (HTTP/HTTPS), you need to put this in your |
124 netrc file: | 172 netrc file: |
125 | 173 |
126 @example | 174 @example |
127 machine yourmachine.com:80 port http login testuser password testpass | 175 machine yourmachine.com:80 port http login testuser password testpass |
128 @end example | 176 @end example |
129 | 177 |
130 This will match any realm and authentication method (basic or | 178 This will match any realm and authentication method (basic or digest) |
131 digest). If you want finer controls, explore the url-auth source | 179 over HTTP. HTTPS is set up similarly. If you want finer controls, |
132 code and variables. | 180 explore the url-auth source code and variables. |
133 | 181 |
134 For Tramp authentication, use: | 182 For Tramp authentication, use: |
135 | 183 |
136 @example | 184 @example |
137 machine yourmachine.com port scp login testuser password testpass | 185 machine yourmachine.com port scp login testuser password testpass |
138 @end example | 186 @end example |
139 | 187 |
140 Note that the port denotes the Tramp connection method. When you | 188 Note that the port denotes the Tramp connection method. When you |
141 don't use a port entry, you match any Tramp method, as explained | 189 don't use a port entry, you match any Tramp method, as explained |
142 earlier. | 190 earlier. Since Tramp has about 88 connection methods, this may be |
191 necessary if you have an unusual (see earlier comment on those) setup. | |
143 | 192 |
144 @node Help for developers | 193 @node Help for developers |
145 @chapter Help for developers | 194 @chapter Help for developers |
146 | 195 |
147 The auth-source library only has one function for external use. | 196 The auth-source library only has one function for external use. |
148 | 197 |
149 @defun auth-source-user-or-password mode host port | 198 @defun auth-source-user-or-password mode host port |
150 | 199 |
151 Retrieve appropriate authentication tokens, determined by @var{mode}, | 200 Retrieve appropriate authentication tokens, determined by @var{mode}, |
152 for host @var{host} and @var{port}. If @code{gnus-verbose} is 9 or | 201 for host @var{host} and @var{port}. If @var{auth-source-debug} is t, |
153 higher, debugging messages will be printed. | 202 debugging messages will be printed. Set @var{auth-source-debug} to a |
203 function to use that function for logging. The parameters passed will | |
204 be the same that the @code{message} function takes, that is, a string | |
205 formatting spec and optional parameters. | |
154 | 206 |
155 If @var{mode} is a list of strings, the function will return a list of | 207 If @var{mode} is a list of strings, the function will return a list of |
156 strings or @code{nil} objects. If it's a string, the function will | 208 strings or @code{nil} objects (thus you can avoid parsing the netrc |
157 return a string or a @code{nil} object. Currently only the modes | 209 file more than once). If it's a string, the function will return a |
158 ``login'' and ``password'' are recognized but more may be added in the | 210 string or a @code{nil} object. Currently only the modes ``login'' and |
159 future. | 211 ``password'' are recognized but more may be added in the future. |
160 | 212 |
161 @var{host} is a string containing the host name. | 213 @var{host} is a string containing the host name. |
162 | 214 |
163 @var{port} contains the protocol name (e.g. ``imap'') or | 215 @var{port} contains the protocol name (e.g. ``imap'') or |
164 a port number. It must be a string, corresponding to the port in the | 216 a port number. It must be a string, corresponding to the port in the |