Merge from gnus--devo--0

[bpt/emacs.git] / doc / misc / auth.texi

\input texinfo                  @c -*-texinfo-*-

@setfilename auth.info

@set VERSION 0.1

@dircategory Emacs
@direntry
* auth-source: (auth).   The Emacs auth-source library.
@end direntry

@settitle Emacs auth-source Library @value{VERSION}

@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

@tex

@titlepage
@title Emacs auth-source Library

@author by Ted Zlatanov
@page

@vskip 0pt plus 1filll
@insertcopying
@end titlepage
@page

@end tex

@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.

@menu
* Overview::                    Overview of the auth-source library.
* Help for users::              
* Help for developers::         
* Index::                       
* Function Index::              
* Variable Index::              
@end menu

@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

@summarycontents
@contents
@bye

@c End:

@ignore
   arch-tag: 7b835fd3-473f-40fc-9776-1c4e49d26c94
@end ignore