python-pam 2.0.0__tar.gz → 2.1.0__tar.gz

python_pam-2.1.0/PKG-INFO

@@ -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.0.0/src/python_pam.egg-info/PKG-INFO → python_pam-2.1.0/README.md

@@ -1,32 +1,57 @@
-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)
+[![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:
 
@@ -45,12 +70,10 @@ 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()
+>>> pam.authenticate('david', 'correctpassword')
+True
+>>> p = pam.pam()
 >>> p.authenticate('david', 'correctpassword')
 True
 >>> p.authenticate('david', 'badpassword')
@@ -96,5 +119,3 @@ Replace `good` with the correct password, replace `david` with your appropriate
 ~$ (echo -ne 'good\0' > /tmp/myfifo & /usr/bin/unix_chkpwd someotheruser nullok < /tmp/myfifo ) ; echo $?
 9
 ```
-
-

python_pam-2.1.0/pyproject.toml

@@ -0,0 +1,92 @@
+[project]
+name = "python-pam"
+version = "2.1.0"
+description = ""
+authors = [{name = "David Ford", email = "david@blue-labs.org"}]
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = []
+
+#[project.scripts]
+#lint = "pylint"
+#test = "pytest"
+
+[tool.poetry]
+packages = [{include = "pam", from = "python-pam"}]
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^9.1.1"
+pytest-cov = "^7.1.0"
+pylint = "^4.0.8"
+tox = "^4.61.4"
+bandit = "*"
+mypy = ">=2.3.1,<3"
+
+[tool.poetry.group.test.dependencies]
+pytest = "^9.1.1"
+pytest-cov = "^7.1.0"
+pytest-env = "^1.7.1"
+tox = ">=4.61.4,<5"
+flake8 = "*"
+pylint = ">=4.0.8,<5"
+
+[tool.coverage.run]
+source = ["pam"]
+omit = ["*/tests/*", "*/test_*.py"]
+
+[tool.coverage.report]
+precision = 2
+show_missing = true
+skip_covered = false
+fail_under = 85.0
+
+[tool.bandit]
+exclude_dirs = ["./venv", "./test", ]
+recursive = true
+
+[tool.pylint.main]
+jobs = 0
+
+[tool.pylint.format]
+max-line-length = 120
+
+[tool.pylint."messages control"]
+disable = [
+    "too-many-arguments",
+    "too-many-positional-arguments",
+    "too-many-branches",
+    "too-many-statements",
+    "too-many-return-statements",
+    "too-many-locals",
+    "too-many-instance-attributes",
+    "too-few-public-methods",
+    "wrong-import-position",  # Imports are intentionally after version check
+    # ctypes symbols are assigned at runtime in PamAuthenticator._ensure_libs
+    "not-callable",
+]
+
+[tool.mypy]
+python_version = "3.12"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = false
+disallow_incomplete_defs = false
+check_untyped_defs = true
+no_implicit_optional = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+warn_no_return = true
+strict_equality = true
+ignore_missing_imports = true
+files = ["python-pam/pam"]
+
+[[tool.mypy.overrides]]
+module = [
+    "ctypes.*",
+    "ctypes.util.*",
+]
+ignore_missing_imports = true
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"

{python-pam-2.0.0/src → python_pam-2.1.0/python-pam}/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