Mercurial > emacs
view doc/misc/auth.texi @ 109805:8d09f7d877e7
nsselect.m: include keyboard.h for QPRIMARY, remove its declaration (Bug#6863).
author | Jan D <jan.h.d@swipnet.se> |
---|---|
date | Mon, 16 Aug 2010 10:03:27 +0200 |
parents | 60516122d066 |
children | 8d09094063d0 |
line wrap: on
line source
\input texinfo @c -*-texinfo-*- @setfilename ../../info/auth @settitle Emacs auth-source Library @value{VERSION} @set VERSION 0.2 @copying This file describes the Emacs auth-source library. Copyright @copyright{} 2008, 2009, 2010 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 @direntry * 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 @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:: * 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 ``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 ``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. 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 :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 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}. This is an encrypted file if and only if you set up EPA, which is strongly recommended. @lisp (require 'epa-file) (epa-file-enable) ;;; VERY important if you want symmetric encryption ;;; irrelevant if you don't (setq epa-file-cache-passphrase-for-symmetric-encryption t) @end lisp The simplest working netrc line example is one 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 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 &optional username Retrieve appropriate authentication tokens, determined by @var{mode}, 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 (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. @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. @var{username} contains the user name (e.g. ``joe'') as a string. @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 @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: @ignore arch-tag: 7b835fd3-473f-40fc-9776-1c4e49d26c94 @end ignore