PYTHON AUTHENTICATION AND AUTHORIZATION SUPPORT FOR NNRPD, version 1.0 This file documents nnrpd's built-in optional support for Python reader authentication and authorization. It is based on Greg Andruk's (nee Fluffy) <gerglery@usa.net> Python interface to INN as well as on TCL and Perl hooks develped by Bob Heiney and Christophe Wolfhugel. For details on Python care and feeding at INN, please, refer to Greg Andruk's README.python_hook. Python authentication and authorization support in nnrpd along with filtering support in innd may be compiled in by giving --with-python command line flag to configure script. Python authentication and authorization may be turned on by nnrppythonauth setting in inn.conf configuration file. If nnrppythonauth in inn.conf is set to true, nnrpd will load Python module as defined in include/paths.h and located in the directory specified by pathfilter in inn.conf. Once the module is loaded, nnrpd will authenticate and authorize readers by calling a Python methods rather than reading readers.conf and using the normal authentication mechanism. Every time an authenticated reader asks nnrpd to read or post an article, Python authorization hooks are invoked before proceeding with requested operation. The authorization functionality makes sence when a list of newsgroups in your access statements grows too long to maintain in readers.conf or you need to have access control rules applying immediately that is without having to restart all the nnrpd processes. Also, Python authorization hooks perform access control on per newsgroup basis while readers.conf does the same on per user basis. However, consider the authorization functionality as an option which is reasonable in just a few cases (like those mentioned above). WRITING A NNRPD AUTHENTICATION MODULE: You need to create a nnrpd_auth.py module in INN's filter directory (see the pathfilter setting in inn.conf) where you should define a class holding certain methods. The methods followed are known to nnrpd. It uses them if present: __init__(self): Not explicitly called by nnrpd, but will run whenever the auth module is loaded. This is a good place to initialize constants or establish a database connection. close(self): This method is invoked on nnrpd termination. You can use it to save state information or close a database connection. authenticate(self, attributes): Called when a reader connects or issues AUTHINFO command. Connection attributes are passed in the "attributes" dictionary. The following keys are initialized by nnrpd: type - "connect", "authinfo", "read" or "post" values specify the authentication type. hostname - resolved hostname (or IP address if resolution fails) of connected reader; ipaddress - IP address of connected reader; interface - IP address of the interface at this machine reader is connected to; user - username as reader passed with AUTHINFO command or None if not applicible; pass - password as reader passed with AUTHINFO command or None if not applicible; newsgroup - name of the newsgroup reader requests read or post access to or None if not applicible; All the above values are buffer objects. See README.python_hook for comments on Python buffers. This method should return a tuple of four elements: 1) NNTP response code. Should be a valid NNTP response code (see example for details); 2) Reading Allowed. Should be a boolean value. 3) Posting Allowed. Should be a boolean value. 4) Wildmat expression that says what groups to provide access to. See explanation on applicible NNTP return codes in README.perl_hook file which comes with INN distribution. authorize(self, attributes): Called when a reader requests either read or post permission. The "attributes" dictionary is passed to group() method (see above for details). This method should return None to grant requested permission to requested newsgroup or non-empty string otherwise. The rejection string will be shown to reader. To register your methods with nnrpd, you need to create an instance of your class, import the built-in nnrpd module, and pass the instance to nnrpd.set_auth_hook(). For example: class AUTH: def authenticate(self, attributes): ... def authorize(self, attributes): ... import nnrpd myauth = AUTH() nnrpd.set_auth_hook(myauth) There is also a nnrpd.py module there which is not actually used by nnrpd but provides the same set of functions as built-in nnrpd module. This stub module may be used when debugging your own module. Check Greg Andruk's tips and tricks regarding programming Python INN filter (see README.python_hook). Almost everything there also applies to the case of programming Python authentication and authorization module. FUNCTIONS SUPPLIED BY THE BUILT-IN NNRPD MODULE: As of this writing, nnrpd built-in module exports the following functions: set_auth_hook() - used to pass a reference to the instance of authentication and authorization class to nnrpd; syslog() - intended to be a replacement for a Python native syslog. See README.python_hook for details. =-=-= This document and Python authentication&authorization support for nnrpd was written by Ilya Etingof <ilya@glas.net>, 12/1999