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