mirror of
https://git.savannah.gnu.org/git/emacs.git
synced 2024-12-14 09:39:42 +00:00
537 lines
19 KiB
Plaintext
537 lines
19 KiB
Plaintext
\input texinfo @c -*-texinfo-*-
|
|
|
|
@include gnus-overrides.texi
|
|
|
|
@setfilename ../../info/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. 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 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:
|