@setfilename auth
@settitle Emacs auth-source Library @value{VERSION}
-@set VERSION 0.1
+@set VERSION 0.2
@copying
This file describes the Emacs auth-source library.
-Copyright @copyright{} 2008, 2009 Free Software Foundation, Inc.
+Copyright @copyright{} 2008, 2009, 2010 Free Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
@dircategory Emacs
@direntry
-* Auth-source: (auth). The Emacs auth-source library.
+* Auth-source: (auth). The Emacs auth-source library.
@end direntry
@titlepage
@menu
* Overview:: Overview of the auth-source library.
* Help for users::
+* Secret Service API::
* Help for developers::
+* GnuPG and EasyPG Assistant Configuration::
* Index::
* Function Index::
* Variable Index::
@node Overview
@chapter Overview
-To be done.
+The auth-source library is simply a way for Emacs and Gnus, among
+others, to answer the old burning question ``I have a server name and
+a port, what are my user name and password?''
+
+The auth-source library actually supports more than just the user name
+(known as the login) or the password, but only those two are in use
+today in Emacs or Gnus. Similarly, the auth-source library supports
+multiple storage formats, currently either the classic ``netrc''
+format, examples of which you can see later in this document, or the
+Secret Service API.
@node Help for users
@chapter Help for users
-If you have problems with the port, turn up @code{gnus-verbose} and
-see what port the library is checking. Ditto for any other
-problems, your first step is to see what's being checked.
+``Netrc'' files are a de facto standard. They look like this:
+@example
+machine @var{mymachine} login @var{myloginname} password @var{mypassword} port @var{myport}
+@end example
+
+The machine is the server (either a DNS name or an IP address).
+
+The port is optional. If it's missing, auth-source will assume any
+port is OK. Actually the port is a protocol name or a port number so
+you can have separate entries for port @var{143} and for protocol
+@var{imap} if you fancy that. Anyway, you can just omit the port if
+you don't need it.
+
+The login and password are simply your login credentials to the server.
-Setup:
+``Netrc'' files are usually called @code{.authinfo} or @code{.netrc};
+nowadays @code{.authinfo} seems to be more popular and the auth-source
+library encourages this confusion by making it the default, as you'll
+see later.
+
+If you have problems with the port, set @code{auth-source-debug} to
+@code{t} and see what port the library is checking in the
+@code{*Messages*} buffer. Ditto for any other problems, your first
+step is always to see what's being checked. The second step, of
+course, is to write a blog entry about it and wait for the answer in
+the comments.
+
+You can customize the variable @code{auth-sources}. The following may
+be needed if you are using an older version of Emacs or if the
+auth-source library is not loaded for some other reason.
@lisp
-(require 'auth-source)
+(require 'auth-source) ;; probably not necessary
(customize-variable 'auth-sources) ;; optional, do it once
@end lisp
@defvar auth-sources
-The @var{auth-sources} variable tells the auth-source library where
-your netrc files live for a particular host and protocol. While you
-can get fancy, the default and simplest configuration is:
+The @code{auth-sources} variable tells the auth-source library where
+your netrc files or Secret Service API collection items live for a
+particular host and protocol. While you can get fancy, the default
+and simplest configuration is:
@lisp
+;;; old default: required :host and :protocol, not needed anymore
(setq auth-sources '((:source "~/.authinfo.gpg" :host t :protocol t)))
+;;; mostly equivalent (see below about fallbacks) but shorter:
+(setq auth-sources '((:source "~/.authinfo.gpg")))
+@end lisp
+
+This says ``for any host and any protocol, use just that one file.''
+Sweet simplicity. In fact, the latter is already the default, so
+unless you want to move your netrc file, it will just work if you have
+that file. Make sure it exists.
+
+By adding multiple entries to @code{auth-sources} with a particular
+host or protocol, you can have specific netrc files for that host or
+protocol. Usually this is unnecessary but may make sense if you have
+shared netrc files or some other unusual setup (90% of Emacs users
+have unusual setups and the remaining 10% are @emph{really} unusual).
+
+Here's an example that uses the Secret Service API for all lookups,
+using the default collection:
+
+@lisp
+(setq auth-sources '((:source (:secrets default))))
+@end lisp
+
+And here's a mixed example, using two sources:
+
+@lisp
+(setq auth-sources '((:source (:secrets default) :host "myserver" :user "joe")
+ (:source "~/.authinfo.gpg")))
@end lisp
-By adding multiple entries to that list with a particular host or
-protocol, you can have specific netrc files for that host or protocol.
+The best match is determined by order (starts from the bottom) only
+for the first pass, where things are checked exactly. In the example
+above, the first pass would find a single match for host
+@code{myserver}. The netrc choice would fail because it matches any
+host and protocol implicitly (as a @emph{fallback}). A specified
+value of @code{:host t} in @code{auth-sources} is considered a match
+on the first pass, unlike a missing @code{:host}.
+
+Now if you look for host @code{missing}, it won't match either source
+explicitly. The second pass (the @emph{fallback} pass) will look at
+all the implicit matches and collect them. They will be scored and
+returned sorted by score. The score is based on the number of
+explicit parameters that matched. See the @code{auth-pick} function
+for details.
@end defvar
+If you don't customize @code{auth-sources}, you'll have to live with
+the defaults: any host and any port are looked up in the netrc
+file @code{~/.authinfo.gpg}, which is a GnuPG encrypted file
+(@pxref{GnuPG and EasyPG Assistant Configuration}).
+
+The simplest working netrc line example is one without a port.
-``Netrc'' files are a de facto standard. They look like this:
@example
-machine mymachine login myloginname password mypassword port myport
+machine YOURMACHINE login YOU password YOURPASSWORD
@end example
-The port is optional. If it's missing, auth-source will assume any
-port is OK. Actually the port is a protocol name or a port number so
-you can have separate entries for port 143 and for protocol ``imap''
-if you fancy that.
-
-If you don't customize @var{auth-sources}, you'll have to live with
-the defaults: any host and any port are looked up in the netrc
-file @code{~/.authinfo.gpg}. This is an encrypted file if and only if
-you set up EPA, which is strongly recommended.
+This will match any authentication port. Simple, right? But what if
+there's a SMTP server on port 433 of that machine that needs a
+different password from the IMAP server?
-@lisp
-(require 'epa-file)
-(epa-file-enable)
-(setq epa-file-cache-passphrase-for-symmetric-encryption t) ; VERY important
-@end lisp
+@example
+machine YOURMACHINE login YOU password SMTPPASSWORD port 433
+machine YOURMACHINE login YOU password GENERALPASSWORD
+@end example
For url-auth authentication (HTTP/HTTPS), you need to put this in your
netrc file:
machine yourmachine.com:80 port http login testuser password testpass
@end example
-This will match any realm and authentication method (basic or
-digest). If you want finer controls, explore the url-auth source
-code and variables.
+This will match any realm and authentication method (basic or digest)
+over HTTP. HTTPS is set up similarly. If you want finer controls,
+explore the url-auth source code and variables.
For Tramp authentication, use:
Note that the port denotes the Tramp connection method. When you
don't use a port entry, you match any Tramp method, as explained
-earlier.
+earlier. Since Tramp has about 88 connection methods, this may be
+necessary if you have an unusual (see earlier comment on those) setup.
+
+@node Secret Service API
+@chapter Secret Service API
+
+TODO: how does it work generally, how does secrets.el work, some examples.
@node Help for developers
@chapter Help for developers
The auth-source library only has one function for external use.
-@defun auth-source-user-or-password mode host port
+@defun auth-source-user-or-password mode host port &optional username
Retrieve appropriate authentication tokens, determined by @var{mode},
-for host @var{host} and @var{port}. If @code{gnus-verbose} is 9 or
-higher, debugging messages will be printed.
+for host @var{host} and @var{port}. If @var{username} is provided it
+will also be checked. If @code{auth-source-debug} is t, debugging
+messages will be printed. Set @code{auth-source-debug} to a function
+to use that function for logging. The parameters passed will be the
+same that the @code{message} function takes, that is, a string
+formatting spec and optional parameters.
If @var{mode} is a list of strings, the function will return a list of
-strings or @code{nil} objects. If it's a string, the function will
-return a string or a @code{nil} object. Currently only the modes
-``login'' and ``password'' are recognized but more may be added in the
-future.
+strings or @code{nil} objects (thus you can avoid parsing the netrc
+file or checking the Secret Service API more than once). If it's a
+string, the function will return a string or a @code{nil} object.
+Currently only the modes ``login'' and ``password'' are recognized but
+more may be added in the future.
@var{host} is a string containing the host name.
a port number. It must be a string, corresponding to the port in the
users' netrc files.
+@var{username} contains the user name (e.g. ``joe'') as a string.
+
@example
;; IMAP example
(setq auth (auth-source-user-or-password
@end defun
+@node GnuPG and EasyPG Assistant Configuration
+@appendix GnuPG and EasyPG Assistant Configuration
+
+If you don't customize @code{auth-sources}, the auth-source library
+reads @code{~/.authinfo.gpg}, which is a GnuPG encrypted file.
+
+In Emacs 23 or later there is an option @code{auto-encryption-mode} to
+automatically decrypt @code{*.gpg} files. It is enabled by default.
+If you are using earlier versions of Emacs, you will need:
+
+@lisp
+(require 'epa-file)
+(epa-file-enable)
+@end lisp
+
+If you want your GnuPG passwords to be cached, set up @code{gpg-agent}
+or EasyPG Assitant
+(@pxref{Caching Passphrases, , Caching Passphrases, epa}).
+
+To quick start, here are some questions:
+
+@enumerate
+@item
+Do you use GnuPG version 2 instead of GnuPG version 1?
+@item
+Do you use symmetric encryption rather than public key encryption?
+@item
+Do you want to use gpg-agent?
+@end enumerate
+
+Here are configurations depending on your answers:
+
+@multitable {111} {222} {333} {configuration configuration configuration}
+@item @b{1} @tab @b{2} @tab @b{3} @tab Configuration
+@item Yes @tab Yes @tab Yes @tab Set up gpg-agent.
+@item Yes @tab Yes @tab No @tab You can't, without gpg-agent.
+@item Yes @tab No @tab Yes @tab Set up gpg-agent.
+@item Yes @tab No @tab No @tab You can't, without gpg-agent.
+@item No @tab Yes @tab Yes @tab Set up elisp passphrase cache.
+@item No @tab Yes @tab No @tab Set up elisp passphrase cache.
+@item No @tab No @tab Yes @tab Set up gpg-agent.
+@item No @tab No @tab No @tab You can't, without gpg-agent.
+@end multitable
+
+To set up gpg-agent, follow the instruction in GnuPG manual
+(@pxref{Invoking GPG-AGENT, , Invoking GPG-AGENT, gnupg}).
+
+To set up elisp passphrase cache, set
+@code{epa-file-cache-passphrase-for-symmetric-encryption}.
+
@node Index
@chapter Index
@printindex cp
@bye
@c End:
-
-@ignore
- arch-tag: 7b835fd3-473f-40fc-9776-1c4e49d26c94
-@end ignore
projects / gnus / blobdiff