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
|
'\" t
.\" Title: pam_sm_setcred
.\" Author: [FIXME: author] [see http://docbook.sf.net/el/author]
.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
.\" Date: 09/19/2013
.\" Manual: Linux-PAM Manual
.\" Source: Linux-PAM Manual
.\" Language: English
.\"
.TH "PAM_SM_SETCRED" "3" "09/19/2013" "Linux-PAM Manual" "Linux-PAM Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
pam_sm_setcred \- PAM service function to alter credentials
.SH "SYNOPSIS"
.sp
.ft B
.nf
#define PAM_SM_AUTH
.fi
.ft
.sp
.ft B
.nf
#include <security/pam_modules\&.h>
.fi
.ft
.HP \w'PAM_EXTERN\ int\ pam_sm_setcred('u
.BI "PAM_EXTERN int pam_sm_setcred(pam_handle_t\ *" "pamh" ", int\ " "flags" ", int\ " "argc" ", const\ char\ **" "argv" ");"
.SH "DESCRIPTION"
.PP
The
\fBpam_sm_setcred\fR
function is the service module\*(Aqs implementation of the
\fBpam_setcred\fR(3)
interface\&.
.PP
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
\fIafter\fR
the user has been authenticated but before a session has been established\&.
.PP
Valid flags, which may be logically OR\*(Aqd with
\fIPAM_SILENT\fR, are:
.PP
PAM_SILENT
.RS 4
Do not emit any messages\&.
.RE
.PP
PAM_ESTABLISH_CRED
.RS 4
Initialize the credentials for the user\&.
.RE
.PP
PAM_DELETE_CRED
.RS 4
Delete the credentials associated with the authentication service\&.
.RE
.PP
PAM_REINITIALIZE_CRED
.RS 4
Reinitialize the user credentials\&.
.RE
.PP
PAM_REFRESH_CRED
.RS 4
Extend the lifetime of the user credentials\&.
.RE
.PP
The way the
\fBauth\fR
stack is navigated in order to evaluate the
\fBpam_setcred\fR() function call, independent of the
\fBpam_sm_setcred\fR() return codes, is exactly the same way that it was navigated when evaluating the
\fBpam_authenticate\fR() library call\&. Typically, if a stack entry was ignored in evaluating
\fBpam_authenticate\fR(), it will be ignored when libpam evaluates the
\fBpam_setcred\fR() function call\&. Otherwise, the return codes from each module specific
\fBpam_sm_setcred\fR() call are treated as
\fBrequired\fR\&.
.SH "RETURN VALUES"
.PP
PAM_CRED_UNAVAIL
.RS 4
This module cannot retrieve the user\*(Aqs credentials\&.
.RE
.PP
PAM_CRED_EXPIRED
.RS 4
The user\*(Aqs credentials have expired\&.
.RE
.PP
PAM_CRED_ERR
.RS 4
This module was unable to set the credentials of the user\&.
.RE
.PP
PAM_SUCCESS
.RS 4
The user credential was successfully set\&.
.RE
.PP
PAM_USER_UNKNOWN
.RS 4
The user is not known to this authentication module\&.
.RE
.PP
These, non\-\fIPAM_SUCCESS\fR, return values will typically lead to the credential stack
\fIfailing\fR\&. The first such error will dominate in the return value of
\fBpam_setcred\fR()\&.
.SH "SEE ALSO"
.PP
\fBpam\fR(3),
\fBpam_authenticate\fR(3),
\fBpam_setcred\fR(3),
\fBpam_sm_authenticate\fR(3),
\fBpam_strerror\fR(3),
\fBPAM\fR(8)
|
