\input texinfo @c -*-texinfo-*-
-@setfilename auth.info
-
-@set VERSION 0.1
+@include gnus-overrides.texi
-@dircategory Emacs
-@direntry
-* auth-source: (auth). The Emacs auth-source library.
-@end direntry
+@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
-@tex
+@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
-@page
-@end tex
+@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::
-* 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
@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 ``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
-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 @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}.
+
+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
+
+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.
-Setup:
+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
+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
-(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
-By adding multiple entries to that list with a particular host or
-protocol, you can have specific netrc files for that host or protocol.
+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: the unencrypted netrc file @file{~/.authinfo} will be
+used for any host and any port.
+
+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 typical netrc line example is 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 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.
-@defun auth-source-user-or-password mode host port
+@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-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
-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.
+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
-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.
+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
-@summarycontents
-@contents
@bye
@c End:
-
-@ignore
- arch-tag: dc9650be-a953-40bf-bc55-24fe5f19d875
-@end ignore
projects / gnus / blobdiff