X-Git-Url: https://cgit.sxemacs.org/?a=blobdiff_plain;f=texi%2Fauth.texi;h=1f88d4c1dc5107aac9b3553c9a175589d9254a59;hb=2a000c5fd3c6662f4f1487cac7a965c84502783c;hp=381ec73ca994809a3bf5cc02ad403a3b54c92ec3;hpb=a90e87fa2eb92b16f43d5904396466ada49f0e97;p=gnus diff --git a/texi/auth.texi b/texi/auth.texi index 381ec73ca..1f88d4c1d 100644 --- a/texi/auth.texi +++ b/texi/auth.texi @@ -1,22 +1,13 @@ \input texinfo @c -*-texinfo-*- - -@setfilename auth.info +@setfilename auth @settitle Emacs auth-source Library @value{VERSION} -@set VERSION 0.1 - -@dircategory Emacs -@direntry -* auth-source: (auth). The Emacs auth-source library. -@end direntry - -@settitle Emacs auth-source Library @value{VERSION} +@set VERSION 0.2 @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 @@ -40,22 +31,20 @@ license to the document, as described in section 6 of the license. @dircategory Emacs @direntry -* Auth-source: (auth). The Emacs auth-source library. +* Auth-source: (auth). The Emacs auth-source library. @end direntry @titlepage @title Emacs auth-source Library - @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. @@ -63,70 +52,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 ``I have a server name and +a port, what are my user name and password?'' + +The auth-source library actually supports more than just the user name +(known as the login) or the password, but only those two are in use +today in Emacs or Gnus. Similarly, the auth-source library supports +multiple storage formats, currently either the classic ``netrc'' +format, examples of which you can see later in this document, or the +Secret Service API. @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 machine is the server (either a DNS name or an IP address). + +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 @var{143} and for protocol +@var{imap} if you fancy that. Anyway, you can just omit the port if +you don't need it. + +The login and password are simply your login credentials to the server. + +``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 port, set @code{auth-source-debug} to +@code{t} and see what port 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"))) @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. +This says ``for any host and any protocol, use just that one file.'' +Sweet simplicity. In fact, the latter is already the default, so +unless you want to move your netrc file, it will just work if you have +that file. Make sure it exists. + +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 an example that uses the Secret Service API for all lookups, +using the default collection: + +@lisp +(setq auth-sources '((:source (:secrets default)))) +@end lisp + +And here's a mixed example, using two sources: + +@lisp +(setq auth-sources '((:source (:secrets default) :host "myserver" :user "joe") + (:source "~/.authinfo.gpg"))) +@end lisp + +The best match is determined by order (starts from the bottom) only +for the first pass, where things are checked exactly. In the example +above, the first pass would find a single match for host +@code{myserver}. The netrc choice would fail because it matches any +host and protocol implicitly (as a @emph{fallback}). A specified +value of @code{:host t} in @code{auth-sources} is considered a match +on the first pass, unlike a missing @code{:host}. + +Now if you look for host @code{missing}, it won't match either source +explicitly. The second pass (the @emph{fallback} pass) will look at +all the implicit matches and collect them. They will be scored and +returned sorted by score. The score is based on the number of +explicit parameters that matched. See the @code{auth-pick} function +for details. @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}). + +The simplest working netrc line example is one 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: @@ -135,9 +202,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: @@ -147,24 +214,35 @@ 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. -@defun auth-source-user-or-password mode host port +@defun auth-source-user-or-password mode host port &optional username 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. +for host @var{host} and @var{port}. If @var{username} is provided it +will also be checked. If @code{auth-source-debug} is t, debugging +messages will be printed. Set @code{auth-source-debug} to a function +to use that function for logging. The parameters passed will be the +same that the @code{message} function takes, that is, a string +formatting spec and optional parameters. 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. +strings or @code{nil} objects (thus you can avoid parsing the netrc +file or checking the Secret Service API more than once). 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. @var{host} is a string containing the host name. @@ -172,6 +250,8 @@ future. a port number. It must be a string, corresponding to the port in the users' netrc files. +@var{username} contains the user name (e.g. ``joe'') as a string. + @example ;; IMAP example (setq auth (auth-source-user-or-password @@ -184,6 +264,56 @@ users' netrc files. @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 @@ -196,12 +326,6 @@ users' netrc files. @chapter Variable Index @printindex vr -@summarycontents -@contents @bye @c End: - -@ignore - arch-tag: 7b835fd3-473f-40fc-9776-1c4e49d26c94 -@end ignore