From 20c61d3cef60ba542823b2bd8282fb67310f2912 Mon Sep 17 00:00:00 2001 From: David Ford Date: Sun, 26 Jul 2026 02:37:26 -0400 Subject: [PATCH] docs: explain resetcreds default vs password-check-only use Clarify when to keep pam_setcred (login-style) and when resetcreds=False is appropriate for verify-only callers (#52). Co-authored-by: Cursor --- ChangeLog.md | 1 + README.md | 22 ++++++++++++++++++++++ 2 files changed, 23 insertions(+) diff --git a/ChangeLog.md b/ChangeLog.md index 38faf4b..d2ccdba 100644 --- a/ChangeLog.md +++ b/ChangeLog.md @@ -11,6 +11,7 @@ `PamAuthenticator` (thread-safe concurrent auth); libpam ctypes bindings are loaded once and shared for performance - document threading model (do not share one `PamAuthenticator` across threads) + - document when to use `resetcreds=True` vs `False` (#52) ## 2.0.2 Latest March 17, 2022 diff --git a/README.md b/README.md index d0e21de..5cbcec7 100644 --- a/README.md +++ b/README.md @@ -29,6 +29,28 @@ 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: