@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
-The auth-source library is a modern, extensible, enterprise-class
-authentication library. It uses the latest design patterns, has 1800
-unit tests, and has been featured in 21 industry conference keynote
-talks. It's future-proof, mathematically proven to be bug-free, and
-has 6 internal XML parsers just in case you ever need to eat up some
-memory.
-
-Just kidding. The auth-source library is simply a way for Emacs and
-Gnus, among others, to find the answer to the old burning question ``I
-have a server name and a port, what are my user name and password?''
+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 can in
-theory support multiple storage formats, but currently it only
-understands the classic ``netrc'' format, examples of which you can
-see later in this document.
+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
``Netrc'' files are a de facto standard. They look like this:
@example
-machine mymachine login myloginname password mypassword port myport
+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 143 and for protocol ``imap''
-if you fancy that. Anyway, you can just omit the port if you don't
-need it. ``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 @var{auth-source-debug} to 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 @var{auth-sources}. The following may
+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.
+
+``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.
@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, this is already the default, so unless you
-want to move your netrc file, it will just work if you have that
-file. You may not, though, so make sure it exists.
+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 @var{auth-sources} with a particular
+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).
-@end defvar
+Here's an example that uses the Secret Service API for all lookups,
+using the default collection:
-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.
+@lisp
+(setq auth-sources '((:source (:secrets default))))
+@end lisp
+
+And here's a mixed example, using two sources:
@lisp
-(require 'epa-file)
-(epa-file-enable)
-;;; VERY important if you want symmetric encryption
-;;; irrelevant if you don't
-(setq epa-file-cache-passphrase-for-symmetric-encryption t)
+(setq auth-sources '((:source (:secrets default) :host "myserver" :user "joe")
+ (:source "~/.authinfo.gpg")))
@end lisp
+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.
@example
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 @var{auth-source-debug} is t,
-debugging messages will be printed. Set @var{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
+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 (thus you can avoid parsing the netrc
-file 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.
+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