cgit.sxemacs.org Git - gnus/blob - texi/auth.texi

   1 \input texinfo                  @c -*-texinfo-*-
   2
   3 @include gnus-overrides.texi
   4
   5 @setfilename 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
  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.  You can also use
 109 @code{protocol}.
 110
 111 The @code{user} is the user name.  It's known as @var{:user} in
 112 @code{auth-source-search} queries.  You can also use @code{login} and
 113 @code{account}.
 114
 115 Spaces are always OK as far as auth-source is concerned (but other
 116 programs may not like them).  Just put the data in quotes, escaping
 117 quotes as you'd expect with @code{\}.
 118
 119 All these are optional.  You could just say (but we don't recommend
 120 it, we're just showing that it's possible)
 121
 122 @example
 123 password @var{mypassword}
 124 @end example
 125
 126 to use the same password everywhere.  Again, @emph{DO NOT DO THIS} or
 127 you will be pwned as the kids say.
 128
 129 ``Netrc'' files are usually called @code{.authinfo} or @code{.netrc};
 130 nowadays @code{.authinfo} seems to be more popular and the auth-source
 131 library encourages this confusion by making it the default, as you'll
 132 see later.
 133
 134 If you have problems with the search, set @code{auth-source-debug} to
 135 @code{t} and see what host, port, and user the library is checking in
 136 the @code{*Messages*} buffer.  Ditto for any other problems, your
 137 first step is always to see what's being checked.  The second step, of
 138 course, is to write a blog entry about it and wait for the answer in
 139 the comments.
 140
 141 You can customize the variable @code{auth-sources}.  The following may
 142 be needed if you are using an older version of Emacs or if the
 143 auth-source library is not loaded for some other reason.
 144
 145 @lisp
 146 (require 'auth-source)             ;; probably not necessary
 147 (customize-variable 'auth-sources) ;; optional, do it once
 148 @end lisp
 149
 150 @defvar auth-sources
 151
 152 The @code{auth-sources} variable tells the auth-source library where
 153 your netrc files or Secret Service API collection items live for a
 154 particular host and protocol.  While you can get fancy, the default
 155 and simplest configuration is:
 156
 157 @lisp
 158 ;;; old default: required :host and :protocol, not needed anymore
 159 (setq auth-sources '((:source "~/.authinfo.gpg" :host t :protocol t)))
 160 ;;; mostly equivalent (see below about fallbacks) but shorter:
 161 (setq auth-sources '((:source "~/.authinfo.gpg")))
 162 ;;; even shorter and the @emph{default}:
 163 (setq auth-sources '("~/.authinfo.gpg" "~/.authinfo"))
 164 ;;; use the Secrets API @var{Login} collection (@pxref{Secret Service API})
 165 (setq auth-sources '("secrets:Login"))
 166 @end lisp
 167
 168 By adding multiple entries to @code{auth-sources} with a particular
 169 host or protocol, you can have specific netrc files for that host or
 170 protocol.  Usually this is unnecessary but may make sense if you have
 171 shared netrc files or some other unusual setup (90% of Emacs users
 172 have unusual setups and the remaining 10% are @emph{really} unusual).
 173
 174 Here's a mixed example using two sources:
 175
 176 @lisp
 177 (setq auth-sources '((:source (:secrets default) :host "myserver" :user "joe")
 178                      "~/.authinfo.gpg"))
 179 @end lisp
 180
 181 @end defvar
 182
 183 If you don't customize @code{auth-sources}, you'll have to live with
 184 the defaults: any host and any port are looked up in the netrc
 185 file @code{~/.authinfo.gpg}, which is a GnuPG encrypted file
 186 (@pxref{GnuPG and EasyPG Assistant Configuration}).
 187
 188 If that fails, the unencrypted netrc file @code{~/.authinfo} will
 189 be used.
 190
 191 The typical netrc line example is without a port.
 192
 193 @example
 194 machine YOURMACHINE login YOU password YOURPASSWORD
 195 @end example
 196
 197 This will match any authentication port.  Simple, right?  But what if
 198 there's a SMTP server on port 433 of that machine that needs a
 199 different password from the IMAP server?
 200
 201 @example
 202 machine YOURMACHINE login YOU password SMTPPASSWORD port 433
 203 machine YOURMACHINE login YOU password GENERALPASSWORD
 204 @end example
 205
 206 For url-auth authentication (HTTP/HTTPS), you need to put this in your
 207 netrc file:
 208
 209 @example
 210 machine yourmachine.com:80 port http login testuser password testpass
 211 @end example
 212
 213 This will match any realm and authentication method (basic or digest)
 214 over HTTP.  HTTPS is set up similarly.  If you want finer controls,
 215 explore the url-auth source code and variables.
 216
 217 For Tramp authentication, use:
 218
 219 @example
 220 machine yourmachine.com port scp login testuser password testpass
 221 @end example
 222
 223 Note that the port denotes the Tramp connection method.  When you
 224 don't use a port entry, you match any Tramp method, as explained
 225 earlier.  Since Tramp has about 88 connection methods, this may be
 226 necessary if you have an unusual (see earlier comment on those) setup.
 227
 228 @node Secret Service API
 229 @chapter Secret Service API
 230
 231 TODO: how does it work generally, how does secrets.el work, some examples.
 232
 233 @node Help for developers
 234 @chapter Help for developers
 235
 236 The auth-source library only has a few functions for external use.
 237
 238 @defun auth-source-search SPEC
 239
 240 TODO: how to include docstring?
 241
 242 @end defun
 243
 244 @defun auth-source-delete SPEC
 245
 246 TODO: how to include docstring?
 247
 248 @end defun
 249
 250 @defun auth-source-forget SPEC
 251
 252 TODO: how to include docstring?
 253
 254 @end defun
 255
 256 @defun auth-source-forget+ SPEC
 257
 258 TODO: how to include docstring?
 259
 260 @end defun
 261
 262 @node GnuPG and EasyPG Assistant Configuration
 263 @appendix GnuPG and EasyPG Assistant Configuration
 264
 265 If you don't customize @code{auth-sources}, the auth-source library
 266 reads @code{~/.authinfo.gpg}, which is a GnuPG encrypted file.
 267
 268 In Emacs 23 or later there is an option @code{auto-encryption-mode} to
 269 automatically decrypt @code{*.gpg} files.  It is enabled by default.
 270 If you are using earlier versions of Emacs, you will need:
 271
 272 @lisp
 273 (require 'epa-file)
 274 (epa-file-enable)
 275 @end lisp
 276
 277 If you want your GnuPG passwords to be cached, set up @code{gpg-agent}
 278 or EasyPG Assitant
 279 (@pxref{Caching Passphrases, , Caching Passphrases, epa}).
 280
 281 To quick start, here are some questions:
 282
 283 @enumerate
 284 @item
 285 Do you use GnuPG version 2 instead of GnuPG version 1?
 286 @item
 287 Do you use symmetric encryption rather than public key encryption?
 288 @item
 289 Do you want to use gpg-agent?
 290 @end enumerate
 291
 292 Here are configurations depending on your answers:
 293
 294 @multitable {111} {222} {333} {configuration configuration configuration}
 295 @item @b{1} @tab @b{2} @tab @b{3} @tab Configuration
 296 @item Yes @tab Yes @tab Yes @tab Set up gpg-agent.
 297 @item Yes @tab Yes @tab No @tab You can't, without gpg-agent.
 298 @item Yes @tab No @tab Yes @tab Set up gpg-agent.
 299 @item Yes @tab No @tab No @tab You can't, without gpg-agent.
 300 @item No @tab Yes @tab Yes @tab Set up elisp passphrase cache.
 301 @item No @tab Yes @tab No @tab Set up elisp passphrase cache.
 302 @item No @tab No @tab Yes @tab Set up gpg-agent.
 303 @item No @tab No @tab No @tab You can't, without gpg-agent.
 304 @end multitable
 305
 306 To set up gpg-agent, follow the instruction in GnuPG manual
 307 (@pxref{Invoking GPG-AGENT, , Invoking GPG-AGENT, gnupg}).
 308
 309 To set up elisp passphrase cache, set
 310 @code{epa-file-cache-passphrase-for-symmetric-encryption}.
 311
 312 @node Index
 313 @chapter Index
 314 @printindex cp
 315
 316 @node Function Index
 317 @chapter Function Index
 318 @printindex fn
 319
 320 @node Variable Index
 321 @chapter Variable Index
 322 @printindex vr
 323
 324 @bye
 325
 326 @c End: