pam_python¶

Abstract

pam_python is a PAM module that runs the Python interpreter, and so allows PAM modules to be written in Python.

Author:	Russell Stuart <russell-pampython@stuart.id.au>

Introduction¶

The pam_python PAM module runs the Python source file (aka Python PAM module) it is given in the Python interpreter, making the PAM module API available to it. This document describes the how the PAM Module API is exposed to the Python PAM module. It does not describe how to use the API. You must read the PAM Module Writers Guide to learn how to do that. To re-iterate: this document does not tell you how to write PAM modules, it only tells you how to access the PAM module API from Python.

Writing PAM modules from Python incurs a large performance penalty and requires Python to be installed, so it is not the best option for writing modules that will be used widely. On the other hand memory allocation / corruption problems can not be caused by bad Python code, and a Python module is generally shorter and easier to write than its C equivalent. This makes it ideal for the system administrator who just wants to make use of the the PAM API for his own ends while minimising the risk of introducing memory corruption problems into every program using PAM.

Configuring PAM¶

Tell PAM to use a Python PAM module in the usual way: add a rule to your PAM configuration. The PAM administrators manual gives the syntax of a rule as:

service type control module-path module-arguments

The first three parameters are the same for all PAM modules and so aren’t any different for pam_python. The module-path is the path to pam_python.so. Like all paths PAM modules it is relative to the default PAM module directory so is usually just the string pam_python.so. The first module-argument is the path to the Python PAM module. If it doesn’t start with a / it is relative to the /lib/security. All module-arguments, including the path name to the Python PAM module are passed to it.

Python PAM modules¶

When a PAM handle created by the applications call to PAM’s pam_start() function first uses a Python PAM module, pam_python invokes it using Python’s execfile function. The following variables are passed to the invoked module in its global namespace:

__builtins__¶: The usual Python __builtins__.

__file__¶: The absolute path name to the Python PAM module.

As described in the PAM Module Writers Guide, PAM interacts with your module by calling methods you provide in it. Each type in the PAM configuration rules results in one or more methods being called. The Python PAM module must define the methods that will be called by each rule type it can be used with. Those methods are:

pam_sm_acct_mgmt(pamh, flags, args)¶: The service module’s implementation of PAM’s pam_acct_mgmt(3) interface.

pam_sm_authenticate(pamh, flags, args)¶: The service module’s implementation of PAM’s pam_authenticate(3) interface.

pam_sm_close_session(pamh, flags, args)¶: The service module’s implementation of PAM’s pam_close_session(3) interface.

pam_sm_chauthtok(pamh, flags, args)¶: The service module’s implementation of PAM’s pam_chauthtok(3) interface.

pam_sm_open_session(pamh, flags, args)¶: The service module’s implementation of PAM’s pam_open_session(3) interface.

pam_sm_setcred(pamh, flags, args)¶: The service module’s implementation of PAM’s pam_setcred(3) interface.

The arguments and return value of all these methods are the same. The pamh parameter is an instance of the PamHandle class. It is used to interact with PAM and is described in the next section. The remaining arguments are as described in the PAM Module Writers Guide. All functions must return an integer, eg pamh.PAM_SUCCESS. The valid return codes for each function are defined PAM Module Writers Guide. If the Python method isn’t present pam_python will return pamh.PAM_SYMBOL_ERR to PAM; if the method doesn’t return an integer or throws an exception pamh.PAM_SERVICE_ERR is returned.

There is one other method that in the Python PAM module that may be called by pam_python. It is optional:

pam_sm_end(pamh)¶: If present this will be called when the application calls PAM’s pam_end(3) function. If not present nothing happens. The parameter pamh is the PamHandle object. The return value is ignored.

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’s pam_end() 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 version 1.1.1 are available. They are all read-only int’s.

authtok¶: The PAM_AUTHTOK PAM item. Reading this results in a call to the PAM library function 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.

authtok_type¶: The PAM_AUTHTOK_TYPE PAM item. Reading this results in a call to the PAM library function pam_get_item(PAM_AUTHTOK_TYPE), writing it results in a call pam_set_item(PAM_AUTHTOK_TYPE, value). Its value will be either a string or None for the C value NULL. New in version 1.0.0. Only present if the version of PAM pam_python is compiled with supports it.

