Mercurial > emacs
view doc/misc/auth.texi @ 104244:97bc7c2be2d0
(read-regexp): Return empty string when `default-value' is nil.
(keep-lines-read-args): Don't use empty string as the
default value for `read-regexp'. (Bug#2495)
author | Juri Linkov <juri@jurta.org> |
---|---|
date | Wed, 12 Aug 2009 20:55:31 +0000 |
parents | 3e7c6b40afdd |
children | b99b3dda298b |
line wrap: on
line source
\input texinfo @c -*-texinfo-*- @setfilename ../../info/auth @settitle Emacs auth-source Library @value{VERSION} @set VERSION 0.1 @copying This file describes the Emacs auth-source library. Copyright @copyright{} 2008, 2009 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:: * Help for developers:: * Index:: * Function Index:: * Variable Index:: @end menu @end ifnottex @node Overview @chapter Overview To be done. @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. Setup: @lisp (require 'auth-source) (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: @lisp (setq auth-sources '((:source "~/.authinfo.gpg" :host t :protocol t))) @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. @end defvar ``Netrc'' files are a de facto standard. They look like this: @example machine mymachine login myloginname password mypassword port myport @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. @lisp (require 'epa-file) (epa-file-enable) (setq epa-file-cache-passphrase-for-symmetric-encryption t) ; VERY important @end lisp 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). 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. @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 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. 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. @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. @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