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