* auth.texi (Help for users): Login collection is "Login" and not "login".
[gnus] / texi / auth.texi
index 060c0b9..d1208d5 100644 (file)
@@ -1,21 +1,16 @@
 \input texinfo                  @c -*-texinfo-*-
 
-@setfilename auth.info
-
-@set VERSION 0.1
-
-@dircategory Emacs
-@direntry
-* auth-source: (auth).   The Emacs auth-source library.
-@end direntry
+@include gnus-overrides.texi
 
+@setfilename auth
 @settitle Emacs auth-source Library @value{VERSION}
 
+@set VERSION 0.3
+
 @copying
 This file describes the Emacs auth-source library.
 
-Copyright @copyright{} 2008, 2009
-Free Software Foundation, Inc.
+Copyright @copyright{} 2008-2011 Free Software Foundation, Inc.
 
 @quotation
 Permission is granted to copy, distribute and/or modify this document
@@ -37,21 +32,27 @@ license to the document, as described in section 6 of the license.
 @end quotation
 @end copying
 
-@tex
+@dircategory Emacs
+@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 +60,148 @@ 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
 
-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.  You can also use
+@code{protocol}.
+
+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 @code{\}.
+
+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 @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.
+
+If you have problems with the search, set @code{auth-source-debug} to
+@code{t} and see what host, port, and user 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.
 
-Setup:
+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
+;;; old default: required :host and :protocol, not needed anymore
 (setq auth-sources '((:source "~/.authinfo.gpg" :host t :protocol 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"))
+;;; 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: any host and any port are looked up in the netrc
+file @code{~/.authinfo.gpg}, which is a GnuPG encrypted file
+(@pxref{GnuPG and EasyPG Assistant Configuration}).  
+
+If that fails, the unencrypted netrc file @code{~/.authinfo} will
+be used.
+
+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.
+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?
 
-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.
-
-@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 +210,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,43 +222,93 @@ 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 Secret Service API
+@chapter Secret Service API
+
+TODO: how does it work generally, how does secrets.el work, some examples.
 
 @node Help for developers
 @chapter Help for developers
 
-The auth-source library only has one function for external use.
+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 SPEC
 
-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.
+TODO: how to include docstring?
 
-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.
+@end defun
 
-@var{host} is a string containing the host name.
+@defun auth-source-delete SPEC
 
-@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.
+TODO: how to include docstring?
 
-@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
-@end example
+@end defun
+
+@defun auth-source-forget SPEC
+
+TODO: how to include docstring?
 
 @end defun
 
+@defun auth-source-forget+ SPEC
+
+TODO: how to include docstring?
+
+@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 @code{~/.authinfo.gpg}, which is a GnuPG encrypted file.
+
+In Emacs 23 or later there is an option @code{auto-encryption-mode} to
+automatically decrypt @code{*.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 Assitant
+(@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
@@ -192,12 +321,6 @@ users' netrc files.
 @chapter Variable Index
 @printindex vr
 
-@summarycontents
-@contents
 @bye
 
 @c End:
-
-@ignore
-   arch-tag: dc9650be-a953-40bf-bc55-24fe5f19d875
-@end ignore