doc/misc/auth.texi

   1 \input texinfo                  @c -*-texinfo-*-
   2 @setfilename ../../info/auth
   3 @settitle Emacs auth-source Library @value{VERSION}
   4
   5 @set VERSION 0.2
   6
   7 @copying
   8 This file describes the Emacs auth-source library.
   9
  10 Copyright @copyright{} 2008, 2009, 2010, 2011 Free Software Foundation, Inc.
  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
  32 @dircategory Emacs
  33 @direntry
  34 * Auth-source: (auth).          The Emacs auth-source library.
  35 @end direntry
  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
  45 @contents
  46
  47 @ifnottex
  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
  55 @insertcopying
  56
  57 @menu
  58 * Overview::                    Overview of the auth-source library.
  59 * Help for users::
  60 * Help for developers::
  61 * Index::
  62 * Function Index::
  63 * Variable Index::
  64 @end menu
  65 @end ifnottex
  66
  67 @node Overview
  68 @chapter Overview
  69
  70 The auth-source library is simply a way for Emacs and Gnus, among
  71 others, to find the answer to the old burning question ``I have a
  72 server name and a port, what are my user name and password?''
  73
  74 The auth-source library actually supports more than just the user name
  75 (known as the login) or the password, but only those two are in use
  76 today in Emacs or Gnus.  Similarly, the auth-source library can in
  77 theory support multiple storage formats, but currently it only
  78 understands the classic ``netrc'' format, examples of which you can
  79 see later in this document.
  80
  81 @node Help for users
  82 @chapter Help for users
  83
  84 ``Netrc'' files are a de facto standard.  They look like this:
  85 @example
  86 machine @var{mymachine} login @var{myloginname} password @var{mypassword} port @var{myport}
  87 @end example
  88
  89 The machine is the server (either a DNS name or an IP address).
  90
  91 The port is optional.  If it's missing, auth-source will assume any
  92 port is OK.  Actually the port is a protocol name or a port number so
  93 you can have separate entries for port @var{143} and for protocol
  94 @var{imap} if you fancy that.  Anyway, you can just omit the port if
  95 you don't need it.
  96
  97 The login and password are simply your login credentials to the server.
  98
  99 ``Netrc'' files are usually called @code{.authinfo} or @code{.netrc};
 100 nowadays @code{.authinfo} seems to be more popular and the auth-source
 101 library encourages this confusion by making it the default, as you'll
 102 see later.
 103
 104 If you have problems with the port, set @code{auth-source-debug} to
 105 @code{t} and see what port the library is checking in the
 106 @code{*Messages*} buffer.  Ditto for any other problems, your first
 107 step is always to see what's being checked.  The second step, of
 108 course, is to write a blog entry about it and wait for the answer in
 109 the comments.
 110
 111 You can customize the variable @code{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.
 114
 115 @lisp
 116 (require 'auth-source)             ;; probably not necessary
 117 (customize-variable 'auth-sources) ;; optional, do it once
 118 @end lisp
 119
 120 @defvar auth-sources
 121
 122 The @code{auth-sources} variable tells the auth-source library where
 123 your netrc files live for a particular host and protocol.  While you
 124 can get fancy, the default and simplest configuration is:
 125
 126 @lisp
 127 (setq auth-sources '((:source "~/.authinfo.gpg" :host t :protocol t)))
 128 @end lisp
 129
 130 This says ``for any host and any protocol, use just that one file.''
 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 @code{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).
 140
 141 @end defvar
 142
 143 If you don't customize @code{auth-sources}, you'll have to live with
 144 the defaults: any host and any port are looked up in the netrc
 145 file @code{~/.authinfo.gpg}.  This is an encrypted file if and only if
 146 you set up EPA, which is strongly recommended.
 147
 148 @lisp
 149 (require 'epa-file)
 150 (epa-file-enable)
 151 ;;; VERY important if you want symmetric encryption
 152 ;;; irrelevant if you don't
 153 (setq epa-file-cache-passphrase-for-symmetric-encryption t)
 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
 170
 171 For url-auth authentication (HTTP/HTTPS), you need to put this in your
 172 netrc file:
 173
 174 @example
 175 machine yourmachine.com:80 port http login testuser password testpass
 176 @end example
 177
 178 This will match any realm and authentication method (basic or digest)
 179 over HTTP.  HTTPS is set up similarly.  If you want finer controls,
 180 explore the url-auth source code and variables.
 181
 182 For Tramp authentication, use:
 183
 184 @example
 185 machine yourmachine.com port scp login testuser password testpass
 186 @end example
 187
 188 Note that the port denotes the Tramp connection method.  When you
 189 don't use a port entry, you match any Tramp method, as explained
 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.
 192
 193 @node Help for developers
 194 @chapter Help for developers
 195
 196 The auth-source library only has one function for external use.
 197
 198 @defun auth-source-user-or-password mode host port
 199
 200 Retrieve appropriate authentication tokens, determined by @var{mode},
 201 for host @var{host} and @var{port}.  If @code{auth-source-debug} is t,
 202 debugging messages will be printed.  Set @code{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.
 206
 207 If @var{mode} is a list of strings, the function will return a list of
 208 strings or @code{nil} objects (thus you can avoid parsing the netrc
 209 file more than once).  If it's a string, the function will return a
 210 string or a @code{nil} object.  Currently only the modes ``login'' and
 211 ``password'' are recognized but more may be added in the future.
 212
 213 @var{host} is a string containing the host name.
 214
 215 @var{port} contains the protocol name (e.g. ``imap'') or
 216 a port number.  It must be a string, corresponding to the port in the
 217 users' netrc files.
 218
 219 @example
 220 ;; IMAP example
 221 (setq auth (auth-source-user-or-password
 222             '("login" "password")
 223             "anyhostnamehere"
 224             "imap"))
 225 (nth 0 auth) ; the login name
 226 (nth 1 auth) ; the password
 227 @end example
 228
 229 @end defun
 230
 231 @node Index
 232 @chapter Index
 233 @printindex cp
 234
 235 @node Function Index
 236 @chapter Function Index
 237 @printindex fn
 238
 239 @node Variable Index
 240 @chapter Variable Index
 241 @printindex vr
 242
 243 @bye
 244
 245 @c End:
 246
 247 @ignore
 248    arch-tag: 7b835fd3-473f-40fc-9776-1c4e49d26c94
 249 @end ignore