granicus.if.org Git - linux-pam/blob - doc/man/pam_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
   5 <refentry id="pam_setcred">
   6
   7   <refmeta>
   8     <refentrytitle>pam_setcred</refentrytitle>
   9     <manvolnum>3</manvolnum>
  10     <refmiscinfo class='setdesc'>Linux-PAM Manual</refmiscinfo>
  11   </refmeta>
  12
  13   <refnamediv id="pam_setcred-name">
  14     <refname>pam_setcred</refname>
  15     <refpurpose>
  16        establish / delete user credentials
  17     </refpurpose>
  18   </refnamediv>
  19
  20   <!-- body begins here -->
  21   <refsynopsisdiv>
  22     <funcsynopsis id='pam_setcred-synopsis'>
  23       <funcsynopsisinfo>#include &lt;security/pam_appl.h&gt;</funcsynopsisinfo>
  24       <funcprototype>
  25         <funcdef>int <function>pam_setcred</function></funcdef>
  26         <paramdef>pam_handle_t *<parameter>pamh</parameter></paramdef>
  27         <paramdef>int <parameter>flags</parameter></paramdef>
  28       </funcprototype>
  29     </funcsynopsis>
  30   </refsynopsisdiv>
  31
  32
  33   <refsect1 id='pam_setcred-description'>
  34     <title>DESCRIPTION</title>
  35     <para>
  36       The <function>pam_setcred</function> function is used to establish,
  37       maintain and delete the credentials of a user. It should be called
  38       to set the credentials after a user has been authenticated and before
  39       a session is opened for the user (with
  40       <citerefentry>
  41         <refentrytitle>pam_open_session</refentrytitle><manvolnum>3</manvolnum>
  42        </citerefentry>). The credentials should be deleted after the session
  43       has been closed (with
  44       <citerefentry>
  45         <refentrytitle>pam_close_session</refentrytitle><manvolnum>3</manvolnum>
  46        </citerefentry>).
  47      </para>
  48
  49      <para>
  50        A credential is something that the user possesses. It is some
  51        property, such as a <emphasis>Kerberos</emphasis> ticket, or a
  52        supplementary group membership that make up the uniqueness of a
  53        given user. On a Linux system the user's <emphasis>UID</emphasis>
  54        and <emphasis>GID</emphasis>'s are credentials too. However, it
  55        has been decided that these properties (along with the default
  56        supplementary groups of which the user is a member) are credentials
  57        that should be set directly by the application and not by PAM.
  58        Such credentials should be established, by the application, prior
  59        to a call to this function.  For example,
  60        <citerefentry>
  61          <refentrytitle>initgroups</refentrytitle><manvolnum>2</manvolnum>
  62        </citerefentry> (or equivalent) should have been performed.
  63       </para>
  64
  65       <para>
  66         Valid <emphasis>flags</emphasis>, any one of which, may be
  67         logically OR'd with <option>PAM_SILENT</option>, are:
  68       </para>
  69
  70       <variablelist>
  71         <varlistentry>
  72           <term>PAM_ESTABLISH_CRED</term>
  73           <listitem>
  74             <para>Initialize the credentials for the user.</para>
  75           </listitem>
  76           </varlistentry>
  77         <varlistentry>
  78           <term>PAM_DELETE_CRED</term>
  79           <listitem>
  80             <para>Delete the user's credentials.</para>
  81           </listitem>
  82         </varlistentry>
  83         <varlistentry>
  84           <term>PAM_REINITIALIZE_CRED</term>
  85           <listitem>
  86             <para>Fully reinitialize the user's credentials.</para>
  87           </listitem>
  88         </varlistentry>
  89         <varlistentry>
  90           <term>PAM_REFRESH_CRED</term>
  91           <listitem>
  92             <para>Extend the lifetime of the existing credentials.</para>
  93           </listitem>
  94         </varlistentry>
  95       </variablelist>
  96    </refsect1>
  97
  98    <refsect1 id='pam_setcred-return_values'>
  99      <title>RETURN VALUES</title>
 100     <variablelist>
 101       <varlistentry>
 102         <term>PAM_BUF_ERR</term>
 103         <listitem>
 104            <para>
 105               Memory buffer error.
 106           </para>
 107         </listitem>
 108       </varlistentry>
 109       <varlistentry>
 110         <term>PAM_CRED_ERR</term>
 111         <listitem>
 112            <para>
 113               Failed to set user credentials.
 114           </para>
 115         </listitem>
 116       </varlistentry>
 117       <varlistentry>
 118         <term>PAM_CRED_EXPIRED</term>
 119         <listitem>
 120            <para>
 121              User credentials are expired.
 122           </para>
 123         </listitem>
 124       </varlistentry>
 125       <varlistentry>
 126         <term>PAM_CRED_UNAVAIL</term>
 127         <listitem>
 128            <para>
 129               Failed to retrieve user credentials.
 130           </para>
 131         </listitem>
 132       </varlistentry>
 133       <varlistentry>
 134         <term>PAM_SUCCESS</term>
 135         <listitem>
 136            <para>
 137              Data was successful stored.
 138           </para>
 139         </listitem>
 140       </varlistentry>
 141       <varlistentry>
 142         <term>PAM_SYSTEM_ERR</term>
 143         <listitem>
 144            <para>
 145              A NULL pointer was submitted as PAM handle, the
 146              function was called by a module or another system
 147              error occured.
 148           </para>
 149         </listitem>
 150       </varlistentry>
 151       <varlistentry>
 152         <term>PAM_USER_UNKNOWN</term>
 153         <listitem>
 154            <para>
 155               User is not known to an authentication module.
 156           </para>
 157         </listitem>
 158       </varlistentry>
 159
 160     </variablelist>
 161   </refsect1>
 162
 163   <refsect1 id="pam_set_data-see_also">
 164     <title>SEE ALSO</title>
 165     <para>
 166       <citerefentry>
 167         <refentrytitle>pam_authenticate</refentrytitle><manvolnum>3</manvolnum>
 168       </citerefentry>,
 169       <citerefentry>
 170          <refentrytitle>pam_open_session</refentrytitle><manvolnum>3</manvolnum>
 171       </citerefentry>,
 172       <citerefentry>
 173          <refentrytitle>pam_close_session</refentrytitle><manvolnum>3</manvolnum>
 174       </citerefentry>,
 175       <citerefentry>
 176         <refentrytitle>pam_strerror</refentrytitle><manvolnum>3</manvolnum>
 177       </citerefentry>
 178     </para>
 179   </refsect1>
 180 </refentry>