************** |pam_python| ************** .. toctree:: :maxdepth: 2 .. topic:: 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> .. _intro: 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 |PMWG|_ 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: 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. .. _module: Python PAM modules ================== When a PAM handle created by the applications call to PAM's :samp:`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: .. data:: __builtins__ The usual Python ``__builtins__``. .. data:: __file__ The absolute path name to the Python PAM module. As described in the |PMWG|, 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: .. function:: pam_sm_acct_mgmt(pamh, flags, args) The service module's implementation of PAM's :manpage:`pam_acct_mgmt(3)` interface. .. function:: pam_sm_authenticate(pamh, flags, args) The service module's implementation of PAM's :manpage:`pam_authenticate(3)` interface. .. function:: pam_sm_close_session(pamh, flags, args) The service module's implementation of PAM's :manpage:`pam_close_session(3)` interface. .. function:: pam_sm_chauthtok(pamh, flags, args) The service module's implementation of PAM's :manpage:`pam_chauthtok(3)` interface. .. function:: pam_sm_open_session(pamh, flags, args) The service module's implementation of PAM's :manpage:`pam_open_session(3)` interface. .. function:: pam_sm_setcred(pamh, flags, args) The service module's implementation of PAM's :manpage:`pam_setcred(3)` interface. The arguments and return value of all these methods are the same. The *pamh* parameter is an instance of the :class:`PamHandle` class. It is used to interact with PAM and is described in the next section. The remaining arguments are as described in the |PMWG|. All functions must return an integer, eg :const:`pamh.PAM_SUCCESS`. The valid return codes for each function are defined |PMWG|. If the Python method isn't present |pam_python| will return :const:`pamh.PAM_SYMBOL_ERR` to PAM; if the method doesn't return an integer or throws an exception :const:`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: .. function:: pam_sm_end(pamh) If present this will be called when the application calls PAM's :manpage:`pam_end(3)` function. If not present nothing happens. The parameter *pamh* is the :class:`PamHandle` object. The return value is ignored. .. _pamhandle: 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 :c:func:`pam_end` is called, right after the ``execfile``'ed module is destroyed. If any method fails, or any access to a member fails a :exc:`PamHandle.exception` exception will be thrown. It contains the following members: .. data:: PAM_??? All the :const:`PAM_???` constants defined in the PAM include files version 1.1.1 are available. They are all read-only :class:`int`'s. .. data:: authtok The :const:`PAM_AUTHTOK` PAM item. Reading this results in a call to the |pam-lib-func| :samp:`pam_get_item(PAM_AUTHTOK)`, writing it results in a call :samp:`pam_set_item(PAM_AUTHTOK, value)`. Its value will be either a :class:`string` or :const:`None` for the C value :c:macro:`NULL`. .. data:: authtok_type The :const:`PAM_AUTHTOK_TYPE` PAM item. Reading this results in a call to the |pam-lib-func| :samp:`pam_get_item(PAM_AUTHTOK_TYPE)`, writing it results in a call :samp:`pam_set_item(PAM_AUTHTOK_TYPE, value)`. Its value will be either a :class:`string` or :const:`None` for the C value :c:macro:`NULL`. New in version 1.0.0. Only present if the version of PAM |pam_python| is compiled with supports it. .. data:: env This is a mapping representing the PAM environment. |pam_python| implements accesses and changes to it via the |pam-lib-func| :samp:`pam_getenv()`, :samp:`pam_putenv()` and :samp:`pam_getenvlist()`. The PAM environment only supports :class:`string` keys and values, and the keys may not be blank nor contain '='. .. data:: exception The exception raised by methods defined here if they fail. It is a subclass of :class:`StandardError`. Instances contain the member :const:`pam_result`, which is the error code returned by PAM. The description is the PAM error message. .. data:: libpam_version The version of PAM |pam_python| was compiled with. This is a :class:`string`. In version 0.1.0 of |pam_python| and prior this was an :class:`int` holding the version of PAM library loaded. Newer versions of PAM no longer export that value. .. data:: pamh The PAM handle, as read-only :class:`int`. Possibly useful during debugging. .. data:: py_initialized A read-only :class:`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 :c:func:`Py_Initialize` and will call :c:func:`Py_Finalize` when the last |pam_python| module is destroyed. .. data:: oldauthtok The :const:`PAM_OLDAUTHTOK` PAM item. Reading this results in a call to the |pam-lib-func| :samp:`pam_get_item(PAM_OLDAUTHTOK)`, writing it results in a call :samp:`pam_set_item(PAM_OLDAUTHTOK, value)`. Its value will be either a :class:`string` or :const:`None` for the C value :c:macro:`NULL`. .. data:: rhost The :const:`PAM_RHOST` PAM item. Reading this results in a call to the |pam-lib-func| :samp:`pam_get_item(PAM_RHOST)`, writing it results in a call :samp:`pam_set_item(PAM_RHOST, value)`. Its value will be either a :class:`string` or :const:`None` for the C value :c:macro:`NULL`. .. data:: ruser The :const:`PAM_RUSER` PAM item. Reading this results in a call to the |pam-lib-func| :samp:`pam_get_item(PAM_RUSER)`, writing it results in a call :samp:`pam_set_item(PAM_RUSER, value)`. Its value will be either a :class:`string` or :const:`None` for the C value :c:macro:`NULL`. .. data:: service The :const:`PAM_SERVICE` PAM item. Reading this results in a call to the |pam-lib-func| :samp:`pam_get_item(PAM_SERVICE)`, writing it results in a call :samp:`pam_set_item(PAM_SERVICE, value)`. Its value will be either a :class:`string` or :const:`None` for the C value :c:macro:`NULL`. .. data:: tty The :const:`PAM_TTY` PAM item. Reading this results in a call to the |pam-lib-func| :samp:`pam_get_item(PAM_TTY)`, writing it results in a call :samp:`pam_set_item(PAM_TTY, value)`. Its value will be either a :class:`string` or :const:`None` for the C value :c:macro:`NULL`. .. data:: user The :const:`PAM_USER` PAM item. Reading this results in a call to the |pam-lib-func| :samp:`pam_get_item(PAM_USER)`, writing it results in a call :samp:`pam_set_item(PAM_USER, value)`. Its value will be either a :class:`string` or :const:`None` for the C value :c:macro:`NULL`. .. data:: user_prompt The :const:`PAM_USER_PROMPT` PAM item. Reading this results in a call to the |pam-lib-func| :samp:`pam_get_item(PAM_USER_PROMPT)`, writing it results in a call :samp:`pam_set_item(PAM_USER_PROMPT, value)`. Its value will be either a :class:`string` or :const:`None` for the C value :c:macro:`NULL`. .. data:: xauthdata The :const:`PAM_XAUTHDATA` PAM item. Reading this results in a call to the |pam-lib-func| :samp:`pam_get_item(PAM_XAUTHDATA)`, writing it results in a call :samp:`pam_set_item(PAM_XAUTHDATA, value)`. Its value is a :class:`XAuthData` instance. When setting its value you don't have to use an actual :class:`XAuthData` instance, any class that contains a :class:`string` member :attr:`name` and a :class:`string` member :attr:`data` will do. New in version 1.0.0. Only present if the version of PAM |pam_python| is compiled with supports it. .. data:: xdisplay The :const:`PAM_XDISPLAY` PAM item. Reading this results in a call to the |pam-lib-func| :samp:`pam_get_item(PAM_XDISPLAY)`, writing it results in a call :samp:`pam_set_item(PAM_XDISPLAY, value)`. Its value will be either a :class:`string` or :const:`None` for the C value :c:macro:`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: .. method:: PamHandle.Message(msg_style,msg) Creates an instance of the :class:`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: :attr:`msg_style` an :class:`int` and :attr:`data` a :class:`string`. Instances are immutable. Instances of this class can be passed to the :meth:`conversation` method. .. method:: PamHandle.Response(resp,ret_code) Creates an instance of the :class:`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: :attr:`resp` a :class:`string` and :attr:`ret_code` an :class:`int`. Instances are immutable. Instances of this class are returned by the :meth:`conversation` method. .. method:: PamHandle.XAuthData(name,data) Creates an instance of the :class:`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: :attr:`name` a :class:`string` and :attr:`data` also a :class:`string`. Instances are immutable. The :data:`xauthdata` member returns instances of this class and can be set to an instance of this class. .. method:: PamHandle.conversation(prompts) Calls the function defined by the PAM :c:macro:`PAM_CONV` item. The *prompts* argument is a :class:`Message` object or a :class:`list` of them. You don't have to pass an actual :class:`Message` object, any class that contains a :class:`string` member :attr:`msg` and a :class:`int` member :attr:`msg_style` will do. These members are used to initialise the ``struct pam_message`` members of the same name. It returns either a single :class:`Response` object if a single :class:`Message` was passed, or a :class:`list` of them of the same length as the :class:`list` passed. These :class:`Response` objects contain the data the user entered. .. method:: PamHandle.fail_delay(delay) This results in a call to the |pam-lib-func| :samp:`pam_fail_delay()`, which sets the maximum random delay after an authentication failure to *delay* milliseconds. .. method:: PamHandle.get_user([prompt]) This results in a call to the |pam-lib-func| :samp:`pam_get_user()`, which returns the current user name (a :class:`string`) or :const:`None` if :samp:`pam_get_user()` returns :c:macro:`NULL`. If not known it asks the PAM application for the user name, giving it the :class:`string` *prompt* parameter to prompt the user to enter it. .. method:: PamHandle.strerror(errnum) This results in a call to the |pam-lib-func| :samp:`pam_strerror()`, which returns a :class:`string` description of the :class:`int` PAM return value *errnum*. There is no interface provided for the |pam-lib-func|\s :samp:`pam_get_data()` and :samp:`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: 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. .. _return-values: Diagnostics ----------- If |pam_python| returns something other than :const:`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 :meth:`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/log/syslog` or :file:`/var/log/auth.log`. The diagnostic or traceback Python would normally print to :attr:`sys.stderr` will be in there. The PAM result codes returned directly by |pam_python| are: .. data:: PAM_BUF_ERR Memory allocation failed. .. data:: PAM_MODULE_UNKNOWN The Python PAM module name wasn't supplied. .. data:: PAM_OPEN_ERR The Python PAM module could not be opened. .. data:: PAM_SERVICE_ERR A Python exception was thrown, unless it was because of a memory allocation failure. .. data:: PAM_SYMBOL_ERR A :meth:`pam_sm_...` called by PAM wasn't defined by the Python PAM module. .. _debugging: Debugging --------- If you have Python bindings for the PAM Application library then you can write test units in Python and use Pythons :mod:`pdb` module debug a Python PAM module. This is how |pam_python| was developed. I used `PyPAM <http://www.pangalactic.org/PyPAM/>`_ for the Python Application library bindings. Distributions often package it as ``python-pam``. To set breakpoints in :mod:`pdb` either wait until PAM has loaded your module, or :keyword:`import` it before you start debugging. .. _bugs: 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 :keyword:`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 :keyword:`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 :keyword:`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 |PMWG| 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-lib-func| :samp:`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 :samp:`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 :c:func:`Py_Initialize`) then it will call its finaliser :c:func:`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. .. _example: An example ========== This is one of the examples provided by the package: .. include:: pam_permit.py :literal: 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 .. |PMWG| replace:: PAM Module Writers Guide .. _PMWG: http://www.linux-pam.org/Linux-PAM-html/ .. |pam_python| replace:: `pam_python` .. |pam-lib-func| replace:: PAM library function