doc/misc/auth.texi

   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-2011 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 making it the default, as you'll
 131 see later.
 132
 133 If you have problems with the search, set @code{auth-source-debug} to
 134 @code{t} and see what host, port, and user the library is checking in
 135 the @code{*Messages*} buffer.  Ditto for any other problems, your
 136 first step is always to see what's being checked.  The second step, of
 137 course, is to write a blog entry about it and wait for the answer in
 138 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"))
 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 file @code{~/.authinfo} will
 188 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 only has a few functions for external use.
 236
 237 @defun auth-source-search SPEC
 238
 239 TODO: how to include docstring?
 240
 241 @end defun
 242
 243 @defun auth-source-delete SPEC
 244
 245 TODO: how to include docstring?
 246
 247 @end defun
 248
 249 @defun auth-source-forget SPEC
 250
 251 TODO: how to include docstring?
 252
 253 @end defun
 254
 255 @defun auth-source-forget+ SPEC
 256
 257 TODO: how to include docstring?
 258
 259 @end defun
 260
 261 @node GnuPG and EasyPG Assistant Configuration
 262 @appendix GnuPG and EasyPG Assistant Configuration
 263
 264 If you don't customize @code{auth-sources}, the auth-source library
 265 reads @code{~/.authinfo.gpg}, which is a GnuPG encrypted file.  Then
 266 it will check @code{~/.authinfo} but it's not recommended to use such
 267 an unencrypted file.
 268
 269 In Emacs 23 or later there is an option @code{auto-encryption-mode} to
 270 automatically decrypt @code{*.gpg} files.  It is enabled by default.
 271 If you are using earlier versions of Emacs, you will need:
 272
 273 @lisp
 274 (require 'epa-file)
 275 (epa-file-enable)
 276 @end lisp
 277
 278 If you want your GnuPG passwords to be cached, set up @code{gpg-agent}
 279 or EasyPG Assitant
 280 (@pxref{Caching Passphrases, , Caching Passphrases, epa}).
 281
 282 To quick start, here are some questions:
 283
 284 @enumerate
 285 @item
 286 Do you use GnuPG version 2 instead of GnuPG version 1?
 287 @item
 288 Do you use symmetric encryption rather than public key encryption?
 289 @item
 290 Do you want to use gpg-agent?
 291 @end enumerate
 292
 293 Here are configurations depending on your answers:
 294
 295 @multitable {111} {222} {333} {configuration configuration configuration}
 296 @item @b{1} @tab @b{2} @tab @b{3} @tab Configuration
 297 @item Yes @tab Yes @tab Yes @tab Set up gpg-agent.
 298 @item Yes @tab Yes @tab No @tab You can't, without gpg-agent.
 299 @item Yes @tab No @tab Yes @tab Set up gpg-agent.
 300 @item Yes @tab No @tab No @tab You can't, without gpg-agent.
 301 @item No @tab Yes @tab Yes @tab Set up elisp passphrase cache.
 302 @item No @tab Yes @tab No @tab Set up elisp passphrase cache.
 303 @item No @tab No @tab Yes @tab Set up gpg-agent.
 304 @item No @tab No @tab No @tab You can't, without gpg-agent.
 305 @end multitable
 306
 307 To set up gpg-agent, follow the instruction in GnuPG manual
 308 (@pxref{Invoking GPG-AGENT, , Invoking GPG-AGENT, gnupg}).
 309
 310 To set up elisp passphrase cache, set
 311 @code{epa-file-cache-passphrase-for-symmetric-encryption}.
 312
 313 @node Index
 314 @chapter Index
 315 @printindex cp
 316
 317 @node Function Index
 318 @chapter Function Index
 319 @printindex fn
 320
 321 @node Variable Index
 322 @chapter Variable Index
 323 @printindex vr
 324
 325 @bye
 326
 327 @c End: