\input texinfo @c -*-texinfo-*-
-@setfilename auth
-@settitle Emacs auth-source Library @value{VERSION}
-@set VERSION 0.2
+@include gnus-overrides.texi
+
+@set VERSION 0.3
+
+@setfilename auth.info
+@settitle Emacs auth-source Library @value{VERSION}
+@include docstyle.texi
@copying
This file describes the Emacs auth-source library.
-Copyright @copyright{} 2008, 2009 Free Software Foundation, Inc.
+Copyright @copyright{} 2008--2016 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,''
+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.
+is included in the section entitled ``GNU Free Documentation License''.
(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.
+modify this GNU manual.''
@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::
-* Help for developers::
-* Index::
-* Function Index::
-* Variable Index::
+* Help for users::
+* Multiple GMail accounts with Gnus::
+* Secret Service API::
+* Help for developers::
+* GnuPG and EasyPG Assistant Configuration::
+* GNU Free Documentation License:: The license for this documentation.
+* Index::
+* Function Index::
+* Variable Index::
@end menu
@end ifnottex
@chapter Overview
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?''
+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).
-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.
+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
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 @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 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 @code{port} is the connection port or protocol. It's known as
+@var{:port} in @code{auth-source-search} queries.
-The login and password are simply your login credentials to the server.
+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}.
+
+You can use spaces inside a password or other token by surrounding the
+token with either single or double quotes.
+
+You can use apostrophes inside a password or other token by
+surrounding it with double quotes, e.g., @code{"he'llo"}. Similarly you
+can use double quotes inside a password or other token by surrounding
+it with apostrophes, e.g., @code{'he"llo'}. You can't mix both (so a
+password or other token can't have both apostrophes and double quotes).
+
+All this is 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
-``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.
+to use the same password everywhere. Again, @emph{DO NOT DO THIS} or
+you will be pwned as the kids say.
-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.
+``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 @file{*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
@defvar auth-sources
The @code{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:
+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 @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 @code{~/.authinfo.gpg}. This is an encrypted file if and only if
-you set up EPA, which is strongly recommended.
+the defaults: the unencrypted netrc file @file{~/.authinfo} will be
+used for any host and any port.
-@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, 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}).
+
+Finally, the unencrypted netrc file @file{~/.netrc} will be used for
+any host and any port.
-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
@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,
+over HTTP@. HTTPS is set up similarly. If you want finer controls,
explore the url-auth source code and variables.
For Tramp authentication, use:
earlier. Since Tramp has about 88 connection methods, this may be
necessary if you have an unusual (see earlier comment on those) setup.
+@node Multiple GMail accounts with Gnus
+@chapter Multiple GMail accounts with Gnus
+
+For multiple GMail accounts with Gnus, you have to make two nnimap
+entries in your @code{gnus-secondary-select-methods} with distinct
+names:
+
+@example
+(setq gnus-secondary-select-methods '((nnimap "gmail"
+ (nnimap-address "imap.gmail.com"))
+ (nnimap "gmail2"
+ (nnimap-address "imap.gmail.com"))))
+@end example
+
+Your netrc entries will then be:
+
+@example
+machine gmail login account@@gmail.com password "account password" port imap
+machine gmail2 login account2@@gmail.com password "account2 password" port imap
+@end example
+
+@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. This
+API is implemented by system daemons such as the GNOME Keyring and the
+KDE Wallet (these are GNOME and KDE packages respectively and should
+be available on most modern GNU/Linux systems).
+
+The auth-source library uses the @file{secrets.el} library to connect
+through the Secret Service API@. You can also use that library in
+other packages, it's not exclusive to auth-source.
+
+@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 shows all collections, items, and their attributes.
+@end deffn
+
+The atomic objects managed by the Secret Service API are @dfn{secret
+items}, which contain things an application wishes to store securely,
+like a password. Secret items have a label (a name), the @dfn{secret}
+(which is the string we want, like a password), and a set of lookup
+attributes. The attributes can be used to search and retrieve a
+secret item at a later date.
+
+Secret items are grouped in @dfn{collections}. A collection is
+sometimes called a @samp{keyring} or @samp{wallet} in GNOME Keyring
+and KDE Wallet but it's the same thing, a group of secrets.
+Collections are personal and protected so only the owner can open them.
+
+The most common collection is called @code{"login"}.
+
+A collection can have an alias. The alias @code{"default"} is
+commonly used so the clients don't have to know the specific name of
+the collection they open. Other aliases are not supported yet.
+Since aliases are globally accessible, set the @code{"default"} alias
+only when you're sure it's appropriate.
+
+@defun secrets-list-collections
+This function returns all the collection names as a list.
+@end defun
+
+@defun secrets-set-alias collection alias
+Set @var{alias} as alias of collection labeled @var{collection}.
+Currently only the alias @code{"default"} is supported.
+@end defun
+
+@defun secrets-get-alias alias
+Return the collection name @var{alias} is referencing to.
+Currently only the alias @code{"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 done from within Emacs. Do not delete standard
+collections such as @code{"login"}.
+
+The special collection @code{"session"} exists for the lifetime of the
+corresponding client session (in our case, 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. The @code{"session"}
+collection is better than a persistent collection when the secret
+items should not live longer than Emacs. The session collection can
+be specified either by the string @code{"session"}, or by @code{nil},
+whenever a collection parameter is needed in the following functions.
+
+@defun secrets-list-items collection
+Returns all the item labels of @var{collection} as a list.
+@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
+;;; The session "session", the label is "my item"
+;;; and the secret (password) is "geheim"
+(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 for the items in @var{collection} with matching
+@var{attributes}. The @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
+
+The auth-source library uses the @file{secrets.el} library and thus
+the Secret Service API when you specify a source matching
+@code{"secrets:COLLECTION"}. For instance, you could use
+@code{"secrets:session"} to use the @code{"session"} collection, open only
+for the lifetime of Emacs. Or you could use @code{"secrets:Login"} to
+open the @code{"Login"} collection. As a special case, you can use the
+symbol @code{default} in @code{auth-sources} (not a string, but a
+symbol) to specify the @code{"default"} alias. Here is a contrived
+example that sets @code{auth-sources} to search three collections and
+then fall back to @file{~/.authinfo.gpg}.
+
+@example
+(setq auth-sources '(default
+ "secrets:session"
+ "secrets:Login"
+ "~/.authinfo.gpg"))
+@end example
+
@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.
+
+@defvar auth-source-debug
+Set this variable to @code{'trivia} to see lots of output in
+@file{*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-user-or-password mode host port
+@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}.
-Retrieve appropriate authentication tokens, determined by @var{mode},
-for host @var{host} and @var{port}. 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.
+@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
-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.
+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.
-@var{host} is a string containing the host name.
+Note that the password needs to be evaluated if it's a function. It's
+wrapped in a function to provide some security.
-@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.
+Later, after a successful login, @code{nnimap.el} calls the
+@code{:save-function} like so:
@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
+(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 the @code{auth-sources} variable contains @file{~/.authinfo.gpg}
+before @file{~/.authinfo}, the auth-source library will try to
+read the GnuPG encrypted @file{.gpg} file first, before
+the 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 GNU Free Documentation License
+@appendix GNU Free Documentation License
+@include doclicense.texi
+
@node Index
-@chapter Index
+@unnumbered Index
@printindex cp
@node Function Index
-@chapter Function Index
+@unnumbered Function Index
@printindex fn
@node Variable Index
-@chapter Variable Index
+@unnumbered Variable Index
@printindex vr
@bye
@c End:
-
-@ignore
- arch-tag: 7b835fd3-473f-40fc-9776-1c4e49d26c94
-@end ignore
projects / gnus / blobdiff