| 1 | \input texinfo @c -*-texinfo-*- |
| 2 | |
| 3 | @include gnus-overrides.texi |
| 4 | |
| 5 | @setfilename ../../info/auth |
| 6 | @settitle Emacs auth-source Library @value{VERSION} |
| 7 | |
| 8 | @set VERSION 0.3 |
| 9 | |
| 10 | @copying |
| 11 | This file describes the Emacs auth-source library. |
| 12 | |
| 13 | Copyright @copyright{} 2008-2012 Free Software Foundation, Inc. |
| 14 | |
| 15 | @quotation |
| 16 | Permission is granted to copy, distribute and/or modify this document |
| 17 | under the terms of the GNU Free Documentation License, Version 1.3 or |
| 18 | any later version published by the Free Software Foundation; with no |
| 19 | Invariant Sections, with the Front-Cover texts being ``A GNU Manual,'' |
| 20 | and with the Back-Cover Texts as in (a) below. A copy of the license |
| 21 | is included in the section entitled ``GNU Free Documentation License'' |
| 22 | in the Emacs manual. |
| 23 | |
| 24 | (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and |
| 25 | modify this GNU manual. Buying copies from the FSF supports it in |
| 26 | developing GNU and promoting software freedom.'' |
| 27 | |
| 28 | This document is part of a collection distributed under the GNU Free |
| 29 | Documentation License. If you want to distribute this document |
| 30 | separately from the collection, you can do so by adding a copy of the |
| 31 | license to the document, as described in section 6 of the license. |
| 32 | @end quotation |
| 33 | @end copying |
| 34 | |
| 35 | @dircategory Emacs lisp libraries |
| 36 | @direntry |
| 37 | * Auth-source: (auth). The Emacs auth-source library. |
| 38 | @end direntry |
| 39 | |
| 40 | @titlepage |
| 41 | @ifset WEBHACKDEVEL |
| 42 | @title Emacs auth-source Library (DEVELOPMENT VERSION) |
| 43 | @end ifset |
| 44 | @ifclear WEBHACKDEVEL |
| 45 | @title Emacs auth-source Library |
| 46 | @end ifclear |
| 47 | @author by Ted Zlatanov |
| 48 | @page |
| 49 | @vskip 0pt plus 1filll |
| 50 | @insertcopying |
| 51 | @end titlepage |
| 52 | |
| 53 | @contents |
| 54 | |
| 55 | @ifnottex |
| 56 | @node Top |
| 57 | @top Emacs auth-source |
| 58 | This manual describes the Emacs auth-source library. |
| 59 | |
| 60 | It is a way for multiple applications to share a single configuration |
| 61 | (in Emacs and in files) for user convenience. |
| 62 | |
| 63 | @insertcopying |
| 64 | |
| 65 | @menu |
| 66 | * Overview:: Overview of the auth-source library. |
| 67 | * Help for users:: |
| 68 | * Secret Service API:: |
| 69 | * Help for developers:: |
| 70 | * GnuPG and EasyPG Assistant Configuration:: |
| 71 | * Index:: |
| 72 | * Function Index:: |
| 73 | * Variable Index:: |
| 74 | @end menu |
| 75 | @end ifnottex |
| 76 | |
| 77 | @node Overview |
| 78 | @chapter Overview |
| 79 | |
| 80 | The auth-source library is simply a way for Emacs and Gnus, among |
| 81 | others, to answer the old burning question ``What are my user name and |
| 82 | password?'' |
| 83 | |
| 84 | (This is different from the old question about burning ``Where is the |
| 85 | fire extinguisher, please?''.) |
| 86 | |
| 87 | The auth-source library supports more than just the user name or the |
| 88 | password (known as the secret). |
| 89 | |
| 90 | Similarly, the auth-source library supports multiple storage backend, |
| 91 | currently either the classic ``netrc'' backend, examples of which you |
| 92 | can see later in this document, or the Secret Service API. This is |
| 93 | done with EIEIO-based backends and you can write your own if you want. |
| 94 | |
| 95 | @node Help for users |
| 96 | @chapter Help for users |
| 97 | |
| 98 | ``Netrc'' files are a de facto standard. They look like this: |
| 99 | @example |
| 100 | machine @var{mymachine} login @var{myloginname} password @var{mypassword} port @var{myport} |
| 101 | @end example |
| 102 | |
| 103 | The @code{machine} is the server (either a DNS name or an IP address). |
| 104 | It's known as @var{:host} in @code{auth-source-search} queries. You |
| 105 | can also use @code{host}. |
| 106 | |
| 107 | The @code{port} is the connection port or protocol. It's known as |
| 108 | @var{:port} in @code{auth-source-search} queries. |
| 109 | |
| 110 | The @code{user} is the user name. It's known as @var{:user} in |
| 111 | @code{auth-source-search} queries. You can also use @code{login} and |
| 112 | @code{account}. |
| 113 | |
| 114 | Spaces are always OK as far as auth-source is concerned (but other |
| 115 | programs may not like them). Just put the data in quotes, escaping |
| 116 | quotes as you'd expect with @code{\}. |
| 117 | |
| 118 | All these are optional. You could just say (but we don't recommend |
| 119 | it, we're just showing that it's possible) |
| 120 | |
| 121 | @example |
| 122 | password @var{mypassword} |
| 123 | @end example |
| 124 | |
| 125 | to use the same password everywhere. Again, @emph{DO NOT DO THIS} or |
| 126 | you will be pwned as the kids say. |
| 127 | |
| 128 | ``Netrc'' files are usually called @code{.authinfo} or @code{.netrc}; |
| 129 | nowadays @code{.authinfo} seems to be more popular and the auth-source |
| 130 | library encourages this confusion by accepting both, as you'll see |
| 131 | later. |
| 132 | |
| 133 | If you have problems with the search, set @code{auth-source-debug} to |
| 134 | @code{'trivia} and see what host, port, and user the library is |
| 135 | checking in the @code{*Messages*} buffer. Ditto for any other |
| 136 | problems, your first step is always to see what's being checked. The |
| 137 | second step, of course, is to write a blog entry about it and wait for |
| 138 | the answer in the comments. |
| 139 | |
| 140 | You can customize the variable @code{auth-sources}. The following may |
| 141 | be needed if you are using an older version of Emacs or if the |
| 142 | auth-source library is not loaded for some other reason. |
| 143 | |
| 144 | @lisp |
| 145 | (require 'auth-source) ;; probably not necessary |
| 146 | (customize-variable 'auth-sources) ;; optional, do it once |
| 147 | @end lisp |
| 148 | |
| 149 | @defvar auth-sources |
| 150 | |
| 151 | The @code{auth-sources} variable tells the auth-source library where |
| 152 | your netrc files or Secret Service API collection items live for a |
| 153 | particular host and protocol. While you can get fancy, the default |
| 154 | and simplest configuration is: |
| 155 | |
| 156 | @lisp |
| 157 | ;;; old default: required :host and :port, not needed anymore |
| 158 | (setq auth-sources '((:source "~/.authinfo.gpg" :host t :port t))) |
| 159 | ;;; mostly equivalent (see below about fallbacks) but shorter: |
| 160 | (setq auth-sources '((:source "~/.authinfo.gpg"))) |
| 161 | ;;; even shorter and the @emph{default}: |
| 162 | (setq auth-sources '("~/.authinfo.gpg" "~/.authinfo" "~/.netrc")) |
| 163 | ;;; use the Secrets API @var{Login} collection (@pxref{Secret Service API}) |
| 164 | (setq auth-sources '("secrets:Login")) |
| 165 | @end lisp |
| 166 | |
| 167 | By adding multiple entries to @code{auth-sources} with a particular |
| 168 | host or protocol, you can have specific netrc files for that host or |
| 169 | protocol. Usually this is unnecessary but may make sense if you have |
| 170 | shared netrc files or some other unusual setup (90% of Emacs users |
| 171 | have unusual setups and the remaining 10% are @emph{really} unusual). |
| 172 | |
| 173 | Here's a mixed example using two sources: |
| 174 | |
| 175 | @lisp |
| 176 | (setq auth-sources '((:source (:secrets default) :host "myserver" :user "joe") |
| 177 | "~/.authinfo.gpg")) |
| 178 | @end lisp |
| 179 | |
| 180 | @end defvar |
| 181 | |
| 182 | If you don't customize @code{auth-sources}, you'll have to live with |
| 183 | the defaults: any host and any port are looked up in the netrc |
| 184 | file @code{~/.authinfo.gpg}, which is a GnuPG encrypted file |
| 185 | (@pxref{GnuPG and EasyPG Assistant Configuration}). |
| 186 | |
| 187 | If that fails, the unencrypted netrc files @code{~/.authinfo} and |
| 188 | @code{~/.netrc} will be used. |
| 189 | |
| 190 | The typical netrc line example is 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 | |
| 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 | |
| 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. |
| 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 |
| 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. |
| 226 | |
| 227 | @node Secret Service API |
| 228 | @chapter Secret Service API |
| 229 | |
| 230 | TODO: how does it work generally, how does secrets.el work, some examples. |
| 231 | |
| 232 | @node Help for developers |
| 233 | @chapter Help for developers |
| 234 | |
| 235 | The auth-source library lets you control logging output easily. |
| 236 | |
| 237 | @defvar auth-source-debug |
| 238 | Set this variable to 'trivia to see lots of output in *Messages*, or |
| 239 | set it to a function that behaves like @code{message} to do your own |
| 240 | logging. |
| 241 | @end defvar |
| 242 | |
| 243 | The auth-source library only has a few functions for external use. |
| 244 | |
| 245 | @defun auth-source-search SPEC |
| 246 | |
| 247 | TODO: how to include docstring? |
| 248 | |
| 249 | @end defun |
| 250 | |
| 251 | Let's take a look at an example of using @code{auth-source-search} |
| 252 | from Gnus' @code{nnimap.el}. |
| 253 | |
| 254 | @example |
| 255 | (defun nnimap-credentials (address ports) |
| 256 | (let* ((auth-source-creation-prompts |
| 257 | '((user . "IMAP user at %h: ") |
| 258 | (secret . "IMAP password for %u@@%h: "))) |
| 259 | (found (nth 0 (auth-source-search :max 1 |
| 260 | :host address |
| 261 | :port ports |
| 262 | :require '(:user :secret) |
| 263 | :create t)))) |
| 264 | (if found |
| 265 | (list (plist-get found :user) |
| 266 | (let ((secret (plist-get found :secret))) |
| 267 | (if (functionp secret) |
| 268 | (funcall secret) |
| 269 | secret)) |
| 270 | (plist-get found :save-function)) |
| 271 | nil))) |
| 272 | @end example |
| 273 | |
| 274 | This call requires the user and password (secret) to be in the |
| 275 | results. It also requests that an entry be created if it doesn't |
| 276 | exist already. While the created entry is being assembled, the shown |
| 277 | prompts will be used to interact with the user. The caller can also |
| 278 | pass data in @code{auth-source-creation-defaults} to supply defaults |
| 279 | for any of the prompts. |
| 280 | |
| 281 | Note that the password needs to be evaluated if it's a function. It's |
| 282 | wrapped in a function to provide some security. |
| 283 | |
| 284 | Later, after a successful login, @code{nnimap.el} calls the |
| 285 | @code{:save-function} like so: |
| 286 | |
| 287 | @example |
| 288 | (when (functionp (nth 2 credentials)) |
| 289 | (funcall (nth 2 credentials))) |
| 290 | @end example |
| 291 | |
| 292 | This will work whether the @code{:save-function} was provided or not. |
| 293 | @code{:save-function} will be provided only when a new entry was |
| 294 | created, so this effectively says ``after a successful login, save the |
| 295 | authentication information we just used, if it was newly created.'' |
| 296 | |
| 297 | After the first time it's called, the @code{:save-function} will not |
| 298 | run again (but it will log something if you have set |
| 299 | @code{auth-source-debug} to @code{'trivia}). This is so it won't ask |
| 300 | the same question again, which is annoying. This is so it won't ask |
| 301 | the same question again, which is annoying. This is so it won't ask |
| 302 | the same question again, which is annoying. |
| 303 | |
| 304 | So the responsibility of the API user that specified @code{:create t} |
| 305 | is to call the @code{:save-function} if it's provided. |
| 306 | |
| 307 | @defun auth-source-delete SPEC |
| 308 | |
| 309 | TODO: how to include docstring? |
| 310 | |
| 311 | @end defun |
| 312 | |
| 313 | @defun auth-source-forget SPEC |
| 314 | |
| 315 | TODO: how to include docstring? |
| 316 | |
| 317 | @end defun |
| 318 | |
| 319 | @defun auth-source-forget+ SPEC |
| 320 | |
| 321 | TODO: how to include docstring? |
| 322 | |
| 323 | @end defun |
| 324 | |
| 325 | @node GnuPG and EasyPG Assistant Configuration |
| 326 | @appendix GnuPG and EasyPG Assistant Configuration |
| 327 | |
| 328 | If you don't customize @code{auth-sources}, the auth-source library |
| 329 | reads @code{~/.authinfo.gpg}, which is a GnuPG encrypted file. Then |
| 330 | it will check @code{~/.authinfo} but it's not recommended to use such |
| 331 | an unencrypted file. |
| 332 | |
| 333 | In Emacs 23 or later there is an option @code{auto-encryption-mode} to |
| 334 | automatically decrypt @code{*.gpg} files. It is enabled by default. |
| 335 | If you are using earlier versions of Emacs, you will need: |
| 336 | |
| 337 | @lisp |
| 338 | (require 'epa-file) |
| 339 | (epa-file-enable) |
| 340 | @end lisp |
| 341 | |
| 342 | If you want your GnuPG passwords to be cached, set up @code{gpg-agent} |
| 343 | or EasyPG Assistant |
| 344 | (@pxref{Caching Passphrases, , Caching Passphrases, epa}). |
| 345 | |
| 346 | To quick start, here are some questions: |
| 347 | |
| 348 | @enumerate |
| 349 | @item |
| 350 | Do you use GnuPG version 2 instead of GnuPG version 1? |
| 351 | @item |
| 352 | Do you use symmetric encryption rather than public key encryption? |
| 353 | @item |
| 354 | Do you want to use gpg-agent? |
| 355 | @end enumerate |
| 356 | |
| 357 | Here are configurations depending on your answers: |
| 358 | |
| 359 | @multitable {111} {222} {333} {configuration configuration configuration} |
| 360 | @item @b{1} @tab @b{2} @tab @b{3} @tab Configuration |
| 361 | @item Yes @tab Yes @tab Yes @tab Set up gpg-agent. |
| 362 | @item Yes @tab Yes @tab No @tab You can't, without gpg-agent. |
| 363 | @item Yes @tab No @tab Yes @tab Set up gpg-agent. |
| 364 | @item Yes @tab No @tab No @tab You can't, without gpg-agent. |
| 365 | @item No @tab Yes @tab Yes @tab Set up elisp passphrase cache. |
| 366 | @item No @tab Yes @tab No @tab Set up elisp passphrase cache. |
| 367 | @item No @tab No @tab Yes @tab Set up gpg-agent. |
| 368 | @item No @tab No @tab No @tab You can't, without gpg-agent. |
| 369 | @end multitable |
| 370 | |
| 371 | To set up gpg-agent, follow the instruction in GnuPG manual |
| 372 | (@pxref{Invoking GPG-AGENT, , Invoking GPG-AGENT, gnupg}). |
| 373 | |
| 374 | To set up elisp passphrase cache, set |
| 375 | @code{epa-file-cache-passphrase-for-symmetric-encryption}. |
| 376 | |
| 377 | @node Index |
| 378 | @chapter Index |
| 379 | @printindex cp |
| 380 | |
| 381 | @node Function Index |
| 382 | @chapter Function Index |
| 383 | @printindex fn |
| 384 | |
| 385 | @node Variable Index |
| 386 | @chapter Variable Index |
| 387 | @printindex vr |
| 388 | |
| 389 | @bye |
| 390 | |
| 391 | @c End: |