# 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