granicus.if.org Git - linux-pam/blob - doc/man/pam_set_data.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_set_data'>
   6
   7   <refmeta>
   8     <refentrytitle>pam_set_data</refentrytitle>
   9     <manvolnum>3</manvolnum>
  10     <refmiscinfo class='setdesc'>Linux-PAM Manual</refmiscinfo>
  11   </refmeta>
  12
  13   <refnamediv id='pam_set_data-name'>
  14     <refname>pam_set_data</refname>
  15     <refpurpose>
  16        set module internal data
  17     </refpurpose>
  18   </refnamediv>
  19
  20
  21 <!-- body begins here -->
  22
  23   <refsynopsisdiv>
  24
  25    <funcsynopsis id="pam_set_data-synopsis">
  26      <funcsynopsisinfo>#include &lt;security/pam_modules.h&gt;</funcsynopsisinfo>
  27      <funcprototype>
  28        <funcdef>int <function>pam_set_data</function></funcdef>
  29        <paramdef>pam_handle_t *<parameter>pamh</parameter></paramdef>
  30        <paramdef>const char *<parameter>module_data_name</parameter></paramdef>
  31        <paramdef>void *<parameter>data</parameter></paramdef>
  32        <paramdef>void <parameter>(*cleanup)(pam_handle_t *pamh, void *data, int error_status)</parameter></paramdef>
  33      </funcprototype>
  34    </funcsynopsis>
  35
  36   </refsynopsisdiv>
  37
  38
  39   <refsect1 id="pam_set_data-description">
  40     <title>DESCRIPTION</title>
  41     <para>
  42       The <function>pam_set_data</function> function associates a pointer
  43       to an object with the (hopefully) unique string
  44       <emphasis>module_data_name</emphasis> in the PAM context specified
  45       by the <emphasis>pamh</emphasis> argument.
  46     </para>
  47
  48     <para>
  49       PAM modules may be dynamically loadable objects. In general such files
  50       should not contain <emphasis>static</emphasis> variables. This function
  51       and its counterpart
  52       <citerefentry>
  53         <refentrytitle>pam_get_data</refentrytitle><manvolnum>3</manvolnum>
  54       </citerefentry>,
  55       provide a mechanism for a module to associate some data with
  56       the handle <emphasis>pamh</emphasis>. Typically a module will call the
  57       <function>pam_set_data</function> function to register some data
  58        under a (hopefully) unique <emphasis>module_data_name</emphasis>.
  59        The data is available for use by other modules too but
  60        <emphasis>not</emphasis> by an application. Since this functions
  61        stores only a pointer to the <emphasis>data</emphasis>, the module
  62        should not modify or free the content of it.
  63     </para>
  64
  65     <para>
  66       The function <function>cleanup()</function> is associated with the
  67       <emphasis>data</emphasis> and, if non-NULL, it is called when this
  68       data is over-written or following a call to
  69       <citerefentry>
  70         <refentrytitle>pam_end</refentrytitle><manvolnum>3</manvolnum>
  71       </citerefentry>.
  72     </para>
  73
  74     <para>
  75       The <emphasis>error_status</emphasis> argument is used to indicate
  76       to the module the sort of action it is to take in cleaning this data
  77       item. As an example, Kerberos creates a ticket file during the
  78       authentication phase, this file might be associated with a data item.
  79       When
  80       <citerefentry>
  81         <refentrytitle>pam_end</refentrytitle><manvolnum>3</manvolnum>
  82       </citerefentry>
  83       is called by the module, the <emphasis>error_status</emphasis>
  84       carries the return value of the
  85       <citerefentry>
  86         <refentrytitle>pam_authenticate</refentrytitle><manvolnum>3</manvolnum>
  87       </citerefentry>
  88      or other <emphasis>libpam</emphasis> function as appropriate. Based
  89      on this value the Kerberos module may choose to delete the ticket file
  90      (<emphasis>authentication failure</emphasis>) or leave it in place.
  91    </para>
  92
  93    <para>
  94      The <emphasis>error_status</emphasis> may have been logically
  95      OR'd with either of the following two values:
  96    </para>
  97
  98     <variablelist>
  99       <varlistentry>
 100         <term>PAM_DATA_REPLACE</term>
 101         <listitem>
 102           <para>
 103             When a data item is being replaced (through a second call to
 104             <function>pam_set_data</function>) this mask is used.
 105             Otherwise, the call is assumed to be from
 106             <citerefentry>
 107               <refentrytitle>pam_end</refentrytitle><manvolnum>3</manvolnum>
 108             </citerefentry>.
 109           </para>
 110         </listitem>
 111       </varlistentry>
 112
 113       <varlistentry>
 114         <term>PAM_DATA_SILENT</term>
 115         <listitem>
 116           <para>
 117             Which indicates that the process would prefer to perform the
 118             <function>cleanup()</function> quietly. That is, discourages
 119             logging/messages to the user.
 120           </para>
 121         </listitem>
 122       </varlistentry>
 123     </variablelist>
 124   </refsect1>
 125
 126   <refsect1 id="pam_set_data-return_values">
 127     <title>RETURN VALUES</title>
 128     <variablelist>
 129       <varlistentry>
 130         <term>PAM_BUF_ERR</term>
 131         <listitem>
 132            <para>
 133               Memory buffer error.
 134           </para>
 135         </listitem>
 136       </varlistentry>
 137       <varlistentry>
 138         <term>PAM_SUCCESS</term>
 139         <listitem>
 140            <para>
 141              Data was successful stored.
 142           </para>
 143         </listitem>
 144       </varlistentry>
 145       <varlistentry>
 146         <term>PAM_SYSTEM_ERR</term>
 147         <listitem>
 148            <para>
 149              A NULL pointer was submitted as PAM handle or the
 150              function was called by an application.
 151           </para>
 152         </listitem>
 153       </varlistentry>
 154     </variablelist>
 155   </refsect1>
 156
 157   <refsect1 id="pam_set_data-see_also">
 158     <title>SEE ALSO</title>
 159     <para>
 160       <citerefentry>
 161         <refentrytitle>pam_end</refentrytitle><manvolnum>3</manvolnum>
 162       </citerefentry>,
 163       <citerefentry>
 164         <refentrytitle>pam_get_data</refentrytitle><manvolnum>3</manvolnum>
 165       </citerefentry>,
 166       <citerefentry>
 167         <refentrytitle>pam_strerror</refentrytitle><manvolnum>3</manvolnum>
 168       </citerefentry>
 169     </para>
 170   </refsect1>
 171
 172 </refentry>