auth.texi: Merge changes made in Emacs trunk

[gnus] / texi / auth.texi

\input texinfo                  @c -*-texinfo-*-

@include gnus-overrides.texi

@setfilename auth
@settitle Emacs auth-source Library @value{VERSION}

@set VERSION 0.3

@copying
This file describes the Emacs auth-source library.

Copyright @copyright{} 2008-2012 Free Software Foundation, Inc.

@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with the Front-Cover texts being ``A GNU Manual,''
and with the Back-Cover Texts as in (a) below.  A copy of the license
is included in the section entitled ``GNU Free Documentation License''
in the Emacs manual.

(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
modify this GNU manual.  Buying copies from the FSF supports it in
developing GNU and promoting software freedom.''

This document is part of a collection distributed under the GNU Free
Documentation License.  If you want to distribute this document
separately from the collection, you can do so by adding a copy of the
license to the document, as described in section 6 of the license.
@end quotation
@end copying

@dircategory Emacs lisp libraries
@direntry
* 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
@insertcopying
@end titlepage

@contents

@ifnottex
@node Top
@top Emacs auth-source
This manual describes the Emacs auth-source library.

It is a way for multiple applications to share a single configuration
(in Emacs and in files) for user convenience.

@insertcopying

@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::
@end menu
@end ifnottex

@node Overview
@chapter Overview

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?''

(This is different from the old question about burning ``Where is the
fire extinguisher, please?''.)

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 @var{mymachine} login @var{myloginname} password @var{mypassword} port @var{myport}
@end example

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 @samp{\}.

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 @file{.authinfo} or @file{.netrc};
nowadays @file{.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 @samp{*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)             ;; probably not necessary
(customize-variable 'auth-sources) ;; optional, do it once
@end lisp

@defvar auth-sources

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 :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

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 @code{auth-sources}, you'll have to live with
the defaults: any host and any port are looked up in the netrc
file @file{~/.authinfo.gpg}, which is a GnuPG encrypted file
(@pxref{GnuPG and EasyPG Assistant Configuration}).

If that fails, the unencrypted netrc files @file{~/.authinfo} and
@file{~/.netrc} will be used.

The typical netrc line example is without a port.

@example
machine YOURMACHINE login YOU password YOURPASSWORD
@end example

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?

@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:

@example
machine yourmachine.com:80 port http login testuser password testpass
@end example

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:

@example
machine yourmachine.com port scp login testuser password testpass
@end example

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.  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

The @dfn{Secret Service API} is a standard from
@uref{http://www.freedesktop.org/wiki/Specifications/secret-storage-spec,,freedesktop.org}
to securely store passwords and other confidential information.
Implementations of compliant daemons are the GNOME Keyring and the KDE
Wallet.

The auth-source library uses the @file{secrets.el} library as an
interface to this feature.  You can also use that library in other
packages.

@defvar secrets-enabled
After loading @file{secrets.el}, a non-@code{nil} value of this
variable indicates the existence of a daemon providing the Secret
Service API.
@end defvar

@deffn Command secrets-show-secrets
This command inspects all collections, items, and their attributes.
@end deffn

The atomic objects to be managed by the Secret Service API are
@dfn{secret items}, which are something an application wishes to store
securely.  A good example is a password that an application needs to
save and use at a later date.

Secret items are grouped in @dfn{collections}.  A collection is
similar in concept to the terms @samp{keyring} or @samp{wallet}.  A
common collection is called @samp{"login"}.  A collection is stored
permanently under the user's permissions, and can be accessed in a
user session context.

A collection can have an alias name.  The use case for this is to
set the alias @samp{"default"} for a given collection, making it
transparent to clients as to which collection is used.  Other aliases
are not supported (yet).  Since an alias is visible to all
applications, this setting should be performed with care.

@defun secrets-list-collections
This function returns a list of collection names.
@end defun

@defun secrets-set-alias collection alias
Set @var{alias} as alias of collection labeled @var{collection}.
For the time being, only the alias @samp{"default"} is supported.
@end defun

@defun secrets-get-alias alias
Return the collection name @var{alias} is referencing to.
For the time being, only the alias @samp{"default"} is supported.
@end defun

Collections can be created and deleted by the functions
@code{secrets-create-collection} and @code{secrets-delete-collection}.
Usually, this is not applied from within Emacs.  Common collections,
like @samp{"login"}, should never be deleted.

There exists a special collection called @samp{"session"}, which has
the lifetime of the corresponding client session (aka Emacs's
lifetime).  It is created automatically when Emacs uses the Secret
Service interface, and it is deleted when Emacs is killed.  Therefore,
it can be used to store and retrieve secret items temporarily.  This
should be preferred over creation of a persistent collection, when the
information should not live longer than Emacs.  The session collection
can be addressed either by the string @samp{"session"}, or by
@code{nil}, whenever a collection parameter is needed in the following
functions.

As already said, a collection is a group of secret items.  A secret
item has a label, the @dfn{secret} (which is a string), and a set of
lookup attributes.  The attributes can be used to search and retrieve
a secret item at a later date.

@defun secrets-list-items collection
Returns a list of all item labels of @var{collection}.
@end defun

@defun secrets-create-item collection item password &rest attributes
This function creates a new item in @var{collection} with label
@var{item} and password @var{password}.  @var{attributes} are
key-value pairs set for the created item.  The keys are keyword
symbols, starting with a colon.  Example:

@example
(secrets-create-item "session" "my item" "geheim"
 :method "sudo" :user "joe" :host "remote-host")
@end example
@end defun

@defun secrets-get-secret collection item
Return the secret of item labeled @var{item} in @var{collection}.
If there is no such item, return @code{nil}.
@end defun

@defun secrets-delete-item collection item
This function deletes item @var{item} in @var{collection}.
@end defun

The lookup attributes, which are specified during creation of a
secret item, must be a key-value pair.  Keys are keyword symbols,
starting with a colon; values are strings.  They can be retrieved
from a given secret item, and they can be used for searching of items.

@defun secrets-get-attribute collection item attribute
Returns the value of key @var{attribute} of item labeled @var{item} in
@var{collection}.  If there is no such item, or the item doesn't own
this key, the function returns @code{nil}.
@end defun

@defun secrets-get-attributes collection item
Return the lookup attributes of item labeled @var{item} in
@var{collection}.  If there is no such item, or the item has no
attributes, it returns @code{nil}.  Example:

@example
(secrets-get-attributes "session" "my item")
     @result{} ((:user . "joe") (:host ."remote-host"))
@end example
@end defun

@defun secrets-search-items collection &rest attributes
Search items in @var{collection} with @var{attributes}.
@var{attributes} are key-value pairs, as used in
@code{secrets-create-item}.  Example:

@example
(secrets-search-items "session" :user "joe")
     @result{} ("my item" "another item")
@end example
@end defun

@node Help for developers
@chapter Help for developers

The auth-source library lets you control logging output easily.

@defvar auth-source-debug
Set this variable to @code{'trivia} to see lots of output in
@samp{*Messages*}, or set it to a function that behaves like
@code{message} to do your own logging.
@end defvar

The auth-source library only has a few functions for external use.

@defun auth-source-search &rest spec &key type max host user port secret require create delete &allow-other-keys
This function searches (or modifies) authentication backends according
to @var{spec}.  See the function's doc-string for details.
@c TODO more details.
@end defun

Let's take a look at an example of using @code{auth-source-search}
from Gnus's @code{nnimap.el}.

@example
(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{nnimap.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 &rest spec &key delete &allow-other-keys
This function deletes entries matching @var{spec} from the
authentication backends.  It returns the entries that were deleted.
The backend may not actually delete the entries.
@end defun

@defun auth-source-forget spec
This function forgets any cached data that exactly matches @var{spec}.
It returns @code{t} if it forget some data, and @code{nil} if no
matching data was found.
@end defun

@defun auth-source-forget+ &rest spec &allow-other-keys
This function forgets any cached data matching @var{spec}.
It returns the number of items forgotten.
@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 @file{~/.authinfo.gpg}, which is a GnuPG encrypted file.  Then
it will check @file{~/.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 @file{*.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 Assistant
(@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

@node Function Index
@chapter Function Index
@printindex fn

@node Variable Index
@chapter Variable Index
@printindex vr

@bye

@c End: