{"id":14796,"library":"pamela","title":"PAMELA: Python PAM Interface","description":"Pamela is a Python wrapper for Pluggable Authentication Modules (PAM) that utilizes `ctypes` to interface with the system's PAM libraries. It merges functionality from previously abandoned Python PAM projects (gnosek/python-pam and simplepam) to provide robust Python 3 support, raise informative `PamError` exceptions on failure, and manage PAM sessions. Maintained by Project Jupyter, it aims to offer a reliable and up-to-date solution for system authentication on Unix-like operating systems. The current version is 1.2.0, released in August 2024, indicating active development.","status":"active","version":"1.2.0","language":"en","source_language":"en","source_url":"https://github.com/minrk/pamela","tags":["PAM","authentication","system","security","unix","linux","ctypes"],"install":[{"cmd":"pip install pamela","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"symbol":"authenticate","correct":"from pamela import authenticate"},{"symbol":"open_session","correct":"from pamela import open_session"},{"symbol":"close_session","correct":"from pamela import close_session"},{"symbol":"check_account","correct":"from pamela import check_account"},{"symbol":"change_password","correct":"from pamela import change_password"},{"note":"Pamela is distinct from other `python-pam` modules, though it aims for an identical interface in some aspects.","wrong":"from pam import PAMError","symbol":"PAMError","correct":"from pamela import PAMError"}],"quickstart":{"code":"import getpass\nfrom pamela import authenticate, PAMError\n\ndef verify_user_pam(username, password, service='login'):\n    try:\n        # The 'login' service is a common default, but can be changed.\n        # On some systems, `auth` might also be a default.\n        # A common test is `python -m pamela -a $(whoami)`\n        if authenticate(username, password, service=service):\n            print(f\"Authentication successful for user: {username}\")\n            return True\n        else:\n            # authenticate returns False for simple failures (e.g., bad password)\n            # but can also raise PAMError for more critical issues.\n            print(f\"Authentication failed for user: {username}.\")\n            return False\n    except PAMError as e:\n        print(f\"PAM error during authentication for {username}: {e}\")\n        return False\n    except Exception as e:\n        print(f\"An unexpected error occurred: {e}\")\n        return False\n\nif __name__ == '__main__':\n    user = getpass.getuser()\n    pwd = getpass.getpass(f\"Password for {user}: \")\n    \n    # Example with default 'login' service\n    print(\"\\n--- Testing 'login' service ---\")\n    verify_user_pam(user, pwd, service='login')\n    \n    # Example with a custom service, e.g., 'sudo' (requires appropriate PAM setup)\n    # For this to work, a PAM configuration for 'sudo' might be needed, or ensure\n    # the user has permissions for this service.\n    # print(\"\\n--- Testing 'sudo' service (if configured) ---\")\n    # verify_user_pam(user, pwd, service='sudo')","lang":"python","description":"This quickstart demonstrates how to use `pamela.authenticate` to verify a user's credentials against the system's PAM configuration. It includes error handling for `PAMError` and prompts the user for their system password using `getpass`. The default PAM service 'login' is used, and a commented-out example for a 'sudo' service is provided to illustrate flexibility."},"warnings":[{"fix":"Catch `pamela.PAMError` for robust error handling alongside checking the boolean return value of `authenticate`.","message":"Unlike some older Python PAM wrappers (e.g., `gnosek/python-pam`), Pamela raises a `PamError` exception for critical failures instead of simply returning `False`.","severity":"breaking","affected_versions":"All versions (since 1.0.0 merge)"},{"fix":"Ensure deployment on compatible operating systems. For cross-platform authentication, consider alternative methods or libraries not dependent on PAM.","message":"Pamela relies on underlying system PAM libraries (e.g., `libpam.so`, `libc.so`). It is inherently OS-specific and only functions on Unix-like operating systems (Linux, macOS POSIX). It will not work on Windows without a PAM compatibility layer.","severity":"gotcha","affected_versions":"All versions"},{"fix":"As of April 2026, it is recommended to test `pamela` thoroughly if using Python 3.14 or later. Monitor GitHub issues for updates or consider using Python 3.13 or earlier if encountering this specific error.","message":"There are reported issues with `pamela` on Python 3.14 (specifically with beta versions), where `test_environment` can fail with `PAMError: [PAM Error 26] Critical error - immediate abort`.","severity":"gotcha","affected_versions":"Potentially 1.2.0 and earlier on Python 3.14+"},{"fix":"Always follow security best practices for PAM configuration. Consult your operating system's PAM documentation when creating or modifying service files. Test privileged authentication flows thoroughly in a secure environment.","message":"Using `pamela` for authentication in `sudo` or similar privileged contexts requires careful configuration of PAM service files (e.g., `/etc/pam.d/sudo`). Incorrect or insecure PAM configurations can expose the system.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Pamela is designed for Unix-like systems. Ensure you are running on a compatible OS (Linux, macOS). On some minimal Linux distributions, you may need to install development packages for PAM (e.g., `libpam-dev` or `pam-devel`).","cause":"This error typically occurs when `ctypes.util.find_library('c')` or `find_library('pam')` returns `None`, meaning the underlying C or PAM library cannot be located on the system. This is common on Windows or minimalist Linux environments.","error":"TypeError: LoadLibrary() argument 1 must be str, not None"},{"fix":"If encountering this error, verify your Python version. This might be a compatibility issue with newer Python releases; consider downgrading to Python 3.13 or earlier. Check the `jupyterhub/pamela` GitHub issues for updates on Python 3.14 compatibility.","cause":"This error has been observed in testing environments, particularly with Python 3.14 beta versions, indicating a critical PAM operation failure.","error":"pamela.PAMError: [PAM Error 26] Critical error - immediate abort"},{"fix":"Install the package using pip: `pip install pamela`. If using a virtual environment, ensure it's activated before installation and execution.","cause":"The `pamela` package is not installed in the active Python environment or the Python interpreter cannot find it.","error":"ModuleNotFoundError: No module named 'pamela'"},{"fix":"Double-check the username and password. Verify that the PAM service (e.g., 'login', 'sudo') exists and is correctly configured on your system (e.g., by inspecting files in `/etc/pam.d/`). Test with a known working username/password for the target service.","cause":"This generic message from `pamela.authenticate` usually means the provided username/password combination is incorrect for the specified PAM service, or the PAM service itself is misconfigured.","error":"Authentication failed for user: <username>."}],"ecosystem":"pypi"}