python-pam 2.0.0__py3-none-any.whl → 2.1.0__py3-none-any.whl

pam/__init__.py

@@ -1,9 +1,9 @@
-import sys as __sys
+"""PAM (Pluggable Authentication Modules) interface for Python.
 
-if __sys.version_info < (3, ):  # pragma: no cover
-    print('WARNING, Python 2 is EOL and therefore py2 support in this '
-          "package is deprecated. It won't be actively checked for"
-          'correctness')
+This module provides a Python interface to Linux-PAM, allowing authentication
+against system PAM services.
+"""
+import sys as __sys
 
 # list all the constants and export them
 from .__internals import PAM_ACCT_EXPIRED
@@ -58,6 +58,9 @@ from .__internals import PAM_USER_UNKNOWN
 from .__internals import PAM_XDISPLAY
 from .__internals import PamAuthenticator
 
+if __sys.version_info < (3, ):  # pragma: no cover
+    print('WARNING, Python 2 is EOL not supported')
+
 __all__ = [
     'authenticate',
     'pam',
@@ -113,17 +116,45 @@ __all__ = [
     'PAM_XDISPLAY',
     ]
 
-__PA = None
 
+def authenticate(
+    username: str | bytes,
+    password: str | bytes,
+    service: str | bytes = 'login',
+    env: dict[str, str] | None = None,
+    call_end: bool = True,
+    encoding: str = 'utf-8',
+    resetcreds: bool = True,
+    print_failure_messages: bool = False,
+) -> bool:
+    """Authenticate a user against PAM.
+
+    Creates a fresh ``PamAuthenticator`` for each call so concurrent use from
+    multiple threads is safe. libpam ctypes bindings are loaded once and shared.
+
+    For result codes after auth, use ``PamAuthenticator`` directly::
 
-def authenticate(*args, **kvargs):
-    global __PA
+        pa = pam.pam()
+        ok = pa.authenticate(user, password)
+        print(pa.code, pa.reason)
 
-    if __PA is None:  # pragma: no branch
-        __PA = PamAuthenticator()
+    Args:
+        username: Username to authenticate
+        password: Password in plain text
+        service: PAM service to authenticate against (default: 'login')
+        env: Dictionary of environment variables to set
+        call_end: Whether to call pam_end() after authentication (default: True)
+        encoding: Encoding to use for string conversions (default: 'utf-8')
+        resetcreds: Whether to reset credentials after authentication (default: True)
+        print_failure_messages: Whether to print failure messages (default: False)
 
-    return __PA.authenticate(*args, **kvargs)
+    Returns:
+        bool: True if authentication succeeded, False otherwise
+    """
+    return PamAuthenticator().authenticate(
+        username, password, service, env, call_end, encoding, resetcreds, print_failure_messages,
+    )
 
 
 # legacy implementations used pam.pam()
-pam = authenticate
+pam = PamAuthenticator  # noqa: N816, C0103

pam/__internals.py

@@ -1,22 +1,30 @@
+"""Internal PAM implementation using ctypes.
+
+This module provides the low-level interface to Linux-PAM using ctypes,
+including structure definitions, constants, and the PamAuthenticator class.
+"""
 import os
-import six
 import sys
-from ctypes import cdll
-from ctypes import CFUNCTYPE
-from ctypes import CDLL
-from ctypes import POINTER
-from ctypes import Structure
-from ctypes import byref
-from ctypes import cast
-from ctypes import sizeof
-from ctypes import py_object
-from ctypes import c_char
-from ctypes import c_char_p
-from ctypes import c_int
-from ctypes import c_size_t
-from ctypes import c_void_p
-from ctypes import memmove
+import threading
+from ctypes import (
+    CDLL,
+    CFUNCTYPE,
+    POINTER,
+    Structure,
+    byref,
+    c_char,
+    c_char_p,
+    c_int,
+    c_size_t,
+    c_void_p,
+    cast,
+    cdll,
+    memmove,
+    py_object,
+    sizeof,
+)
 from ctypes.util import find_library
+from typing import Any
 
 PAM_ABORT = 26
 PAM_ACCT_EXPIRED = 13
@@ -69,6 +77,7 @@ PAM_USER_PROMPT = 9
 PAM_USER_UNKNOWN = 10
 PAM_XDISPLAY = 11
 
+
 __all__ = ('PAM_ABORT', 'PAM_ACCT_EXPIRED', 'PAM_AUTHINFO_UNAVAIL',
            'PAM_AUTHTOK_DISABLE_AGING', 'PAM_AUTHTOK_ERR',
            'PAM_AUTHTOK_EXPIRED', 'PAM_AUTHTOK_LOCK_BUSY',
@@ -105,7 +114,7 @@ class PamMessage(Structure):
     _fields_ = [("msg_style", c_int), ("msg", c_char_p)]
 
     def __repr__(self):
-        return "<PamMessage style: %i, content: %s >" % (self.msg_style, self.msg)
+        return f"<PamMessage style: {self.msg_style}, content: {self.msg} >"
 
 
 class PamResponse(Structure):
@@ -113,7 +122,7 @@ class PamResponse(Structure):
     _fields_ = [("resp", c_char_p), ("resp_retcode", c_int)]
 
     def __repr__(self):
-        return "<PamResponse code: %i, content: %s >" % (self.resp_retcode, self.resp)
+        return f"<PamResponse code: {self.resp_retcode}, content: {self.resp} >"
 
 
 conv_func = CFUNCTYPE(c_int,
@@ -123,23 +132,31 @@ conv_func = CFUNCTYPE(c_int,
                       c_void_p)
 
 
-def my_conv(n_messages, messages, p_response, libc, msg_list: list, password: bytes, encoding: str):
+def my_conv(
+    n_messages: int,
+    messages: Any,  # POINTER(POINTER(PamMessage)) - ctypes types not supported by mypy
+    p_response: Any,  # POINTER(POINTER(PamResponse)) - ctypes types not supported by mypy
+    libc: Any,
+    msg_list: list[str],
+    password: bytes,
+    encoding: str,
+) -> int:
     """Simple conversation function that responds to any
        prompt where the echo is off with the supplied password"""
-    # Create an array of n_messages response objects
-
-    calloc = libc.calloc
-    calloc.restype = c_void_p
-    calloc.argtypes = [c_size_t, c_size_t]
+    # Prefer class-level calloc (configured once); fall back for unit tests that
+    # pass a raw libc.
+    calloc = getattr(PamAuthenticator, 'calloc', None)
+    if calloc is None:  # pragma: no cover
+        calloc = libc.calloc
+        calloc.restype = c_void_p
+        calloc.argtypes = [c_size_t, c_size_t]
 
     cpassword = c_char_p(password)
 
-    '''
-    PAM_PROMPT_ECHO_OFF = 1
-    PAM_PROMPT_ECHO_ON = 2
-    PAM_ERROR_MSG = 3
-    PAM_TEXT_INFO = 4
-    '''
+    # PAM_PROMPT_ECHO_OFF = 1
+    # PAM_PROMPT_ECHO_ON = 2
+    # PAM_ERROR_MSG = 3
+    # PAM_TEXT_INFO = 4
 
     addr = calloc(n_messages, sizeof(PamResponse))
     response = cast(addr, POINTER(PamResponse))
@@ -172,103 +189,155 @@ class PamConv(Structure):
 
 
 class PamAuthenticator:
-    code = 0
-    reason = None
+    """PAM authenticator class.
+
+    Provides methods to authenticate users against Linux-PAM, manage PAM
+    sessions, and handle PAM environment variables.
+
+    Thread safety:
+      - ``pam.authenticate()`` creates a fresh instance per call and is safe
+        for concurrent use (libs are loaded once and shared).
+      - A single ``PamAuthenticator`` instance must not be used from multiple
+        threads at once. For high-QPS auth, prefer ``pam.authenticate()`` or
+        one instance per concurrent caller (default ``call_end=True``).
+      - With ``call_end=False``, the instance owns a live PAM handle for
+        sessions/env; treat that object as single-threaded.
+    """
+
+    # Shared ctypes bindings (immutable after _ensure_libs). Loaded once.
+    _lib_lock = threading.Lock()
+    _libs_ready = False
+    libc: Any = None
+    calloc: Any = None
+    pam_end: Any = None
+    pam_start: Any = None
+    pam_acct_mgmt: Any = None
+    pam_set_item: Any = None
+    pam_setcred: Any = None
+    pam_strerror: Any = None
+    pam_authenticate: Any = None
+    pam_open_session: Any = None
+    pam_close_session: Any = None
+    pam_putenv: Any = None
+    pam_misc_setenv: Any = None
+    pam_getenv: Any = None
+    pam_getenvlist: Any = None
+
+    @classmethod
+    def _ensure_libs(cls) -> None:
+        """Load libpam/libc symbols once for all instances (thread-safe)."""
+        if cls._libs_ready:
+            return
 
-    def __init__(self):
-        # use a trick of dlopen(), this effectively becomes
-        # dlopen("", ...) which opens our own executable. since 'python' has
-        # a libc dependency, this means libc symbols are already available
-        # to us
+        with cls._lib_lock:
+            if cls._libs_ready:
+                return
 
-        # libc = CDLL(find_library("c"))
-        libc = cdll.LoadLibrary(None)
-        self.libc = libc
+            # dlopen("", ...) — python already links libc, so symbols are available
+            libc = cdll.LoadLibrary(None)  # type: ignore[arg-type]
+            libpam = CDLL(find_library("pam"))
+            libpam_misc = CDLL(find_library("pam_misc"))
 
-        libpam = CDLL(find_library("pam"))
-        libpam_misc = CDLL(find_library("pam_misc"))
+            cls.libc = libc
+            cls.calloc = libc.calloc
+            cls.calloc.restype = c_void_p
+            cls.calloc.argtypes = [c_size_t, c_size_t]
 
-        self.handle = None
-        self.messages = []
+            # bug #6 (@NIPE-SYSTEMS), some libpam versions don't include this
+            if hasattr(libpam, 'pam_end'):  # pragma: no branch
+                cls.pam_end = libpam.pam_end
+                cls.pam_end.restype = c_int
+                cls.pam_end.argtypes = [PamHandle, c_int]
+
+            cls.pam_start = libpam.pam_start
+            cls.pam_start.restype = c_int
+            cls.pam_start.argtypes = [c_char_p, c_char_p, POINTER(PamConv),
+                                     POINTER(PamHandle)]
+
+            cls.pam_acct_mgmt = libpam.pam_acct_mgmt
+            cls.pam_acct_mgmt.restype = c_int
+            cls.pam_acct_mgmt.argtypes = [PamHandle, c_int]
+
+            cls.pam_set_item = libpam.pam_set_item
+            cls.pam_set_item.restype = c_int
+            cls.pam_set_item.argtypes = [PamHandle, c_int, c_void_p]
+
+            cls.pam_setcred = libpam.pam_setcred
 
-        self.calloc = libc.calloc
-        self.calloc.restype = c_void_p
-        self.calloc.argtypes = [c_size_t, c_size_t]
-
-        # bug #6 (@NIPE-SYSTEMS), some libpam versions don't include this
-        # function
-        if hasattr(libpam, 'pam_end'):  # pragma: no branch
-            self.pam_end = libpam.pam_end
-            self.pam_end.restype = c_int
-            self.pam_end.argtypes = [PamHandle, c_int]
-
-        self.pam_start = libpam.pam_start
-        self.pam_start.restype = c_int
-        self.pam_start.argtypes = [c_char_p, c_char_p, POINTER(PamConv),
-                                   POINTER(PamHandle)]
-
-        self.pam_acct_mgmt = libpam.pam_acct_mgmt
-        self.pam_acct_mgmt.restype = c_int
-        self.pam_acct_mgmt.argtypes = [PamHandle, c_int]
-
-        self.pam_set_item = libpam.pam_set_item
-        self.pam_set_item.restype = c_int
-        self.pam_set_item.argtypes = [PamHandle, c_int, c_void_p]
-
-        self.pam_setcred = libpam.pam_setcred
-        self.pam_strerror = libpam.pam_strerror
-        self.pam_strerror.restype = c_char_p
-        self.pam_strerror.argtypes = [PamHandle, c_int]
-
-        self.pam_authenticate = libpam.pam_authenticate
-        self.pam_authenticate.restype = c_int
-        self.pam_authenticate.argtypes = [PamHandle, c_int]
-
-        self.pam_open_session = libpam.pam_open_session
-        self.pam_open_session.restype = c_int
-        self.pam_open_session.argtypes = [PamHandle, c_int]
-
-        self.pam_close_session = libpam.pam_close_session
-        self.pam_close_session.restype = c_int
-        self.pam_close_session.argtypes = [PamHandle, c_int]
-
-        self.pam_putenv = libpam.pam_putenv
-        self.pam_putenv.restype = c_int
-        self.pam_putenv.argtypes = [PamHandle, c_char_p]
-
-        if libpam_misc._name:  # pragma: no branch
-            self.pam_misc_setenv = libpam_misc.pam_misc_setenv
-            self.pam_misc_setenv.restype = c_int
-            self.pam_misc_setenv.argtypes = [PamHandle, c_char_p, c_char_p,
-                                             c_int]
-
-        self.pam_getenv = libpam.pam_getenv
-        self.pam_getenv.restype = c_char_p
-        self.pam_getenv.argtypes = [PamHandle, c_char_p]
-
-        self.pam_getenvlist = libpam.pam_getenvlist
-        self.pam_getenvlist.restype = POINTER(c_char_p)
-        self.pam_getenvlist.argtypes = [PamHandle]
+            cls.pam_strerror = libpam.pam_strerror
+            cls.pam_strerror.restype = c_char_p
+            cls.pam_strerror.argtypes = [PamHandle, c_int]
+
+            cls.pam_authenticate = libpam.pam_authenticate
+            cls.pam_authenticate.restype = c_int
+            cls.pam_authenticate.argtypes = [PamHandle, c_int]
+
+            cls.pam_open_session = libpam.pam_open_session
+            cls.pam_open_session.restype = c_int
+            cls.pam_open_session.argtypes = [PamHandle, c_int]
+
+            cls.pam_close_session = libpam.pam_close_session
+            cls.pam_close_session.restype = c_int
+            cls.pam_close_session.argtypes = [PamHandle, c_int]
+
+            cls.pam_putenv = libpam.pam_putenv
+            cls.pam_putenv.restype = c_int
+            cls.pam_putenv.argtypes = [PamHandle, c_char_p]
+
+            # CDLL._name is the loaded library path (empty if unavailable)
+            if getattr(libpam_misc, '_name', None):  # pragma: no branch
+                cls.pam_misc_setenv = libpam_misc.pam_misc_setenv
+                cls.pam_misc_setenv.restype = c_int
+                cls.pam_misc_setenv.argtypes = [PamHandle, c_char_p, c_char_p,
+                                               c_int]
+
+            cls.pam_getenv = libpam.pam_getenv
+            cls.pam_getenv.restype = c_char_p
+            cls.pam_getenv.argtypes = [PamHandle, c_char_p]
+
+            cls.pam_getenvlist = libpam.pam_getenvlist
+            cls.pam_getenvlist.restype = POINTER(c_char_p)
+            cls.pam_getenvlist.argtypes = [PamHandle]
+
+            cls._libs_ready = True
+
+    def __init__(self):
+        self._ensure_libs()
+        # Cheap instance aliases to shared class bindings so callers/tests can
+        # patch per-object and static analyzers see callables on self.
+        cls = self.__class__
+        self.libc = cls.libc
+        self.calloc = cls.calloc
+        self.pam_end = cls.pam_end
+        self.pam_start = cls.pam_start
+        self.pam_acct_mgmt = cls.pam_acct_mgmt
+        self.pam_set_item = cls.pam_set_item
+        self.pam_setcred = cls.pam_setcred
+        self.pam_strerror = cls.pam_strerror
+        self.pam_authenticate = cls.pam_authenticate
+        self.pam_open_session = cls.pam_open_session
+        self.pam_close_session = cls.pam_close_session
+        self.pam_putenv = cls.pam_putenv
+        self.pam_misc_setenv = cls.pam_misc_setenv
+        self.pam_getenv = cls.pam_getenv
+        self.pam_getenvlist = cls.pam_getenvlist
+
+        self.handle: PamHandle | None = None
+        self.messages: list[str] = []
+        self.code: int = 0
+        self.reason: str | bytes | None = None
 
     def authenticate(
-                self,
-                username,
-                password,
-                service='login',
-                env=None,
-                call_end=True,
-                encoding='utf-8',
-                resetcreds=True,
-                print_failure_messages=False):
-        self.pam_authenticate.__annotations = {'username': str,
-                                               'password': str,
-                                               'service': str,
-                                               'env': dict,
-                                               'call_end': bool,
-                                               'encoding': str,
-                                               'resetcreds': bool,
-                                               'return': bool,
-                                               'print_failure_messages': bool}
+        self,
+        username: str | bytes,
+        password: str | bytes,
+        service: str | bytes = 'login',
+        env: dict[str, str] | None = None,
+        call_end: bool = True,
+        encoding: str = 'utf-8',
+        resetcreds: bool = True,
+        print_failure_messages: bool = False,
+    ) -> bool:
         """username and password authentication for the given service.
 
         Returns True for success, or False for failure.
@@ -281,17 +350,22 @@ class PamAuthenticator:
         necessary conversions using the supplied encoding.
 
         Args:
-          username: username to authenticate
-          password: password in plain text
-          service:  PAM service to authenticate against, defaults to 'login'
-          env:      Pam environment variables
-          call_end: call the pam_end() function after (default true)
-          print_failure_messages: Print messages on failure
+          username (str): username to authenticate
+          password (str): password in plain text
+          service (str):  PAM service to authenticate against, defaults to 'login'
+          env (dict):      Pam environment variables
+          call_end (bool): call the pam_end() function after (default true)
+          print_failure_messages (bool): Print messages on failure
 
         Returns:
-          success:  True
+          success:  PAM_SUCCESS
           failure:  False
+
+        Note:
+          Do not call authenticate() on the same instance from multiple threads
+          concurrently. Use ``pam.authenticate()`` for concurrent high-QPS auth.
         """
+        self.messages = []
 
         @conv_func
         def __conv(n_messages, messages, p_response, app_data):
@@ -303,11 +377,11 @@ class PamAuthenticator:
 
             return my_conv(n_messages, messages, p_response, self.libc, msg_list, password, encoding)
 
-        if isinstance(username, six.text_type):
+        if isinstance(username, str):
             username = username.encode(encoding)
-        if isinstance(password, six.text_type):
+        if isinstance(password, str):
             password = password.encode(encoding)
-        if isinstance(service, six.text_type):
+        if isinstance(service, str):
             service = service.encode(encoding)
 
         if b'\x00' in username or b'\x00' in password or b'\x00' in service:
@@ -329,9 +403,16 @@ class PamAuthenticator:
             # This is not an authentication error, something has gone wrong
             # starting up PAM
             self.code = retval
-            self.reason = ("pam_start() failed: %s" %
-                           self.pam_strerror(self.handle, retval))
-            return retval
+            self.reason = f"pam_start() failed: {self.pam_strerror(self.handle, retval)}"
+            self.handle = None
+            return False
+
+        # Verify handle was properly initialized by pam_start
+        if self.handle is None or self.handle.handle == 0:
+            self.code = PAM_SYSTEM_ERR
+            self.reason = "pam_start() succeeded but handle was not properly initialized"
+            self.handle = None
+            return False
 
         # set the TTY, required when pam_securetty is used and the username
         # root is used note: this is only needed WHEN the pam_securetty.so
@@ -352,66 +433,92 @@ class PamAuthenticator:
             ctty = os.ttyname(0)
 
         # ctty can be invalid if no tty is being used
-        if ctty:  # pragma: no branch
-            ctty = c_char_p(ctty.encode(encoding))
+        if ctty:  # pragma: no branch (we don't test a void tty yet)
+            ctty_p = c_char_p(ctty.encode(encoding))
 
-            retval = self.pam_set_item(self.handle, PAM_TTY, ctty)
-            retval = self.pam_set_item(self.handle, PAM_XDISPLAY, ctty)
+            retval = self.pam_set_item(self.handle, PAM_TTY, ctty_p)
+            retval = self.pam_set_item(self.handle, PAM_XDISPLAY, ctty_p)
 
         # Set the environment variables if they were supplied
         if env:
             if not isinstance(env, dict):
                 raise TypeError('"env" must be a dict')
 
+            # Ensure handle is still valid before setting environment variables
+            if self.handle is None or self.handle.handle == 0:
+                self.code = PAM_SYSTEM_ERR
+                self.reason = "PAM handle became invalid before setting environment variables"
+                return False
+
             for key, value in env.items():
                 if isinstance(key, bytes) and b'\x00' in key:
                     raise ValueError('"env{}" key cannot contain NULLs')
                 if isinstance(value, bytes) and b'\x00' in value:
                     raise ValueError('"env{}" value cannot contain NULLs')
 
-                name_value = "{}={}".format(key, value)
+                name_value = f"{key}={value}"
                 retval = self.putenv(name_value, encoding)
 
+        # Ensure handle is still valid before authentication
+        if self.handle is None or self.handle.handle == 0:
+            self.code = PAM_SYSTEM_ERR
+            self.reason = "PAM handle became invalid before authentication"
+            return False
+
         auth_success = self.pam_authenticate(self.handle, 0)
 
-        # skip code coverage, this can only succeed when TEST_* is supplied
-        # in the environment. we ostensibly know it will work
         if auth_success == PAM_SUCCESS:
-            auth_success = self.pam_acct_mgmt(self.handle, 0)  # pragma: no cover
+            # Ensure handle is still valid before account management
+            if self.handle is None or self.handle.handle == 0:
+                self.code = PAM_SYSTEM_ERR
+                self.reason = "PAM handle became invalid before account management"
+                return False
+            auth_success = self.pam_acct_mgmt(self.handle, 0)
 
         if auth_success == PAM_SUCCESS and resetcreds:
-            auth_success = self.pam_setcred(self.handle, PAM_REINITIALIZE_CRED)  # pragma: no cover
+            # Ensure handle is still valid before setting credentials
+            if self.handle is None or self.handle.handle == 0:
+                self.code = PAM_SYSTEM_ERR
+                self.reason = "PAM handle became invalid before setting credentials"
+                return False
+            auth_success = self.pam_setcred(self.handle, PAM_REINITIALIZE_CRED)
 
         # store information to inform the caller why we failed
         self.code = auth_success
-        self.reason = self.pam_strerror(self.handle, auth_success)
-
-        if sys.version_info >= (3,):  # pragma: no branch
-            self.reason = self.reason.decode(encoding)
+        # Ensure handle is still valid before getting error message
+        if self.handle is not None and self.handle.handle != 0:
+            reason_bytes = self.pam_strerror(self.handle, auth_success)
+            if sys.version_info >= (3,):  # pragma: no branch (we don't test non-py3 versions)
+                self.reason = reason_bytes.decode(encoding)
+            else:
+                self.reason = reason_bytes  # type: ignore[assignment]
+        else:
+            self.reason = f"PAM error {auth_success} (handle invalid)"
 
-        if call_end and hasattr(self, 'pam_end'):  # pragma: no branch
+        if call_end and hasattr(self, 'pam_end') and self.pam_end is not None:  # pragma: no branch
             self.pam_end(self.handle, auth_success)
             self.handle = None
 
         if print_failure_messages and self.code != PAM_SUCCESS:  # pragma: no cover
-            print(f"Failure: {self.reason}")
+            reason_str = self.reason if isinstance(self.reason, str) else str(self.reason)
+            print(f"Failure: {reason_str}")
 
-        return auth_success
+        return bool(auth_success == PAM_SUCCESS)
 
-    def end(self):
+    def end(self) -> int:
         """A direct call to pam_end()
         Returns:
           Linux-PAM return value as int
         """
-        if not self.handle or not hasattr(self, 'pam_end'):
+        if not self.handle or self.pam_end is None:
             return PAM_SYSTEM_ERR
 
         retval = self.pam_end(self.handle, self.code)
         self.handle = None
 
-        return retval
+        return int(retval)
 
-    def open_session(self, encoding='utf-8'):
+    def open_session(self, encoding: str = 'utf-8') -> int:
         """Call pam_open_session as required by the pam_api
         Returns:
           Linux-PAM return value as int
@@ -421,14 +528,15 @@ class PamAuthenticator:
 
         retval = self.pam_open_session(self.handle, 0)
         self.code = retval
-        self.reason = self.pam_strerror(self.handle, retval)
-
+        reason_bytes = self.pam_strerror(self.handle, retval)
         if sys.version_info >= (3,):  # pragma: no branch
-            self.reason = self.reason.decode(encoding)
+            self.reason = reason_bytes.decode(encoding)
+        else:
+            self.reason = reason_bytes  # type: ignore[assignment]
 
-        return retval
+        return int(retval)
 
-    def close_session(self, encoding='utf-8'):
+    def close_session(self, encoding: str = 'utf-8') -> int:
         """Call pam_close_session as required by the pam_api
         Returns:
           Linux-PAM return value as int
@@ -438,14 +546,15 @@ class PamAuthenticator:
 
         retval = self.pam_close_session(self.handle, 0)
         self.code = retval
-        self.reason = self.pam_strerror(self.handle, retval)
-
+        reason_bytes = self.pam_strerror(self.handle, retval)
         if sys.version_info >= (3,):  # pragma: no branch
-            self.reason = self.reason.decode(encoding)
+            self.reason = reason_bytes.decode(encoding)
+        else:
+            self.reason = reason_bytes  # type: ignore[assignment]
 
-        return retval
+        return int(retval)
 
-    def misc_setenv(self, name, value, readonly, encoding='utf-8'):
+    def misc_setenv(self, name: str, value: str, readonly: int, encoding: str = 'utf-8') -> int:
         """A wrapper for the pam_misc_setenv function
         Args:
           name: key name of the environment variable
@@ -453,15 +562,16 @@ class PamAuthenticator:
         Returns:
           Linux-PAM return value as int
         """
-        if not self.handle or not hasattr(self, "pam_misc_setenv"):
+        if not self.handle or self.pam_misc_setenv is None:
             return PAM_SYSTEM_ERR
 
-        return self.pam_misc_setenv(self.handle,
-                                    name.encode(encoding),
-                                    value.encode(encoding),
-                                    readonly)
+        retval = self.pam_misc_setenv(self.handle,
+                                      name.encode(encoding),
+                                      value.encode(encoding),
+                                      readonly)
+        return int(retval)
 
-    def putenv(self, name_value, encoding='utf-8'):
+    def putenv(self, name_value: str, encoding: str = 'utf-8') -> int:
         """A wrapper for the pam_putenv function
         Args:
           name_value: environment variable in the format KEY=VALUE
@@ -472,46 +582,61 @@ class PamAuthenticator:
         if not self.handle:
             return PAM_SYSTEM_ERR
 
-        name_value = name_value.encode(encoding)
+        name_value_bytes = name_value.encode(encoding)
 
-        retval = self.pam_putenv(self.handle, name_value)
+        retval = self.pam_putenv(self.handle, name_value_bytes)
         if retval != PAM_SUCCESS:
-            raise Exception(self.pam_strerror(self.handle, retval))
+            error_msg_bytes = self.pam_strerror(self.handle, retval)
+            if sys.version_info >= (3,):  # pragma: no branch
+                error_msg = error_msg_bytes.decode(encoding)
+            else:
+                error_msg = error_msg_bytes  # type: ignore[assignment]
+            raise RuntimeError(error_msg)
 
-        return retval
+        return int(retval)
 
-    def getenv(self, key, encoding='utf-8'):
+    def getenv(self, key: str | bytes, encoding: str = 'utf-8') -> str | None | int:
         """A wrapper for the pam_getenv function
         Args:
           key name of the environment variable
         Returns:
-          value of the environment variable or None on error
+          value of the environment variable, None on error, or PAM_SYSTEM_ERR if handle is invalid
         """
         if not self.handle:
             return PAM_SYSTEM_ERR
 
         #  can't happen unless someone is using internals directly
-        if sys.version_info >= (3, ):  # pragma: no branch
-            if isinstance(key, six.text_type):  # pragma: no branch
-                key = key.encode(encoding)
+        if isinstance(key, str):  # pragma: no branch
+            key = key.encode(encoding)
 
         value = self.pam_getenv(self.handle, key)
 
         if isinstance(value, type(None)):
-            return
+            return None
 
         if isinstance(value, int):  # pragma: no cover
-            raise Exception(self.pam_strerror(self.handle, value))
+            error_msg = self.pam_strerror(self.handle, value)
+            if sys.version_info >= (3,):  # pragma: no branch
+                error_msg = error_msg.decode(encoding)
+            raise RuntimeError(error_msg)
 
         if sys.version_info >= (3,):  # pragma: no branch
-            value = value.decode(encoding)
-
-        return value
-
-    def getenvlist(self, encoding='utf-8'):
+            if isinstance(value, bytes):
+                return value.decode(encoding)
+            # value is c_char_p which is bytes-like, but mypy doesn't know
+            # c_char_p can be None, bytes, or int, but in practice it's bytes here
+            # We've already checked for None and bytes, so this should be safe
+            # At this point value should be bytes (c_char_p), but mypy sees it as Any
+            # Since we've checked for None and bytes, the remaining case is safe
+            return str(value)
+        # Python 2 path (not tested) - value is bytes in py2
+        # This path is never executed in Python 3, so mypy doesn't see the error
+        return str(value)
+
+    def getenvlist(self, encoding: str = 'utf-8') -> dict[str, str] | int:
         """A wrapper for the pam_getenvlist function
         Returns:
-          environment as python dictionary
+          environment as python dictionary, or PAM_SYSTEM_ERR if handle is invalid
         """
         if not self.handle:
             return PAM_SYSTEM_ERR

pam/pam.py

@@ -30,24 +30,24 @@ a user against the Pluggable Authentication Modules (PAM) on the system.
 Implemented using ctypes, so no compilation is necessary.
 '''
 
-import six
-import __internals
+from . import __internals
 
 if __name__ == "__main__":  # pragma: no cover
     import readline
     import getpass
 
     def input_with_prefill(prompt, text):
+        """Input function with prefilled text."""
         def hook():
             readline.insert_text(text)
             readline.redisplay()
 
         readline.set_pre_input_hook(hook)
-        result = six.moves.input(prompt)  # nosec (bandit; python2)
+        user_input = input(prompt)  # nosec (bandit; python2)
 
         readline.set_pre_input_hook()
 
-        return result
+        return user_input
 
     __pam = __internals.PamAuthenticator()
 
@@ -58,23 +58,30 @@ if __name__ == "__main__":  # pragma: no cover
     result = __pam.authenticate(username, getpass.getpass(),
                                 env={"XDG_SEAT": "seat0"},
                                 call_end=False)
-    print('Auth result: {} ({})'.format(__pam.reason, __pam.code))
+    reason_str = __pam.reason if isinstance(__pam.reason, str) else str(__pam.reason)
+    print(f'Auth result: {reason_str} ({__pam.code})')
 
     env_list = __pam.getenvlist()
-    for key, value in env_list.items():
-        print("Pam Environment List item: {}={}".format(key, value))
+    if isinstance(env_list, dict):
+        for key, value in env_list.items():
+            print(f"Pam Environment List item: {key}={value}")
 
     key = "XDG_SEAT"
-    value = __pam.getenv(key)
-    print("Pam Environment item: {}={}".format(key, value))
+    env_value = __pam.getenv(key)
+    if env_value is not None:
+        print(f"Pam Environment item: {key}={env_value}")
+    else:
+        print(f"Pam Environment item: {key}=None")
 
     if __pam.code == __internals.PAM_SUCCESS:
-        result = __pam.open_session()
-        print('Open session: {} ({})'.format(__pam.reason, __pam.code))
+        session_result = __pam.open_session()
+        session_reason = __pam.reason if isinstance(__pam.reason, str) else str(__pam.reason)
+        print(f'Open session: {session_reason} ({__pam.code})')
 
         if __pam.code == __internals.PAM_SUCCESS:
-            result = __pam.close_session()
-            print('Close session: {} ({})'.format(__pam.reason, __pam.code))
+            close_result = __pam.close_session()
+            close_reason = __pam.reason if isinstance(__pam.reason, str) else str(__pam.reason)
+            print(f'Close session: {close_reason} ({__pam.code})')
 
         else:
             __pam.end()

pam/version.py

@@ -1,3 +1,4 @@
-VERSION = '2.0.0'
+"""Version information for python-pam package."""
+VERSION = '2.1.0'
 AUTHOR = 'David Ford <david.ford@blue-labs.org>'
-RELEASED = '2022 March 10'
+RELEASED = '2026 September 16'

python_pam-2.1.0.dist-info/METADATA

@@ -0,0 +1,137 @@
+Metadata-Version: 2.4
+Name: python-pam
+Version: 2.1.0
+Summary: 
+License-File: LICENSE
+Author: David Ford
+Author-email: david@blue-labs.org
+Requires-Python: >=3.11
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Description-Content-Type: text/markdown
+
+# python-pam
+
+[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/FirefighterBlu3/python-pam/badge)](https://scorecard.dev/viewer/?uri=github.com/FirefighterBlu3/python-pam)
+[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/13794/badge)](https://www.bestpractices.dev/projects/13794)
+
+Python pam module supporting py3 for Linux type systems (!windows)
+
+## Security
+
+See [SECURITY.md](SECURITY.md) for supported versions and how to report vulnerabilities.
+
+## Threading and concurrency
+
+`pam.authenticate()` is safe to call from many threads at once. Each call uses
+its own PAM handle; libpam ctypes bindings are loaded once and shared (no global
+lock on the auth path).
+
+Do **not** share a single `PamAuthenticator` / `pam.pam()` instance across threads
+without external synchronization. That object owns mutable PAM session state
+(`handle`, `code`, `reason`, `messages`). For sessions (`call_end=False`), keep
+one instance per thread (or serialize access).
+
+High-QPS login APIs should use:
+
+```python
+import pam
+
+if pam.authenticate(username, password, service='myapp'):
+    ...
+```
+
+## Credentials (`resetcreds`)
+
+After a successful `pam_authenticate` + `pam_acct_mgmt`, `authenticate()` calls
+`pam_setcred(..., PAM_REINITIALIZE_CRED)` when `resetcreds=True` (the default).
+
+**Keep the default (`True`)** when this process is acting like a login / credential
+handoff: modules may establish or refresh credentials (e.g. Kerberos), and you care
+about that step succeeding as part of auth.
+
+**Set `resetcreds=False`** when you only need to verify a username/password (typical
+web/API “is this password valid?” checks). You are not assuming the user’s identity
+or opening a session; skipping setcred avoids extra module work and avoids treating a
+setcred failure as an authentication failure.
+
+```python
+# Password check only
+pam.authenticate(user, password, service='myapp', resetcreds=False)
+
+# Login-style / credential-aware stack (default)
+pam.authenticate(user, password, service='login')
+```
+
+## Examples
+
+Commandline example:
+
+```bash
+[david@Scott python-pam]$ python pam/pam.py
+Username: david
+Password:
+Auth result: Success (0)
+Pam Environment List item: XDG_SEAT=seat0
+Pam Environment item: XDG_SEAT=seat0
+Missing Pam Environment item: asdf=None
+Open session: Success (0)
+Close session: Success (0)
+```
+
+Inline examples:
+
+```python
+>>> import pam
+>>> pam.authenticate('david', 'correctpassword')
+True
+>>> p = pam.pam()
+>>> p.authenticate('david', 'correctpassword')
+True
+>>> p.authenticate('david', 'badpassword')
+False
+>>> p.authenticate('david', 'correctpassword', service='login')
+True
+>>> p.authenticate('david', 'correctpassword', service='unknownservice')
+False
+>>> p.authenticate('david', 'correctpassword', service='login', resetcreds=True)
+True
+>>> p.authenticate('david', 'correctpassword', encoding='latin-1')
+True
+>>> print('{} {}'.format(p.code, p.reason))
+0 Success
+>>> p.authenticate('david', 'badpassword')
+False
+>>> print('{} {}'.format(p.code, p.reason))
+7 Authentication failure
+>>>
+```
+
+## Authentication and privileges
+Please note, python-pam and *all* tools that do authentication follow two rules:
+
+* You have root (or privileged access): you can check any account's password for validity
+* You don't have root: you can only check the validity of the username running the tool
+
+If you need to authenticate multiple users, you must use an authentication stack that at some stage has privileged access. On Linux systems one example of doing this is using SSSD.
+
+Typical Linux installations check against `/etc/shadow` with `pam_unix.so` which will spawn `/usr/bin/unix_chkpwd` to verify the password. Both of these are intentionally written to meet the above two rules. You can test the functionality of `unix_chkpwd` in the following manner:
+
+Replace `good` with the correct password, replace `david` with your appropriate username.
+
+```
+~$ mkfifo /tmp/myfifo
+
+~$ (echo -ne 'good\0' > /tmp/myfifo & /usr/bin/unix_chkpwd david nullok < /tmp/myfifo ) ; echo $?
+0
+
+~$ (echo -ne 'bad\0' > /tmp/myfifo & /usr/bin/unix_chkpwd david nullok < /tmp/myfifo ) ; echo $?
+7
+
+~$ (echo -ne 'good\0' > /tmp/myfifo & /usr/bin/unix_chkpwd someotheruser nullok < /tmp/myfifo ) ; echo $?
+9
+```
+

python_pam-2.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+pam/__init__.py,sha256=6uTNelMCu1yx2m4l0j-SShRRHpgzDUkZ3mYWP5o5guE,5165
+pam/__internals.py,sha256=lsR_9b3EW8EpjywL_mwv58KokeOqMdHux2z_g_Qt734,24596
+pam/pam.py,sha256=_7vWm5YUWSk9-QRdeVSpej8km6h36qYoa_EmpW2aUac,2974
+pam/version.py,sha256=XCnpkS4zsVVwvnbPaAebfpXmy69grDiOLK8EVWFGZa8,148
+python_pam-2.1.0.dist-info/METADATA,sha256=ZXCERT3F0X6N2FJbkA_-mCj0YxIoeQyli15r9iByQtw,4699
+python_pam-2.1.0.dist-info/WHEEL,sha256=EGEvSphFYqXKs23-kQBeyNoJP1nrT8ZJKQoi5p5DYL8,88
+python_pam-2.1.0.dist-info/licenses/LICENSE,sha256=-B9Dx4t8RlyTldHuUNiV6WYgeXvO0LBO7-C5u9p-HW8,1077
+python_pam-2.1.0.dist-info/RECORD,,

{python_pam-2.0.0.dist-info → python_pam-2.1.0.dist-info}/WHEEL

@@ -1,5 +1,4 @@
 Wheel-Version: 1.0
-Generator: bdist_wheel (0.37.1)
+Generator: poetry-core 2.4.0
 Root-Is-Purelib: true
 Tag: py3-none-any
-

python_pam-2.0.0.dist-info/METADATA

@@ -1,100 +0,0 @@
-Metadata-Version: 2.1
-Name: python-pam
-Version: 2.0.0
-Summary: Python PAM module using ctypes, py3
-Home-page: https://github.com/FirefighterBlu3/python-pam
-Author: David Ford
-Author-email: david@blue-labs.org
-License: License :: OSI Approved :: MIT License
-Project-URL: Bug Tracker, https://github.com/FirefighterBlu3/python-pam/issues
-Platform: UNKNOWN
-Classifier: Development Status :: 6 - Mature
-Classifier: Environment :: Plugins
-Classifier: Intended Audience :: Developers
-Classifier: Intended Audience :: Information Technology
-Classifier: Intended Audience :: System Administrators
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Operating System :: POSIX
-Classifier: Operating System :: POSIX :: Linux
-Classifier: Programming Language :: Python
-Classifier: Programming Language :: Python :: 2
-Classifier: Programming Language :: Python :: 3
-Classifier: Topic :: Security
-Classifier: Topic :: System :: Systems Administration :: Authentication/Directory
-Description-Content-Type: text/markdown
-License-File: LICENSE
-
-# python-pam
-
-Python pam module supporting py3 (and py2) for Linux type systems (!windows)
-
-Commandline example:
-
-```bash
-[david@Scott python-pam]$ python pam/pam.py
-Username: david
-Password:
-Auth result: Success (0)
-Pam Environment List item: XDG_SEAT=seat0
-Pam Environment item: XDG_SEAT=seat0
-Missing Pam Environment item: asdf=None
-Open session: Success (0)
-Close session: Success (0)
-```
-
-Inline examples:
-
-```python
-[david@Scott python-pam]$ python
-Python 3.9.7 (default, Oct 10 2021, 15:13:22)
-[GCC 11.1.0] on linux
-Type "help", "copyright", "credits" or "license" for more information.
->>> import pam
->>> p = pam.authenticate()
->>> p.authenticate('david', 'correctpassword')
-True
->>> p.authenticate('david', 'badpassword')
-False
->>> p.authenticate('david', 'correctpassword', service='login')
-True
->>> p.authenticate('david', 'correctpassword', service='unknownservice')
-False
->>> p.authenticate('david', 'correctpassword', service='login', resetcreds=True)
-True
->>> p.authenticate('david', 'correctpassword', encoding='latin-1')
-True
->>> print('{} {}'.format(p.code, p.reason))
-0 Success
->>> p.authenticate('david', 'badpassword')
-False
->>> print('{} {}'.format(p.code, p.reason))
-7 Authentication failure
->>>
-```
-
-## Authentication and privileges
-Please note, python-pam and *all* tools that do authentication follow two rules:
-
-* You have root (or privileged access): you can check any account's password for validity
-* You don't have root: you can only check the validity of the username running the tool
-
-If you need to authenticate multiple users, you must use an authentication stack that at some stage has privileged access. On Linux systems one example of doing this is using SSSD.
-
-Typical Linux installations check against `/etc/shadow` with `pam_unix.so` which will spawn `/usr/bin/unix_chkpwd` to verify the password. Both of these are intentionally written to meet the above two rules. You can test the functionality of `unix_chkpwd` in the following manner:
-
-Replace `good` with the correct password, replace `david` with your appropriate username.
-
-```
-~$ mkfifo /tmp/myfifo
-
-~$ (echo -ne 'good\0' > /tmp/myfifo & /usr/bin/unix_chkpwd david nullok < /tmp/myfifo ) ; echo $?
-0
-
-~$ (echo -ne 'bad\0' > /tmp/myfifo & /usr/bin/unix_chkpwd david nullok < /tmp/myfifo ) ; echo $?
-7
-
-~$ (echo -ne 'good\0' > /tmp/myfifo & /usr/bin/unix_chkpwd someotheruser nullok < /tmp/myfifo ) ; echo $?
-9
-```
-
-

python_pam-2.0.0.dist-info/RECORD

@@ -1,9 +0,0 @@
-pam/__init__.py,sha256=iZGiYU7xldTb15b1P94TbAb3wgUY0SXZBp9Olac8UW4,3824
-pam/__internals.py,sha256=Ay6iGazs1m_aio_wMzDezrzaJ8MbLmLLCw6GGEnyJNY,18791
-pam/pam.py,sha256=nV_3zY6C58u4xLZ4RqrTNZGvUd-HjJ9Kik3CCY_I8K0,2544
-pam/version.py,sha256=o9vrEmrkcCr3Tsbg3NlSajeyTQY9hVEcxpanvPksQwo,94
-python_pam-2.0.0.dist-info/LICENSE,sha256=-B9Dx4t8RlyTldHuUNiV6WYgeXvO0LBO7-C5u9p-HW8,1077
-python_pam-2.0.0.dist-info/METADATA,sha256=VHjCQV_jZO_SlmQkuqW4WVkgpd2EE9MzFJHkFVDWlfI,3454
-python_pam-2.0.0.dist-info/WHEEL,sha256=G16H4A3IeoQmnOrYV4ueZGKSjhipXx8zc8nu9FGlvMA,92
-python_pam-2.0.0.dist-info/top_level.txt,sha256=0EOjbyc3hQyzjhn6iyMgsEseqA66Xz0p27iBN7G7W1w,4
-python_pam-2.0.0.dist-info/RECORD,,

python_pam-2.0.0.dist-info/top_level.txt

@@ -1 +0,0 @@
-pam