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">
5 <refentry id="pam_setcred">
8 <refentrytitle>pam_setcred</refentrytitle>
9 <manvolnum>3</manvolnum>
10 <refmiscinfo class='setdesc'>Linux-PAM Manual</refmiscinfo>
13 <refnamediv id="pam_setcred-name">
14 <refname>pam_setcred</refname>
16 establish / delete user credentials
20 <!-- body begins here -->
22 <funcsynopsis id='pam_setcred-synopsis'>
23 <funcsynopsisinfo>#include <security/pam_appl.h></funcsynopsisinfo>
25 <funcdef>int <function>pam_setcred</function></funcdef>
26 <paramdef>pam_handle_t *<parameter>pamh</parameter></paramdef>
27 <paramdef>int <parameter>flags</parameter></paramdef>
33 <refsect1 id='pam_setcred-description'>
34 <title>DESCRIPTION</title>
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
41 <refentrytitle>pam_open_session</refentrytitle><manvolnum>3</manvolnum>
42 </citerefentry>). The credentials should be deleted after the session
45 <refentrytitle>pam_close_session</refentrytitle><manvolnum>3</manvolnum>
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,
61 <refentrytitle>initgroups</refentrytitle><manvolnum>2</manvolnum>
62 </citerefentry> (or equivalent) should have been performed.
66 Valid <emphasis>flags</emphasis>, any one of which, may be
67 logically OR'd with <option>PAM_SILENT</option>, are:
72 <term>PAM_ESTABLISH_CRED</term>
74 <para>Initialize the credentials for the user.</para>
78 <term>PAM_DELETE_CRED</term>
80 <para>Delete the user's credentials.</para>
84 <term>PAM_REINITIALIZE_CRED</term>
86 <para>Fully reinitialize the user's credentials.</para>
90 <term>PAM_REFRESH_CRED</term>
92 <para>Extend the lifetime of the existing credentials.</para>
98 <refsect1 id='pam_setcred-return_values'>
99 <title>RETURN VALUES</title>
102 <term>PAM_BUF_ERR</term>
110 <term>PAM_CRED_ERR</term>
113 Failed to set user credentials.
118 <term>PAM_CRED_EXPIRED</term>
121 User credentials are expired.
126 <term>PAM_CRED_UNAVAIL</term>
129 Failed to retrieve user credentials.
134 <term>PAM_SUCCESS</term>
137 Data was successful stored.
142 <term>PAM_SYSTEM_ERR</term>
145 A NULL pointer was submitted as PAM handle, the
146 function was called by a module or another system
152 <term>PAM_USER_UNKNOWN</term>
155 User is not known to an authentication module.
163 <refsect1 id="pam_set_data-see_also">
164 <title>SEE ALSO</title>
167 <refentrytitle>pam_authenticate</refentrytitle><manvolnum>3</manvolnum>
170 <refentrytitle>pam_open_session</refentrytitle><manvolnum>3</manvolnum>
173 <refentrytitle>pam_close_session</refentrytitle><manvolnum>3</manvolnum>
176 <refentrytitle>pam_strerror</refentrytitle><manvolnum>3</manvolnum>