summaryrefslogtreecommitdiffstats
path: root/doc/man/pam_setcred.3.xml
blob: 629224824d8e680d3ba0c3e9bf9c7b101c261714 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
<?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_setcred">

  <refmeta>
    <refentrytitle>pam_setcred</refentrytitle>
    <manvolnum>3</manvolnum>
    <refmiscinfo class='setdesc'>Linux-PAM Manual</refmiscinfo>
  </refmeta>

  <refnamediv id="pam_setcred-name">
    <refname>pam_setcred</refname>
    <refpurpose>
       establish / delete user credentials
    </refpurpose>
  </refnamediv>

  <!-- body begins here -->
  <refsynopsisdiv>
    <funcsynopsis id='pam_setcred-synopsis'>
      <funcsynopsisinfo>#include &lt;security/pam_appl.h&gt;</funcsynopsisinfo>
      <funcprototype>
        <funcdef>int <function>pam_setcred</function></funcdef>
        <paramdef>pam_handle_t *<parameter>pamh</parameter></paramdef>
        <paramdef>int <parameter>flags</parameter></paramdef>
      </funcprototype>
    </funcsynopsis>
  </refsynopsisdiv>


  <refsect1 id='pam_setcred-description'>
    <title>DESCRIPTION</title>
    <para>
      The <function>pam_setcred</function> function is used to establish,
      maintain and delete the credentials of a user. It should be called
      to set the credentials after a user has been authenticated and before
      a session is opened for the user (with
      <citerefentry>
        <refentrytitle>pam_open_session</refentrytitle><manvolnum>3</manvolnum>
       </citerefentry>). The credentials should be deleted after the session
      has been closed (with
      <citerefentry>
        <refentrytitle>pam_close_session</refentrytitle><manvolnum>3</manvolnum>
       </citerefentry>).
     </para>

     <para>
       A credential is something that the user possesses. It is some
       property, such as a <emphasis>Kerberos</emphasis> ticket, or a
       supplementary group membership that make up the uniqueness of a
       given user. On a Linux system the user's <emphasis>UID</emphasis>
       and <emphasis>GID</emphasis>'s are credentials too. However, it
       has been decided that these properties (along with the default
       supplementary groups of which the user is a member) are credentials
       that should be set directly by the application and not by PAM.
       Such credentials should be established, by the application, prior
       to a call to this function.  For example,
       <citerefentry>
         <refentrytitle>initgroups</refentrytitle><manvolnum>2</manvolnum>
       </citerefentry> (or equivalent) should have been performed.
      </para>

      <para>
        Valid <emphasis>flags</emphasis>, any one of which, may be
        logically OR'd with <option>PAM_SILENT</option>, are:
      </para>

      <variablelist>
        <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 user's credentials.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>PAM_REINITIALIZE_CRED</term>
          <listitem>
            <para>Fully reinitialize the user's credentials.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>PAM_REFRESH_CRED</term>
          <listitem>
            <para>Extend the lifetime of the existing credentials.</para>
          </listitem>
        </varlistentry>
      </variablelist>
   </refsect1>

   <refsect1 id='pam_setcred-return_values'>
     <title>RETURN VALUES</title>
    <variablelist>
      <varlistentry>
        <term>PAM_BUF_ERR</term>
        <listitem>
           <para>
              Memory buffer error.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>PAM_CRED_ERR</term>
        <listitem>
           <para>
              Failed to set user credentials.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>PAM_CRED_EXPIRED</term>
        <listitem>
           <para>
             User credentials are expired.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>PAM_CRED_UNAVAIL</term>
        <listitem>
           <para>
              Failed to retrieve user credentials.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>PAM_SUCCESS</term>
        <listitem>
           <para>
             Data was successful stored.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>PAM_SYSTEM_ERR</term>
        <listitem>
           <para>
             A NULL pointer was submitted as PAM handle, the
             function was called by a module or another system
             error occurred.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>PAM_USER_UNKNOWN</term>
        <listitem>
           <para>
              User is not known to an authentication module.
          </para>
        </listitem>
      </varlistentry>

    </variablelist>
  </refsect1>

  <refsect1 id="pam_set_data-see_also">
    <title>SEE ALSO</title>
    <para>
      <citerefentry>
        <refentrytitle>pam_authenticate</refentrytitle><manvolnum>3</manvolnum>
      </citerefentry>,
      <citerefentry>
         <refentrytitle>pam_open_session</refentrytitle><manvolnum>3</manvolnum>
      </citerefentry>,
      <citerefentry>
         <refentrytitle>pam_close_session</refentrytitle><manvolnum>3</manvolnum>
      </citerefentry>,
      <citerefentry>
        <refentrytitle>pam_strerror</refentrytitle><manvolnum>3</manvolnum>
      </citerefentry>
    </para>
  </refsect1>
</refentry>