\input texinfo @c -*-texinfo-*-
+
+@include gnus-overrides.texi
+
@setfilename auth
@settitle Emacs auth-source Library @value{VERSION}
-@set VERSION 0.2
+@set VERSION 0.3
@copying
This file describes the Emacs auth-source library.
-Copyright @copyright{} 2008, 2009 Free Software Foundation, Inc.
+Copyright @copyright{} 2008-2011 Free Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
@end quotation
@end copying
-@dircategory Emacs
+@dircategory Emacs lisp libraries
@direntry
-* Auth-source: (auth). The Emacs auth-source library.
+* Auth-source: (auth). The Emacs auth-source library.
@end direntry
@titlepage
+@ifset WEBHACKDEVEL
+@title Emacs auth-source Library (DEVELOPMENT VERSION)
+@end ifset
+@ifclear WEBHACKDEVEL
@title Emacs auth-source Library
+@end ifclear
@author by Ted Zlatanov
@page
@vskip 0pt plus 1filll
@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.
+The auth-source library is simply a way for Emacs and Gnus, among
+others, to answer the old burning question ``What are my user name and
+password?''
-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?''
+(This is different from the old question about burning ``Where is the
+fire extinguisher, please?''.)
-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.
+The auth-source library supports more than just the user name or the
+password (known as the secret).
+
+Similarly, the auth-source library supports multiple storage backend,
+currently either the classic ``netrc'' backend, examples of which you
+can see later in this document, or the Secret Service API. This is
+done with EIEIO-based backends and you can write your own if you want.
@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 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
+The @code{machine} is the server (either a DNS name or an IP address).
+It's known as @var{:host} in @code{auth-source-search} queries. You
+can also use @code{host}.
+
+The @code{port} is the connection port or protocol. It's known as
+@var{:port} in @code{auth-source-search} queries.
+
+The @code{user} is the user name. It's known as @var{:user} in
+@code{auth-source-search} queries. You can also use @code{login} and
+@code{account}.
+
+Spaces are always OK as far as auth-source is concerned (but other
+programs may not like them). Just put the data in quotes, escaping
+quotes as you'd expect with @code{\}.
+
+All these are optional. You could just say (but we don't recommend
+it, we're just showing that it's possible)
+
+@example
+password @var{mypassword}
+@end example
+
+to use the same password everywhere. Again, @emph{DO NOT DO THIS} or
+you will be pwned as the kids say.
+
+``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 accepting both, as you'll see
+later.
+
+If you have problems with the search, set @code{auth-source-debug} to
+@code{'trivia} and see what host, port, and user 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
-(setq auth-sources '((:source "~/.authinfo.gpg" :host t :protocol t)))
+;;; old default: required :host and :port, not needed anymore
+(setq auth-sources '((:source "~/.authinfo.gpg" :host t :port t)))
+;;; mostly equivalent (see below about fallbacks) but shorter:
+(setq auth-sources '((:source "~/.authinfo.gpg")))
+;;; even shorter and the @emph{default}:
+(setq auth-sources '("~/.authinfo.gpg" "~/.authinfo" "~/.netrc"))
+;;; use the Secrets API @var{Login} collection (@pxref{Secret Service API})
+(setq auth-sources '("secrets:Login"))
@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.
-
-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).
+Here's a mixed example using two sources:
+
+@lisp
+(setq auth-sources '((:source (:secrets default) :host "myserver" :user "joe")
+ "~/.authinfo.gpg"))
+@end lisp
+
@end defvar
-If you don't customize @var{auth-sources}, you'll have to live with
+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}. This is an encrypted file if and only if
-you set up EPA, which is strongly recommended.
+file @code{~/.authinfo.gpg}, which is a GnuPG encrypted file
+(@pxref{GnuPG and EasyPG Assistant Configuration}).
-@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)
-@end lisp
+If that fails, the unencrypted netrc files @code{~/.authinfo} and
+@code{~/.netrc} will be used.
-The simplest working netrc line example is one without a port.
+The typical netrc line example is without a port.
@example
machine YOURMACHINE login YOU password YOURPASSWORD
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.
+The auth-source library lets you control logging output easily.
-@defun auth-source-user-or-password mode host port
+@defvar auth-source-debug
+Set this variable to 'trivia to see lots of output in *Messages*, or
+set it to a function that behaves like @code{message} to do your own
+logging.
+@end defvar
-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
-formatting spec and optional parameters.
+The auth-source library only has a few functions for external use.
-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.
+@defun auth-source-search SPEC
-@var{host} is a string containing the host name.
+TODO: how to include docstring?
-@var{port} contains the protocol name (e.g. ``imap'') or
-a port number. It must be a string, corresponding to the port in the
-users' netrc files.
+@end defun
+
+Let's take a look at an example of using @code{auth-source-search}
+from Gnus' @code{nnimap.el}.
@example
-;; IMAP example
-(setq auth (auth-source-user-or-password
- '("login" "password")
- "anyhostnamehere"
- "imap"))
-(nth 0 auth) ; the login name
-(nth 1 auth) ; the password
+(defun nnimap-credentials (address ports)
+ (let* ((auth-source-creation-prompts
+ '((user . "IMAP user at %h: ")
+ (secret . "IMAP password for %u@@%h: ")))
+ (found (nth 0 (auth-source-search :max 1
+ :host address
+ :port ports
+ :require '(:user :secret)
+ :create t))))
+ (if found
+ (list (plist-get found :user)
+ (let ((secret (plist-get found :secret)))
+ (if (functionp secret)
+ (funcall secret)
+ secret))
+ (plist-get found :save-function))
+ nil)))
@end example
+This call requires the user and password (secret) to be in the
+results. It also requests that an entry be created if it doesn't
+exist already. While the created entry is being assembled, the shown
+prompts will be used to interact with the user. The caller can also
+pass data in @code{auth-source-creation-defaults} to supply defaults
+for any of the prompts.
+
+Note that the password needs to be evaluated if it's a function. It's
+wrapped in a function to provide some security.
+
+Later, after a successful login, @code{nnimal.el} calls the
+@code{:save-function} like so:
+
+@example
+(when (functionp (nth 2 credentials))
+ (funcall (nth 2 credentials)))
+@end example
+
+This will work whether the @code{:save-function} was provided or not.
+@code{:save-function} will be provided only when a new entry was
+created, so this effectively says ``after a successful login, save the
+authentication information we just used, if it was newly created.''
+
+After the first time it's called, the @code{:save-function} will not
+run again (but it will log something if you have set
+@code{auth-source-debug} to @code{'trivia}). This is so it won't ask
+the same question again, which is annoying. This is so it won't ask
+the same question again, which is annoying. This is so it won't ask
+the same question again, which is annoying.
+
+So the responsibility of the API user that specified @code{:create t}
+is to call the @code{:save-function} if it's provided.
+
+@defun auth-source-delete SPEC
+
+TODO: how to include docstring?
+
+@end defun
+
+@defun auth-source-forget SPEC
+
+TODO: how to include docstring?
+
@end defun
+@defun auth-source-forget+ SPEC
+
+TODO: how to include docstring?
+
+@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. Then
+it will check @code{~/.authinfo} but it's not recommended to use such
+an unencrypted 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