From 307ffd3c57ced7150851f62158b91e9c0f726ff6 Mon Sep 17 00:00:00 2001
From: Alex Rodin <alex.rodin@sas.com>
Date: Tue, 10 Dec 2019 10:32:04 -0500
Subject: [PATCH] Update pam_sss.8.xml

pam_sss: Added return values on a man page

Resolves: https://pagure.io/SSSD/sssd/issue/3672
---
 src/man/pam_sss.8.xml | 198 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 198 insertions(+)

diff --git a/src/man/pam_sss.8.xml b/src/man/pam_sss.8.xml
index 834d9d2683..cc20e51616 100644
--- a/src/man/pam_sss.8.xml
+++ b/src/man/pam_sss.8.xml
@@ -262,6 +262,204 @@ auth sufficient pam_sss.so allow_missing_name
         from other sources during access control.</para>
     </refsect1>
 
+    <refsect1 id="return_values">
+        <title>RETURN VALUES</title>
+        <variablelist>
+            <varlistentry>
+                <term>PAM_SUCCESS</term>
+                <listitem>
+                    <para>
+                        The PAM operation finished successfully.
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>PAM_USER_UNKNOWN</term>
+                <listitem>
+                    <para>
+                        The user is not known to the authentication service or
+                        the SSSD's PAM responder is not running.
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>PAM_AUTH_ERR</term>
+                <listitem>
+                    <para>
+                        Authentication failure. Also, could be returned when there
+                        is a problem with getting the certificate.
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>PAM_PERM_DENIED</term>
+                <listitem>
+                    <para>
+                        Permission denied. The SSSD log files may contain additional
+                        information about the error.
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>PAM_IGNORE</term>
+                <listitem>
+                    <para>
+                        See options <option>ignore_unknown_user</option> and
+                        <option>ignore_authinfo_unavail</option>.
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>PAM_AUTHTOK_ERR</term>
+                <listitem>
+                    <para>
+                        Unable to obtain the new authentication token. Also, could be
+                        returned when the user authenticates with certificates and
+                        multiple certificates are available, but the installed version
+                        of GDM does not support selection from multiple certificates.
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>PAM_AUTHINFO_UNAVAIL</term>
+                <listitem>
+                    <para>
+                        Unable to access the authentication information.
+                        This might be due to a network or hardware failure.
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>PAM_BUF_ERR</term>
+                <listitem>
+                    <para>
+                        A memory error occurred. Also, could be returned when options
+                        use_first_pass or use_authtok were set, but no password was
+                        found from the previously stacked PAM module.
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>PAM_SYSTEM_ERR</term>
+                <listitem>
+                    <para>
+                        A system error occurred. The SSSD log files may contain additional
+                        information about the error.
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>PAM_CRED_ERR</term>
+                <listitem>
+                    <para>
+                        Unable to set the credentials of the user.
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>PAM_CRED_INSUFFICIENT</term>
+                <listitem>
+                    <para>
+                        The application does not have sufficient credentials
+                        to authenticate the user. For example, missing PIN during
+                        smartcard authentication or missing factor during
+                        two-factor authentication.
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>PAM_SERVICE_ERR</term>
+                <listitem>
+                    <para>
+                        Error in service module.
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>PAM_NEW_AUTHTOK_REQD</term>
+                <listitem>
+                    <para>
+                        The user's authentication token has expired.
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>PAM_ACCT_EXPIRED</term>
+                <listitem>
+                    <para>
+                        The user account has expired.
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>PAM_SESSION_ERR</term>
+                <listitem>
+                    <para>
+                        Unable to fetch IPA Desktop Profile rules or user info.
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>PAM_CRED_UNAVAIL</term>
+                <listitem>
+                    <para>
+                        Unable to retrieve Kerberos user credentials.
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>PAM_NO_MODULE_DATA</term>
+                <listitem>
+                    <para>
+                        No authentication method was found by Kerberos.
+                        This might happen if the user has a Smartcard assigned but
+                        the pkint plugin is not available on the client.
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>PAM_CONV_ERR</term>
+                <listitem>
+                    <para>
+                       Conversation failure.
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>PAM_AUTHTOK_LOCK_BUSY</term>
+                <listitem>
+                    <para>
+                       No KDC suitable for password change is available.
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>PAM_ABORT</term>
+                <listitem>
+                    <para>
+                       Unknown PAM call.
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>PAM_MODULE_UNKNOWN</term>
+                <listitem>
+                    <para>
+                       Unsupported PAM task or command.
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>PAM_BAD_ITEM</term>
+                <listitem>
+                    <para>
+                       The authentication module cannot handle Smartcard credentials.
+                    </para>
+                </listitem>
+            </varlistentry>
+        </variablelist>
+    </refsect1>
+
     <refsect1 id='files'>
         <title>FILES</title>
         <para>If a password reset by root fails, because the corresponding SSSD
