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> |
---|
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.
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.
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:
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:
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 or 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:
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:
The following methods are available:
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.
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.
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 file:/var/syslog or file:/var/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:
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.
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 the 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.
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, 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