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.

This file describes the Emacs auth-source library.

Copyright © 2008, 2009 Free Software Foundation, Inc.

     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.

Overview
********

To be done.

Help for users
**************

If you have problems with the port, turn up 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:

     (require 'auth-source)
     (customize-variable 'auth-sources) ;; optional, do it once

 -- Variable: auth-sources

     The 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:

          (setq auth-sources '((:source "~/.authinfo.gpg" :host t :protocol t)))

     By adding multiple entries to that list with a particular host or protocol, you can have specific netrc files for that host or protocol.

``Netrc'' files are a de facto standard.  They look like this:

     machine mymachine login myloginname password mypassword port myport

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 AUTH-SOURCES, you'll have to live with the defaults: any host and any port are looked up in the netrc file ~/.authinfo.gpg.  This is an encrypted file if and only if you set up EPA, which is strongly recommended.

     (require 'epa-file)
     (epa-file-enable)
     (setq epa-file-cache-passphrase-for-symmetric-encryption t) ; VERY important

For url-auth authentication (HTTP/HTTPS), you need to put this in your netrc file:

     machine yourmachine.com:80 port http login testuser password testpass

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:

     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.

Help for developers
*******************

The auth-source library only has one function for external use.

 -- Function: auth-source-user-or-password mode host port

     Retrieve appropriate authentication tokens, determined by MODE, for host HOST and PORT.  If gnus-verbose is 9 or higher, debugging messages will be printed.

     If MODE is a list of strings, the function will return a list of strings or nil objects.  If it's a string, the function will return a string or a nil object.  Currently only the modes ``login'' and ``password'' are recognized but more may be added in the future.

     HOST is a string containing the host name.

     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.

          ;; IMAP example
          (setq auth (auth-source-user-or-password
                      '("login" "password")
                      "anyhostnamehere"
                      "imap"))
          (nth 0 auth) ; the login name
          (nth 1 auth) ; the password