@include gnus-overrides.texi
+@set VERSION 0.3
+
@setfilename auth
@settitle Emacs auth-source Library @value{VERSION}
-
-@set VERSION 0.3
+@documentencoding UTF-8
@copying
This file describes the Emacs auth-source library.
-Copyright @copyright{} 2008-2012 Free Software Foundation, Inc.
+Copyright @copyright{} 2008--2014 Free Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
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.
+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
* 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::
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
+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
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
+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.
(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})
+;;; use the Secrets API @var{Login} collection
+;;; (@pxref{Secret Service API})
(setq auth-sources '("secrets:Login"))
@end lisp
Here's a mixed example using two sources:
@lisp
-(setq auth-sources '((:source (:secrets default) :host "myserver" :user "joe")
+(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}).
+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}).
-If that fails, the unencrypted netrc files @file{~/.authinfo} and
-@file{~/.netrc} will be used.
+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.
@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:
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.
+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 as an
-interface to this feature. You can also use that library in other
-packages.
+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
@end defvar
@deffn Command secrets-show-secrets
-This command inspects all collections, items, and their attributes.
+This command shows 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.
+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
-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.
+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 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.
+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 a list of collection names.
+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}.
-For the time being, only the alias @samp{"default"} is supported.
+Currently only the alias @code{"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.
+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 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.
+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 a list of all item labels of @var{collection}.
+Returns all the item labels of @var{collection} as a list.
@end defun
@defun secrets-create-item collection item password &rest attributes
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
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.
+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
@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:
+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")
@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
@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
+@file{*Messages*}, or set it to a function that behaves like
@code{message} to do your own logging.
@end defvar
@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.
+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.
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
projects / gnus / blobdiff