X-Git-Url: http://cgit.sxemacs.org/?p=gnus;a=blobdiff_plain;f=texi%2Fauth.texi;h=0d5da95829269969e7cce28e57a4aa7803990a27;hp=fb48a2c2ff93896c8115c1e3b95c86cae23abfc4;hb=1e00b407e8d568d2ecaf980815d39702ffa343fc;hpb=5ed7952f41aad4521616a82eab03fa9cbdbae07c diff --git a/texi/auth.texi b/texi/auth.texi index fb48a2c2f..0d5da9582 100644 --- a/texi/auth.texi +++ b/texi/auth.texi @@ -1,57 +1,52 @@ \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} +@documentencoding UTF-8 @copying This file describes the Emacs auth-source library. -Copyright @copyright{} 2008, 2009 -Free Software Foundation, Inc. +Copyright @copyright{} 2008--2015 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. @@ -59,70 +54,159 @@ 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 single quotes 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 single quotes, e.g., @code{'he"llo'}. You can't mix both (so a +password or other token can't have both single 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: @@ -131,9 +215,9 @@ 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: @@ -143,57 +227,341 @@ machine yourmachine.com port scp login testuser password testpass 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. + +@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 -@defun auth-source-user-or-password mode host port +The auth-source library only has a few functions for external use. -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. +@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 -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: