
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
