Debian Codegraph @

upstream/debian-unstable/man3/pam_sm_setcred.3

raw
1 '\" t
2 .\" Title: pam_sm_setcred
3 .\" Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
4 .\" Generator: DocBook XSL Stylesheets v1.79.2 <http://docbook.sf.net/>
5 .\" Date: 06/29/2025
6 .\" Manual: Linux-PAM Manual
7 .\" Source: Linux-PAM
8 .\" Language: English
9 .\"
10 .TH "PAM_SM_SETCRED" "3" "06/29/2025" "Linux\-PAM" "Linux\-PAM Manual"
11 .\" -----------------------------------------------------------------
12 .\" * Define some portability stuff
13 .\" -----------------------------------------------------------------
14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
15 .\" http://bugs.debian.org/507673
16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
18 .ie \n(.g .ds Aq \(aq
19 .el .ds Aq '
20 .\" -----------------------------------------------------------------
21 .\" * set default formatting
22 .\" -----------------------------------------------------------------
23 .\" disable hyphenation
24 .nh
25 .\" disable justification (adjust text to left margin only)
26 .ad l
27 .\" -----------------------------------------------------------------
28 .\" * MAIN CONTENT STARTS HERE *
29 .\" -----------------------------------------------------------------
30 .SH "NAME"
31 pam_sm_setcred \- PAM service function to alter credentials
32 .SH "SYNOPSIS"
33 .sp
34 .ft B
35 .nf
36 #include <security/pam_modules\&.h>
37 .fi
38 .ft
39 .HP \w'int\ pam_sm_setcred('u
40 .BI "int pam_sm_setcred(pam_handle_t\ *" "pamh" ", int\ " "flags" ", int\ " "argc" ", const\ char\ **" "argv" ");"
41 .SH "DESCRIPTION"
42 .PP
43 The
44 \fBpam_sm_setcred\fR
45 function is the service module\*(Aqs implementation of the
46 \fBpam_setcred\fR(3)
47 interface\&.
48 .PP
49 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
50 \fIafter\fR
51 the user has been authenticated but before a session has been established\&.
52 .PP
53 Valid flags, which may be logically OR\*(Aqd with
54 \fIPAM_SILENT\fR, are:
55 .PP
56 PAM_SILENT
57 .RS 4
58 Do not emit any messages\&.
59 .RE
60 .PP
61 PAM_ESTABLISH_CRED
62 .RS 4
63 Initialize the credentials for the user\&.
64 .RE
65 .PP
66 PAM_DELETE_CRED
67 .RS 4
68 Delete the credentials associated with the authentication service\&.
69 .RE
70 .PP
71 PAM_REINITIALIZE_CRED
72 .RS 4
73 Reinitialize the user credentials\&.
74 .RE
75 .PP
76 PAM_REFRESH_CRED
77 .RS 4
78 Extend the lifetime of the user credentials\&.
79 .RE
80 .PP
81 The way the
82 \fBauth\fR
83 stack is navigated in order to evaluate the
84 \fBpam_setcred\fR() function call, independent of the
85 \fBpam_sm_setcred\fR() return codes, is exactly the same way that it was navigated when evaluating the
86 \fBpam_authenticate\fR() library call\&. Typically, if a stack entry was ignored in evaluating
87 \fBpam_authenticate\fR(), it will be ignored when libpam evaluates the
88 \fBpam_setcred\fR() function call\&. Otherwise, the return codes from each module specific
89 \fBpam_sm_setcred\fR() call are treated as
90 \fBrequired\fR\&.
91 .SH "RETURN VALUES"
92 .PP
93 PAM_CRED_UNAVAIL
94 .RS 4
95 This module cannot retrieve the user\*(Aqs credentials\&.
96 .RE
97 .PP
98 PAM_CRED_EXPIRED
99 .RS 4
100 The user\*(Aqs credentials have expired\&.
101 .RE
102 .PP
103 PAM_CRED_ERR
104 .RS 4
105 This module was unable to set the credentials of the user\&.
106 .RE
107 .PP
108 PAM_SUCCESS
109 .RS 4
110 The user credential was successfully set\&.
111 .RE
112 .PP
113 PAM_USER_UNKNOWN
114 .RS 4
115 The user is not known to this authentication module\&.
116 .RE
117 .PP
118 These, non\-\fIPAM_SUCCESS\fR, return values will typically lead to the credential stack
119 \fIfailing\fR\&. The first such error will dominate in the return value of
120 \fBpam_setcred\fR()\&.
121 .SH "SEE ALSO"
122 .PP
123 \fBpam\fR(3),
124 \fBpam_authenticate\fR(3),
125 \fBpam_setcred\fR(3),
126 \fBpam_sm_authenticate\fR(3),
127 \fBpam_strerror\fR(3),
128 \fBPAM\fR(8)