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
181
182
183
184
|
<?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>#include <security/pam_modules.h></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>
|
