4 The PamHandle Class

An instance of this class is automatically created for a Python PAM module when it is first referenced, (ie when it is execfile'ed). It is the first argument to every Python method called by PAM. It is destroyed automatically when pam_end(3) is called, right after the execfile'ed module is destroyed. If any method fails, or any access to a member fails a PamHandle.exception exception will be thrown. It contains the following members:

PAM_???
All the PAM_??? constants defined in the PAM include files are available. They are all read-only int's.

authtok
The PAM_AUTHTOK PAM item. Reading this results in a call pam_get_item(PAM_AUTHTOK), writing it results in a call pam_set_item(PAM_AUTHTOK, value). Its value will be either a string or None for the C value NULL.

env
This is a mapping representing the PAM environment. pam_python implements accesses and changes to it via the PAM methods pam_getenv(), pam_putenv() and pam_getenvlist(). The PAM environment only supports string keys and values, and the keys may not be blank or contain '='.

exception
The exception raised by methods defined here if they fail. It is a subclass of StandardError. Instances contain the member pam_result, which is the error code returned by PAM. The description is the PAM error message.

libpam_version
The version of PAM pam_python was compiled with. This is a string. In version 0.1.0 of pam_python and prior this was an int holding the version of PAM library loaded. Newer versions of PAM no longer export that value.

pamh
The PAM handle, as read-only int. Possibly useful during debugging.

oldauthtok
The PAM_OLDAUTHTOK PAM item. Reading this results in a call pam_get_item(PAM_OLDAUTHTOK), writing it results in a call pam_set_item(PAM_OLDAUTHTOK, value). Its value will be either a string or None for the C value NULL.

rhost
The PAM_RHOST PAM item. Reading this results in a call pam_get_item(PAM_RHOST), writing it results in a call pam_set_item(PAM_RHOST, value). Its value will be either a string or None for the C value NULL.

ruser
The PAM_RUSER PAM item. Reading this results in a call pam_get_item(PAM_RUSER), writing it results in a call pam_set_item(PAM_RUSER, value). Its value will be either a string or None for the C value NULL.

service
The PAM_SERVICE PAM item. Reading this results in a call pam_get_item(PAM_SERVICE), writing it results in a call pam_set_item(PAM_SERVICE, value). Its value will be either a string or None for the C value NULL.

tty
The PAM_TTY PAM item. Reading this results in a call pam_get_item(PAM_TTY), writing it results in a call pam_set_item(PAM_TTY, value). Its value will be either a string or None for the C value NULL.

user
The PAM_USER PAM item. Reading this results in a call pam_get_item(PAM_USER), writing it results in a call pam_set_item(PAM_USER, value). Its value will be either a string or None for the C value NULL.

user_prompt
The PAM_USER_PROMPT PAM item. Reading this results in a call pam_get_item(PAM_USER_PROMPT), writing it results in a call pam_set_item(PAM_USER_PROMPT, value). Its value will be either a string or None for the C value NULL.

The following methods are available:

Message( msg_style,msg)
Creates an instance of the PamMessage class. Instances of this class can be passed to the conversation() method. They are the equivalent of the C API's struct pam_message type, and have the same members. The arguments become the instance members of the same name. Instances are immutable.

Response( resp,ret_code)
Creates an instance of the PamResponse class. Instances of this class are returned by the conversation() method. They are the equivalent of the C API's struct pam_response type, and have the same members. The arguments become the instance members of the same name. Instances are immutable.

conversation( prompts)
Calls the function defined by the PAM_CONV item. The prompts argument is a Message object or a list them. You don't have to pass an actual Message object, any class that defines a string member msg and a int member msg_style will do. These members are used to initialise the struct pam_message members of the same name. It returns either a single Response object if a single Message was passed, or a list of them of the same length as the list passed. These Response objects contain the data the user entered.

fail_delay( delay)
This results in a call to pam_fail_delay(), which sets the maximum random delay after an authentication failure to delay milliseconds.

get_user( [prompt])
This results in a call to pam_get_user(), which returns the current user name (a string) or None if pam_get_user() return NULL. If not known it asks the PAM application for the user name, giving it the string prompt parameter to prompt the user to enter it.

strerror( errnum)
This results in a call to pam_strerror(), which returns a string description of the int PAM reurn value errnum.

There is no interface provided for PAM's pam_get_data() and pam_set_data() methods. There are two reasons for this. Firstly those two methods are provided so C code can have private storage local to the PAM handle. A Python PAM Module can use own module name space to do the same job, and its easier to do so. But more importantly its safer because there is no type-safe way of providing access to the facility from Python.