Module: kpass
Version: 0.5
Distribution file: pykpass-0.5.tar.gz
Author: Shumon Huque <shuque -at- isc.upenn.edu>

    kpass( username, password, service, host, kt_pathname )

EXAMPLE USAGE:

	from kpass import kpass, KpassError
        try:
            rc = kpass("frank", "bozo", "blah", None, "FILE:/etc/my.keytab")
        except KpassError, diag:
            print "Error: %s" % str(diag)
        else:
            if (rc == 1):
                print "Authentication success"
            else:
                print "Authentication failure"

DESCRIPTION:

This Python extension module provides a simple function called
kpass() to perform password verification using Kerberos 5. It is 
intended for use by applications that cannot use the Kerberos 
protocol natively, but need to authenticate users against the 
Kerberos database. If it must be run on a system that receives a 
username and password over the network, steps should be taken to 
ensure that these are passed to that system in a cryptographically 
secure manner.

kpass() attempts to validate a given user's Kerberos username and
password. It does this in the following manner: it first obtains a 
Kerberos ticket for the specified service for the given username and 
password from the Kerberos AS. And then attempts to decrypt the ticket 
using the key stored in the specified keytable file to verify the 
authenticity of the AS response. The python 'None' type can be passed 
as the 4th (host) argument to use the fully canonicalized primary 
hostname of the system that the function is executed on. The fifth 
argument can also be 'None' to use the system's default keytab file 
(usually "FILE:/etc/krb5.keytab").

Note that previous versions of this module obtained a TGT from the
AS and then subsequently used that to obtain the service ticket from
the TGS. Directly obtaining the service ticket from the AS saves a
round trip with the KDC and the associated cryptographic computations.

Local password verification doesn't need a replay cache, so kpass() 
by disables it. This speeds things up quite a bit, if you are invoking 
this function many times in quick succession.

kpass() returns 1 if password verification is successful, 0 if the 
username or password is incorrect and raises a custom exception of
"KpassError" if a system error is encountered.

kpass() relies on obtaining Kerberos realm and KDC information 
from the invoking environment. Typically it will get this from
the system's Kerberos configuration file (krb5.conf) and/or DNS
records. One quick way to override the default environment is to
create a custom krb5.conf file and set the pathname to this file
as the value of the KRB5_CONFIG environment variable.

This distribution is accompanied by a PGP signature. My PGP public
key can be obtained from <http://www.huque.com/~shuque/pgp/> or one
of the PGP key servers.

PRE-REQUISITES:

	- Python 2.x
	- MIT Kerberos V5 Release 1.3.x or newer (this package
	  seems to work with recent versions of Heimdal also,
	  but I have not tested this extensively).
	- Creation of an application service principal on the
	  Kerberos server for use by this function.
	- Storing this principal and it's associated key in
	  a local keytab file.

INSTALLATION:

1. Edit the file "setup.py" if necessary, to reflect the proper
   locations of the MIT Kerberos 5 libraries, include files, and
   other paraphernalia for your system.

2. Build the distribution:

	python setup.py build

3. Install it (probably as 'root' to install system wide):

	python setup.py install

   (If you just want to install the module in your home directory,
   use "python setup.py install --home $HOME", which will usually 
   put it in $HOME/lib/python/)

4. For testing the function, you'll need to edit the test/test1.py
   file appropriately for your environment (or write your own
   python code).

Shumon Huque
E-mail: <shuque -at- isc.upenn.edu>
Web: http://www.huque.com/~shuque/
University of Pennsylvania.

Copyright (c) 2005 - 2011, Shumon Huque. All rights reserved.  
This program is free software; you can redistribute it and/or modify 
it under the same terms as Python itself.