Adding upstream version 1.3.1.upstream/1.3.1upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 185 insertions, 0 deletions

diff --git a/doc/man/pam_sm_setcred.3.xml b/doc/man/pam_sm_setcred.3.xml
new file mode 100644
index 0000000..5cfe899
--- /dev/null
+++ b/doc/man/pam_sm_setcred.3.xml
@@ -0,0 +1,185 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+                   "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
+<refentry id='pam_sm_setcred'>
+  <refmeta>
+    <refentrytitle>pam_sm_setcred</refentrytitle>
+    <manvolnum>3</manvolnum>
+    <refmiscinfo class='setdesc'>Linux-PAM Manual</refmiscinfo>
+  </refmeta>
+
+  <refnamediv id="pam_sm_setcred-name">
+    <refname>pam_sm_setcred</refname>
+    <refpurpose>PAM service function to alter credentials</refpurpose>
+  </refnamediv>
+
+<!-- body begins here -->
+
+  <refsynopsisdiv>
+    <funcsynopsis id='pam_sm_setcred-synopsis'>
+      <funcsynopsisinfo>#define PAM_SM_AUTH</funcsynopsisinfo>
+      <funcsynopsisinfo>#include &lt;security/pam_modules.h&gt;</funcsynopsisinfo>
+      <funcprototype>
+        <funcdef>int <function>pam_sm_setcred</function></funcdef>
+        <paramdef>pam_handle_t *<parameter>pamh</parameter></paramdef>
+        <paramdef>int <parameter>flags</parameter></paramdef>
+        <paramdef>int <parameter>argc</parameter></paramdef>
+        <paramdef>const char **<parameter>argv</parameter></paramdef>
+      </funcprototype>
+    </funcsynopsis>
+  </refsynopsisdiv>
+
+
+  <refsect1 id='pam_sm_setcred-description'>
+    <title>DESCRIPTION</title>
+    <para>
+      The <function>pam_sm_setcred</function> function is the service
+      module's implementation of the
+      <citerefentry>
+        <refentrytitle>pam_setcred</refentrytitle><manvolnum>3</manvolnum>
+      </citerefentry> interface.
+    </para>
+    <para>
+      This function performs the task of altering the credentials of the
+      user with respect to the corresponding authorization
+      scheme. Generally, an authentication module may have access to more
+      information about a user than their authentication token. This
+      function is used to make such information available to the
+      application. It should only be called <emphasis>after</emphasis> the
+      user has been authenticated but before a session has been established.
+    </para>
+    <para>
+       Valid flags, which may be logically OR'd with
+       <emphasis>PAM_SILENT</emphasis>, are:
+    </para>
+    <variablelist>
+      <varlistentry>
+        <term>PAM_SILENT</term>
+        <listitem>
+           <para>
+             Do not emit any messages.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>PAM_ESTABLISH_CRED</term>
+        <listitem>
+          <para>Initialize the credentials for the user.</para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>PAM_DELETE_CRED</term>
+        <listitem>
+          <para>
+            Delete the credentials associated with the authentication service.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>PAM_REINITIALIZE_CRED</term>
+        <listitem>
+          <para>
+            Reinitialize the user credentials.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>PAM_REFRESH_CRED</term>
+        <listitem>
+          <para>
+            Extend the lifetime of the user credentials.
+          </para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+    <para>
+      The way the <emphasis remap='B'>auth</emphasis> stack is
+      navigated in order to evaluate the <function>pam_setcred</function>()
+      function call, independent of the <function>pam_sm_setcred</function>()
+      return codes, is exactly the same way that it was navigated when
+      evaluating the <function>pam_authenticate</function>() library
+      call. Typically, if a stack entry was ignored in evaluating
+      <function>pam_authenticate</function>(), it will be ignored when
+      libpam evaluates the <function>pam_setcred</function>() function
+      call. Otherwise, the return codes from each module specific
+      <function>pam_sm_setcred</function>() call are treated as
+      <emphasis remap='B'>required</emphasis>.
+    </para>
+  </refsect1>
+
+  <refsect1 id="pam_sm_setcred-return_values">
+    <title>RETURN VALUES</title>
+    <variablelist>
+      <varlistentry>
+        <term>PAM_CRED_UNAVAIL</term>
+        <listitem>
+          <para>
+            This module cannot retrieve the user's credentials.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>PAM_CRED_EXPIRED</term>
+        <listitem>
+          <para>
+            The user's credentials have expired.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>PAM_CRED_ERR</term>
+        <listitem>
+          <para>
+            This module was unable to set the credentials of the user.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>PAM_SUCCESS</term>
+        <listitem>
+           <para>
+             The user credential was successfully set.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>PAM_USER_UNKNOWN</term>
+        <listitem>
+          <para>
+            The user is not known to this authentication module.
+          </para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+    <para>
+      These, non-<emphasis>PAM_SUCCESS</emphasis>, return values will
+      typically lead to the credential stack <emphasis>failing</emphasis>.
+      The first such error will dominate in the return value of
+      <function>pam_setcred</function>().
+    </para>
+  </refsect1>
+
+  <refsect1 id='pam_sm_setcred-see_also'>
+    <title>SEE ALSO</title>
+    <para>
+      <citerefentry>
+        <refentrytitle>pam</refentrytitle><manvolnum>3</manvolnum>
+      </citerefentry>,
+      <citerefentry>
+        <refentrytitle>pam_authenticate</refentrytitle><manvolnum>3</manvolnum>
+      </citerefentry>,
+      <citerefentry>
+        <refentrytitle>pam_setcred</refentrytitle><manvolnum>3</manvolnum>
+      </citerefentry>,
+      <citerefentry>
+        <refentrytitle>pam_sm_authenticate</refentrytitle><manvolnum>3</manvolnum>
+      </citerefentry>,
+      <citerefentry>
+        <refentrytitle>pam_strerror</refentrytitle><manvolnum>3</manvolnum>
+      </citerefentry>,
+      <citerefentry>
+        <refentrytitle>PAM</refentrytitle><manvolnum>8</manvolnum>
+      </citerefentry>
+    </para>
+  </refsect1>
+</refentry>