From: Lennart Poettering <lennart@poettering.net>
Date: Mon, 24 Feb 2025 14:17:22 +0000 (+0100)
Subject: pam_systemd_home: update comment
X-Git-Tag: v258-rc1~1243^2~6
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=5856e869bbf6a9522b4cc67a326d108f2950174b;p=thirdparty%2Fsystemd.git

pam_systemd_home: update comment

Follow-up for 563c5511ad0dd8763eaff75db1967249f662f844, which turned
boolean parameters into flags.
---

diff --git a/src/home/pam_systemd_home.c b/src/home/pam_systemd_home.c
index 9e54971d23c..dcb85adc61d 100644
--- a/src/home/pam_systemd_home.c
+++ b/src/home/pam_systemd_home.c
@@ -553,24 +553,24 @@ static int acquire_home(
 
         /* This acquires a reference to a home directory in the following ways:
          *
-         * 1. If please_authenticate is false, it tries to call RefHome() first — which
-         *    will get us a reference to the home without authentication (which will work for homes that are
-         *    not encrypted, or that already are activated). If this works, we are done. Yay!
+         * 1. If ACQUIRE_MUST_AUTHENTICATE is not set, it tries to call RefHome() first — which will get us a
+         *    reference to the home without authentication (which will work for homes that are not encrypted,
+         *    or that already are activated). If this works, we are done. Yay!
          *
          * 2. Otherwise, we'll call AcquireHome() — which will try to activate the home getting us a
          *    reference. If this works, we are done. Yay!
          *
-         * 3. if ref_anyway, we'll call RefHomeUnrestricted() — which will give us a reference in any case
-         *    (even if the activation failed!).
+         * 3. if ACQUIRE_REF_ANYWAY is set, we'll call RefHomeUnrestricted() — which will give us a reference
+         *    in any case (even if the activation failed!).
          *
-         * The idea is that please_authenticate is set to false for the PAM session hooks (since for those
-         * authentication doesn't matter), and true for the PAM authentication hooks (since for those
-         * authentication is essential). And ref_anyway should be set if we are pretty sure that we can later
-         * activate the home directory via our fallback shell logic, and hence are OK if we can't activate
-         * things here. Usecase for that are SSH logins where SSH does the authentication and thus only the
-         * session hooks are called. But from the session hooks SSH doesn't allow asking questions, hence we
-         * simply allow the login attempt to continue but then invoke our fallback shell that will prompt the
-         * user for the missing unlock credentials, and then chainload the real shell.
+         * The idea is that ACQUIRE_MUST_AUTHENTICATE is off for the PAM session hooks (since for those
+         * authentication doesn't matter), and on for the PAM authentication hooks (since for those
+         * authentication is essential). And ACQUIRE_REF_ANYWAY should be set if we are pretty sure that we
+         * can later activate the home directory via our fallback shell logic, and hence are OK if we can't
+         * activate things here. Usecase for that are SSH logins where SSH does the authentication and thus
+         * only the session hooks are called. But from the session hooks SSH doesn't allow asking questions,
+         * hence we simply allow the login attempt to continue but then invoke our fallback shell that will
+         * prompt the user for the missing unlock credentials, and then chainload the real shell.
          */
 
         r = pam_get_user(handle, &username, NULL);