env¶: This is a mapping representing the PAM environment. pam_python implements accesses and changes to it via the PAM library function pam_getenv(), pam_putenv() and pam_getenvlist(). The PAM environment only supports string keys and values, and the keys may not be blank nor 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.

py_initialized¶: A read-only int. If the Python interpreter was initialised before the pam_python module was created this is 0. Otherwise it is 1, meaning pam_python has called Py_Initialize() and will call Py_Finalize() when the last pam_python module is destroyed.

oldauthtok¶: The PAM_OLDAUTHTOK PAM item. Reading this results in a call to the PAM library function 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 to the PAM library function 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 to the PAM library function 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 to the PAM library function 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 to the PAM library function 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 to the PAM library function 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 to the PAM library function 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.

xauthdata¶: The PAM_XAUTHDATA PAM item. Reading this results in a call to the PAM library function pam_get_item(PAM_XAUTHDATA), writing it results in a call pam_set_item(PAM_XAUTHDATA, value). Its value is a XAuthData instance. When setting its value you don’t have to use an actual XAuthData instance, any class that contains a string member name and a string member data will do. New in version 1.0.0. Only present if the version of PAM pam_python is compiled with supports it.

xdisplay¶: The PAM_XDISPLAY PAM item. Reading this results in a call to the PAM library function pam_get_item(PAM_XDISPLAY), writing it results in a call pam_set_item(PAM_XDISPLAY, value). Its value will be either a string or None for the C value NULL. New in version 1.0.0. Only present if the version of PAM pam_python is compiled with supports it.

The following methods are available:

PamHandle.Message(msg_style, msg)¶: Creates an instance of the Message class. The arguments become the instance members of the same name. This class is used to represent the C API’s struct pam_message type. An instance has two members corresponding to the C structure members of the same name: msg_style an int and data a string. Instances are immutable. Instances of this class can be passed to the conversation() method.

PamHandle.Response(resp, ret_code)¶: Creates an instance of the Response class. The arguments become the instance members of the same name. This class is used to represent the C API’s struct pam_response type. An instance has two members corresponding to the C structure members of the same name: resp a string and ret_code an int. Instances are immutable. Instances of this class are returned by the conversation() method.

PamHandle.XAuthData(name, data)¶: Creates an instance of the XAuthData class. The arguments become the instance members of the same name. This class is used to represent the C API’s struct pam_xauth_data type. An instance has two members corresponding to the C structure members of the same name: name a string and data also a string. Instances are immutable. The xauthdata member returns instances of this class and can be set to an instance of this class.

PamHandle.conversation(prompts)¶: Calls the function defined by the PAM PAM_CONV item. The prompts argument is a Message object or a list of them. You don’t have to pass an actual Message object, any class that contains 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.

PamHandle.fail_delay(delay)¶: This results in a call to the PAM library function pam_fail_delay(), which sets the maximum random delay after an authentication failure to delay milliseconds.

PamHandle.get_user([prompt])¶: This results in a call to the PAM library function pam_get_user(), which returns the current user name (a string) or None if pam_get_user() returns 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.

PamHandle.strerror(errnum)¶: This results in a call to the PAM library function pam_strerror(), which returns a string description of the int PAM return value errnum.

There is no interface provided for the PAM library functions pam_get_data() and pam_set_data(). 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 it’s easier to do so. But more importantly it’s safer because there is no type-safe way of providing access to the facility from Python.

Diagnostics, Debugging, Bugs¶

The way pam_python operates will be foreign to most Python programmers. It embeds Python into existing programs, primarily ones written in C. This means things like debugging and diagnostics are done differently to a normal Python program.

Diagnostics¶

If pam_python returns something other than PAM_SUCCESS to PAM a message will be written to the syslog LOG_AUTHPRIV facility. The only exception to this is when pam_python is passing on the return value from a Python pam_sm_...() entry point - nothing is logged in that case. So, if your Python PAM Module is failing in mysterious ways check the log file your system is configured to write LOG_AUTHPRIV entries to. Usually this is /var/log/syslog or /var/log/auth.log. The diagnostic or traceback Python would normally print to sys.stderr will be in there.

