X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ian/git?p=innduct.git;a=blobdiff_plain;f=doc%2Fexternal-auth;fp=doc%2Fexternal-auth;h=0000000000000000000000000000000000000000;hp=28fc8473bbbb3daf1bdc3753717899b53a99fdc0;hb=b7a32e2d73e3ab1add8208d3e157f7269a31ef4d;hpb=ac902a8299ff4469b356836f431ead31c3377377;ds=sidebyside diff --git a/doc/external-auth b/doc/external-auth deleted file mode 100644 index 28fc847..0000000 --- a/doc/external-auth +++ /dev/null @@ -1,111 +0,0 @@ -NNRPD External Authentication Support - - This is $Revision: 7880 $ dated $Date: 2005-03-17 12:42:46 +0100 (Thu, - 17 Mar 2005) $. - - A fundamental part of the readers.conf(5)-based authorization mechanism - is the interface to external authenticator and resolver programs. This - interface is documented below. - - INN ships with a number of such programs (all written in C, although any - language can be used). Code for them can be found in authprogs/ of the - source tree; the authenticators are installed to *pathbin*/auth/passwd, - and the resolvers are installed to *pathbin*/auth/resolv. - -Reading information from nnrpd - - When nnrpd spawns an external auth program, it passes information on - standard input as a sequence of "key: value" lines. Each line ends with - CRLF, and a line consisting of only "." indicates the end of the input. - The order of the fields is not significant. Additional fields not - mentioned below may be included; this should not be cause for alarm. - - (For robustness as well as ease of debugging, it is probably wise to - accept line endings consisting only of LF, and to treat EOF as - indicating the end of the input even if "." has not been received.) - - Code which reads information in the format discussed below and parses it - into convenient structures is available authenticators and resolvers - written in C; see libauth(3) for details. Use of the libauth library - will make these programs substantially easier to write and more robust. - - For authenticators - - When nnrpd calls an authenticator, the lines it passes are - - ClientAuthname: user\r\n - ClientPassword: pass\r\n - - where *user* and *pass* are the username and password provided by the - client (e.g. using AUTHINFO). In addition, nnrpd generally also passes - the fields mentioned as intended for resolvers; it rare instances this - data may be useful for authenticators. - - For resolvers - - When nnrpd calls a resolver, the lines it passes are - - ClientHost: hostname\r\n - ClientIP: IP-address\r\n - ClientPort: port\r\n - LocalIP: IP-address\r\n - LocalPort: port\r\n - .\r\n - - where *hostname* indicates a string representing the hostname if - available, *IP-address* is a numeric IP address (dotted-quad for IPv4, - equivalent for IPv6 if appropriate), and *port* is a numeric port - number. (The *LocalIP* paramter may be useful for determining which - interface was used for the incoming connection.) - - If information is not available, nnrpd will omit the corresponding - fields. In particular, this applies to the unusual situation of nnrpd - not being connected to a socket; TCP-related information is not - available for standard input. - -Returning information to nnrpd - - Exit status and signals - - The external auth program must exit with a status of 0 to indicate - success; any other exit status indicates failure. (The non-zero exit - value will be logged.) - - If the program dies due to catching a signal (for example, a - segmentation fault occurs), this will be logged and treated as a - failure. - - Returning a username and domain - - If the program succeeds, it must return a username string (optionally - with a domain appended) by writing to standard output. The line it - should write is exactly: - - user:username\r\n - - where *username* is the string that nnrpd should use in matching - readers.conf access blocks. - - There should be no extra spaces in lines sent from the hook to nnrpd; - "user:aidan" is read by nnrpd as a different username than "user: - aidan". - -Error messages - - As mentioned above, errors can be indicated by a non-zero exit value, or - termination due to an unhandled signal; both cases are logged by nnrpd. - However, external auth programs may wish to log error messages - separately. - - Although nnrpd will syslog() anything an external auth program writes to - standard error, it is generally better to use the messages.h functions, - such as warn() and die(). - - Please use the ckpasswd.c program as an example for any authenticators - you write, and ident.c as an example for any resolvers. - -HISTORY - - Written by Aidan Cully for InterNetNews. This documentation rewritten - in POD by Jeffrey M. Vinocur . -