chiark / gitweb /
debugging for thing that crashed
[innduct.git] / doc / pod / external-auth.pod
1 =head1 NNRPD External Authentication Support
2
3 This is $Revision: 7141 $ dated $Date: 2005-03-17 03:42:46 -0800 (Thu, 17 Mar 2005) $.
4
5 A fundamental part of the readers.conf(5)-based authorization mechanism
6 is the interface to external authenticator and resolver programs.  This
7 interface is documented below.
8
9 INN ships with a number of such programs (all written in C, although any
10 language can be used).  Code for them can be found in F<authprogs/> of
11 the source tree; the authenticators are installed to
12 I<pathbin>/auth/passwd, and the resolvers are installed to
13 I<pathbin>/auth/resolv.
14
15 =head1 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 =head2 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 I<user> and I<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 =head2 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 I<hostname> indicates a string representing the hostname if
56 available, I<IP-address> is a numeric IP address (dotted-quad for IPv4,
57 equivalent for IPv6 if appropriate), and I<port> is a numeric port
58 number.  (The I<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 =head1 Returning information to nnrpd
67
68 =head2 Exit status and signals
69
70 The external auth program must exit with a status of C<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 =head2 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 I<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 C<user:aidan> is read by nnrpd as a different username than C<user:
91 aidan>.
92
93 =head1 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 F<messages.h>
102 functions, 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 =head1 HISTORY
108
109 Written by Aidan Cully for InterNetNews.  This documentation rewritten
110 in POD by Jeffrey M. Vinocur <jeff@litech.org>.
111
112 =cut