The PAM result codes returned directly by pam_python are:

PAM_BUF_ERR¶: Memory allocation failed.

PAM_MODULE_UNKNOWN¶: The Python PAM module name wasn’t supplied.

PAM_OPEN_ERR¶: The Python PAM module could not be opened.

PAM_SERVICE_ERR¶: A Python exception was thrown, unless it was because of a memory allocation failure.

PAM_SYMBOL_ERR¶: A pam_sm_...() called by PAM wasn’t defined by the Python PAM module.

Debugging¶

If you have Python bindings for the PAM Application library then you can write test units in Python and use Pythons pdb module debug a Python PAM module. This is how pam_python was developed.

I used PyPAM for the Python Application library bindings. Distributions often package it as python-pam. To set breakpoints in pdb either wait until PAM has loaded your module, or import it before you start debugging.

Bugs¶

There are several design decisions you may stumble across when using pam_python. One is that the Python PAM module is isolated from the rest of the Python environment. This differs from a import’ed Python module, where regardless of how many times a module is imported there is only one copy that shares the one global name space. For example, if you import your Python PAM module and then debug it as suggested above then there will be 2 copies of your Python PAM module in memory - the imported one and the one PAM is using. If the PAM module sets a global variable you won’t see it in the import’ed one. Indeed, obtaining any sort of handle to the module PAM is using is near impossible. This means the debugger can inspect variables in the module only when a breakpoint has one of the modules functions in its backtrace.

There are a few of reasons for this. Firstly, the PAM Module Writers Guide says this is the way it should be, so pam_python encourages it. Secondly, if a PAM application is using a Python PAM Module it’s important the PAM module remains as near to invisible as possible to avoid conflicts. Finally, and most importantly, references to objects constructed by the Python PAM module must never leak. This is because the destructors to those objects are C functions that live in pam_python, and those destructors are called when all references to the objects are gone. When the application calls PAM library function pam_end() function pam_python is unloaded, and with it goes the destructor code. Should a reference to an object defined by pam_python exist after pam_end() returns the call to destructor will result in a jump to a non-existent address causing a SIGSEGV.

Another potential trap is the initialisation and finalisation of the Python interpreter itself. Calling the interpreter’s finalisation routine while it is in use would I imagine be a big no-no. If pam_python has to initialise the interpreter (by calling Py_Initialize()) then it will call its finaliser Py_Finalize() when the last Python PAM module is destroyed. This is heuristic works in most scenarios. One example where is won’t work is a sequence like:

start-python-pam-module;
application-initialises-interpreter;
stop-python-pam-module;
application-stops-interpreter.

The above is doomed to fail.

An example¶

This is one of the examples provided by the package:

#
# Duplicates pam_permit.c
#
DEFAULT_USER    = "nobody"

def pam_sm_authenticate(pamh, flags, argv):
  try:
    user = pamh.get_user(None)
  except pamh.exception as e:
    return e.pam_result
  if user == None:
    pam.user = DEFAULT_USER
  return pamh.PAM_SUCCESS

def pam_sm_setcred(pamh, flags, argv):
  return pamh.PAM_SUCCESS

def pam_sm_acct_mgmt(pamh, flags, argv):
  return pamh.PAM_SUCCESS

def pam_sm_open_session(pamh, flags, argv):
  return pamh.PAM_SUCCESS

def pam_sm_close_session(pamh, flags, argv):
  return pamh.PAM_SUCCESS

def pam_sm_chauthtok(pamh, flags, argv):
  return pamh.PAM_SUCCESS

Assuming it and pam_python.so are in the directory /lib/security adding these rules to /etc/pam.conf would run it:

login account   requisite   pam_python.so pam_accept.py
login auth      requisite   pam_python.so pam_accept.py
login password  requisite   pam_python.so pam_accept.py
login session   requisite   pam_python.so pam_accept.py