granicus.if.org Git - linux-pam/blob - doc/man/pam_sm_setcred.3.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
   3                    "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
   4 <refentry id='pam_sm_setcred'>
   5   <refmeta>
   6     <refentrytitle>pam_sm_setcred</refentrytitle>
   7     <manvolnum>3</manvolnum>
   8     <refmiscinfo class='setdesc'>Linux-PAM Manual</refmiscinfo>
   9   </refmeta>
  10
  11   <refnamediv id="pam_sm_setcred-name">
  12     <refname>pam_sm_setcred</refname>
  13     <refpurpose>PAM service function to alter credentials</refpurpose>
  14   </refnamediv>
  15
  16 <!-- body begins here -->
  17
  18   <refsynopsisdiv>
  19     <funcsynopsis id='pam_sm_setcred-synopsis'>
  20       <funcsynopsisinfo>#define PAM_SM_AUTH</funcsynopsisinfo>
  21       <funcsynopsisinfo>#include &lt;security/pam_modules.h&gt;</funcsynopsisinfo>
  22       <funcprototype>
  23         <funcdef>PAM_EXTERN int <function>pam_sm_setcred</function></funcdef>
  24         <paramdef>pam_handle_t *<parameter>pamh</parameter></paramdef>
  25         <paramdef>int <parameter>flags</parameter></paramdef>
  26         <paramdef>int <parameter>argc</parameter></paramdef>
  27         <paramdef>const char **<parameter>argv</parameter></paramdef>
  28       </funcprototype>
  29     </funcsynopsis>
  30   </refsynopsisdiv>
  31
  32
  33   <refsect1 id='pam_sm_setcred-description'>
  34     <title>DESCRIPTION</title>
  35     <para>
  36       The <function>pam_sm_setcred</function> function is the service
  37       module's implementation of the
  38       <citerefentry>
  39         <refentrytitle>pam_setcred</refentrytitle><manvolnum>3</manvolnum>
  40       </citerefentry> interface.
  41     </para>
  42     <para>
  43       This function performs the task of altering the credentials of the
  44       user with respect to the corresponding authorization
  45       scheme. Generally, an authentication module may have access to more
  46       information about a user than their authentication token. This
  47       function is used to make such information available to the
  48       application. It should only be called <emphasis>after</emphasis> the
  49       user has been authenticated but before a session has been established.
  50     </para>
  51     <para>
  52        Valid flags, which may be logically OR'd with
  53        <emphasis>PAM_SILENT</emphasis>, are:
  54     </para>
  55     <variablelist>
  56       <varlistentry>
  57         <term>PAM_SILENT</term>
  58         <listitem>
  59            <para>
  60              Do not emit any messages.
  61           </para>
  62         </listitem>
  63       </varlistentry>
  64       <varlistentry>
  65         <term>PAM_ESTABLISH_CRED</term>
  66         <listitem>
  67           <para>Initialize the credentials for the user.</para>
  68         </listitem>
  69       </varlistentry>
  70       <varlistentry>
  71         <term>PAM_DELETE_CRED</term>
  72         <listitem>
  73           <para>
  74             Delete the credentials associated with the authentication service.
  75           </para>
  76         </listitem>
  77       </varlistentry>
  78       <varlistentry>
  79         <term>PAM_REINITIALIZE_CRED</term>
  80         <listitem>
  81           <para>
  82             Reinitialize the user credentials.
  83           </para>
  84         </listitem>
  85       </varlistentry>
  86       <varlistentry>
  87         <term>PAM_REFRESH_CRED</term>
  88         <listitem>
  89           <para>
  90             Extend the lifetime of the user credentials.
  91           </para>
  92         </listitem>
  93       </varlistentry>
  94     </variablelist>
  95     <para>
  96       The way the <emphasis remap='B'>auth</emphasis> stack is
  97       navigated in order to evaluate the <function>pam_setcred</function>()
  98       function call, independent of the <function>pam_sm_setcred</function>()
  99       return codes, is exactly the same way that it was navigated when
 100       evaluating the <function>pam_authenticate</function>() library
 101       call. Typically, if a stack entry was ignored in evaluating
 102       <function>pam_authenticate</function>(), it will be ignored when
 103       libpam evaluates the <function>pam_setcred</function>() function
 104       call. Otherwise, the return codes from each module specific
 105       <function>pam_sm_setcred</function>() call are treated as
 106       <emphasis remap='B'>required</emphasis>.
 107     </para>
 108   </refsect1>
 109
 110   <refsect1 id="pam_sm_setcred-return_values">
 111     <title>RETURN VALUES</title>
 112     <variablelist>
 113       <varlistentry>
 114         <term>PAM_CRED_UNAVAIL</term>
 115         <listitem>
 116           <para>
 117             This module cannot retrieve the user's credentials.
 118           </para>
 119         </listitem>
 120       </varlistentry>
 121       <varlistentry>
 122         <term>PAM_CRED_EXPIRED</term>
 123         <listitem>
 124           <para>
 125             The user's credentials have expired.
 126           </para>
 127         </listitem>
 128       </varlistentry>
 129       <varlistentry>
 130         <term>PAM_CRED_ERR</term>
 131         <listitem>
 132           <para>
 133             This module was unable to set the credentials of the user.
 134           </para>
 135         </listitem>
 136       </varlistentry>
 137       <varlistentry>
 138         <term>PAM_SUCCESS</term>
 139         <listitem>
 140            <para>
 141              The user credential was successfully set.
 142           </para>
 143         </listitem>
 144       </varlistentry>
 145       <varlistentry>
 146         <term>PAM_USER_UNKNOWN</term>
 147         <listitem>
 148           <para>
 149             The user is not known to this authentication module.
 150           </para>
 151         </listitem>
 152       </varlistentry>
 153     </variablelist>
 154     <para>
 155       These, non-<emphasis>PAM_SUCCESS</emphasis>, return values will
 156       typically lead to the credential stack <emphasis>failing</emphasis>.
 157       The first such error will dominate in the return value of
 158       <function>pam_setcred</function>().
 159     </para>
 160   </refsect1>
 161
 162   <refsect1 id='pam_sm_setcred-see_also'>
 163     <title>SEE ALSO</title>
 164     <para>
 165       <citerefentry>
 166         <refentrytitle>pam</refentrytitle><manvolnum>3</manvolnum>
 167       </citerefentry>,
 168       <citerefentry>
 169         <refentrytitle>pam_authenticate</refentrytitle><manvolnum>3</manvolnum>
 170       </citerefentry>,
 171       <citerefentry>
 172         <refentrytitle>pam_setcred</refentrytitle><manvolnum>3</manvolnum>
 173       </citerefentry>,
 174       <citerefentry>
 175         <refentrytitle>pam_sm_authenticate</refentrytitle><manvolnum>3</manvolnum>
 176       </citerefentry>,
 177       <citerefentry>
 178         <refentrytitle>pam_strerror</refentrytitle><manvolnum>3</manvolnum>
 179       </citerefentry>,
 180       <citerefentry>
 181         <refentrytitle>PAM</refentrytitle><manvolnum>8</manvolnum>
 182       </citerefentry>
 183     </para>
 184   </refsect1>
 185 </refentry>