doc/external-auth

   1 NNRPD External Authentication Support
   2
   3     This is $Revision: 7880 $ dated $Date: 2005-03-17 12:42:46 +0100 (Thu,
   4     17 Mar 2005) $.
   5
   6     A fundamental part of the readers.conf(5)-based authorization mechanism
   7     is the interface to external authenticator and resolver programs.  This
   8     interface is documented below.
   9
  10     INN ships with a number of such programs (all written in C, although any
  11     language can be used).  Code for them can be found in authprogs/ of the
  12     source tree; the authenticators are installed to *pathbin*/auth/passwd,
  13     and the resolvers are installed to *pathbin*/auth/resolv.
  14
  15 Reading information from nnrpd
  16
  17     When nnrpd spawns an external auth program, it passes information on
  18     standard input as a sequence of "key: value" lines.  Each line ends with
  19     CRLF, and a line consisting of only "." indicates the end of the input.
  20     The order of the fields is not significant.  Additional fields not
  21     mentioned below may be included; this should not be cause for alarm.
  22
  23     (For robustness as well as ease of debugging, it is probably wise to
  24     accept line endings consisting only of LF, and to treat EOF as
  25     indicating the end of the input even if "." has not been received.)
  26
  27     Code which reads information in the format discussed below and parses it
  28     into convenient structures is available authenticators and resolvers
  29     written in C; see libauth(3) for details.  Use of the libauth library
  30     will make these programs substantially easier to write and more robust.
  31
  32   For authenticators
  33
  34     When nnrpd calls an authenticator, the lines it passes are
  35
  36         ClientAuthname: user\r\n
  37         ClientPassword: pass\r\n
  38
  39     where *user* and *pass* are the username and password provided by the
  40     client (e.g. using AUTHINFO).  In addition, nnrpd generally also passes
  41     the fields mentioned as intended for resolvers; it rare instances this
  42     data may be useful for authenticators.
  43
  44   For resolvers
  45
  46     When nnrpd calls a resolver, the lines it passes are
  47
  48         ClientHost: hostname\r\n
  49         ClientIP: IP-address\r\n
  50         ClientPort: port\r\n
  51         LocalIP: IP-address\r\n
  52         LocalPort: port\r\n
  53         .\r\n
  54
  55     where *hostname* indicates a string representing the hostname if
  56     available, *IP-address* is a numeric IP address (dotted-quad for IPv4,
  57     equivalent for IPv6 if appropriate), and *port* is a numeric port
  58     number.  (The *LocalIP* paramter may be useful for determining which
  59     interface was used for the incoming connection.)
  60
  61     If information is not available, nnrpd will omit the corresponding
  62     fields.  In particular, this applies to the unusual situation of nnrpd
  63     not being connected to a socket; TCP-related information is not
  64     available for standard input.
  65
  66 Returning information to nnrpd
  67
  68   Exit status and signals
  69
  70     The external auth program must exit with a status of 0 to indicate
  71     success; any other exit status indicates failure.  (The non-zero exit
  72     value will be logged.)
  73
  74     If the program dies due to catching a signal (for example, a
  75     segmentation fault occurs), this will be logged and treated as a
  76     failure.
  77
  78   Returning a username and domain
  79
  80     If the program succeeds, it must return a username string (optionally
  81     with a domain appended) by writing to standard output.  The line it
  82     should write is exactly:
  83
  84         user:username\r\n
  85
  86     where *username* is the string that nnrpd should use in matching
  87     readers.conf access blocks.
  88
  89     There should be no extra spaces in lines sent from the hook to nnrpd;
  90     "user:aidan" is read by nnrpd as a different username than "user:
  91     aidan".
  92
  93 Error messages
  94
  95     As mentioned above, errors can be indicated by a non-zero exit value, or
  96     termination due to an unhandled signal; both cases are logged by nnrpd.
  97     However, external auth programs may wish to log error messages
  98     separately.
  99
 100     Although nnrpd will syslog() anything an external auth program writes to
 101     standard error, it is generally better to use the messages.h functions,
 102     such as warn() and die().
 103
 104     Please use the ckpasswd.c program as an example for any authenticators
 105     you write, and ident.c as an example for any resolvers.
 106
 107 HISTORY
 108
 109     Written by Aidan Cully for InterNetNews.  This documentation rewritten
 110     in POD by Jeffrey M. Vinocur <jeff@litech.org>.
 111