Debian Codegraph @

upstream/debian-unstable/man3/pam_set_item.3

raw
1 '\" t
2 .\" Title: pam_set_item
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_SET_ITEM" "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_set_item \- set and update PAM information
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_set_item('u
40 .BI "int pam_set_item(pam_handle_t\ *" "pamh" ", int\ " "item_type" ", const\ void\ *" "item" ");"
41 .SH "DESCRIPTION"
42 .PP
43 The
44 \fBpam_set_item\fR
45 function allows applications and PAM service modules to access and to update PAM information of
46 \fIitem_type\fR\&. For this a copy of the object pointed to by the
47 \fIitem\fR
48 argument is created\&. The following
49 \fIitem_type\fRs are supported:
50 .PP
51 PAM_SERVICE
52 .RS 4
53 The service name (which identifies that PAM stack that the PAM functions will use to authenticate the program)\&.
54 .RE
55 .PP
56 PAM_USER
57 .RS 4
58 The username of the entity under whose identity service will be given\&. That is, following authentication,
59 \fIPAM_USER\fR
60 identifies the local entity that gets to use the service\&. Note, this value can be mapped from something (eg\&., "anonymous") to something else (eg\&. "guest119") by any module in the PAM stack\&. As such an application should consult the value of
61 \fIPAM_USER\fR
62 after each call to a PAM function\&.
63 .RE
64 .PP
65 PAM_USER_PROMPT
66 .RS 4
67 The string used when prompting for a user\*(Aqs name\&. The default value for this string is a localized version of "login: "\&.
68 .RE
69 .PP
70 PAM_TTY
71 .RS 4
72 The terminal name prefixed by
73 /dev/
74 for device files\&. In the past, graphical X\-based applications used to store the
75 \fI$DISPLAY\fR
76 variable here, but with the introduction of
77 \fIPAM_XDISPLAY\fR
78 this usage is deprecated\&.
79 .RE
80 .PP
81 PAM_RUSER
82 .RS 4
83 The requesting user name: local name for a locally requesting user or a remote user name for a remote requesting user\&.
84 .sp
85 Generally an application or module will attempt to supply the value that is most strongly authenticated (a local account before a remote one\&. The level of trust in this value is embodied in the actual authentication stack associated with the application, so it is ultimately at the discretion of the system administrator\&.
86 .sp
87 \fIPAM_RUSER@PAM_RHOST\fR
88 should always identify the requesting user\&. In some cases,
89 \fIPAM_RUSER\fR
90 may be NULL\&. In such situations, it is unclear who the requesting entity is\&.
91 .RE
92 .PP
93 PAM_RHOST
94 .RS 4
95 The requesting hostname (the hostname of the machine from which the
96 \fIPAM_RUSER\fR
97 entity is requesting service)\&. That is
98 \fIPAM_RUSER@PAM_RHOST\fR
99 does identify the requesting user\&. In some applications,
100 \fIPAM_RHOST\fR
101 may be NULL\&. In such situations, it is unclear where the authentication request is originating from\&.
102 .RE
103 .PP
104 PAM_AUTHTOK
105 .RS 4
106 The authentication token (often a password)\&. This token should be ignored by all module functions besides
107 \fBpam_sm_authenticate\fR(3)
108 and
109 \fBpam_sm_chauthtok\fR(3)\&. In the former function it is used to pass the most recent authentication token from one stacked module to another\&. In the latter function the token is used for another purpose\&. It contains the currently active authentication token\&.
110 .RE
111 .PP
112 PAM_OLDAUTHTOK
113 .RS 4
114 The old authentication token\&. This token should be ignored by all module functions except
115 \fBpam_sm_chauthtok\fR(3)\&.
116 .RE
117 .PP
118 PAM_CONV
119 .RS 4
120 The pam_conv structure\&. See
121 \fBpam_conv\fR(3)\&.
122 .RE
123 .PP
124 The following additional items are specific to Linux\-PAM and should not be used in portable applications:
125 .PP
126 PAM_FAIL_DELAY
127 .RS 4
128 A function pointer to redirect centrally managed failure delays\&. See
129 \fBpam_fail_delay\fR(3)\&.
130 .RE
131 .PP
132 PAM_XDISPLAY
133 .RS 4
134 The name of the X display\&. For graphical, X\-based applications the value for this item should be the
135 \fI$DISPLAY\fR
136 variable\&. This value may be used independently of
137 \fIPAM_TTY\fR
138 for passing the name of the display\&.
139 .RE
140 .PP
141 PAM_XAUTHDATA
142 .RS 4
143 A pointer to a structure containing the X authentication data required to make a connection to the display specified by
144 \fIPAM_XDISPLAY\fR, if such information is necessary\&. See
145 \fBpam_xauth_data\fR(3)\&.
146 .RE
147 .PP
148 PAM_AUTHTOK_TYPE
149 .RS 4
150 The default action is for the module to use the following prompts when requesting passwords: "New UNIX password: " and "Retype UNIX password: "\&. The example word
151 \fIUNIX\fR
152 can be replaced with this item, by default it is empty\&. This item is used by
153 \fBpam_get_authtok\fR(3)\&.
154 .RE
155 .PP
156 For all
157 \fIitem_type\fRs, other than PAM_CONV and PAM_FAIL_DELAY,
158 \fIitem\fR
159 is a pointer to a <NUL> terminated character string\&. In the case of PAM_CONV,
160 \fIitem\fR
161 points to an initialized
162 \fIpam_conv\fR
163 structure\&. In the case of PAM_FAIL_DELAY,
164 \fIitem\fR
165 is a function pointer:
166 \fBvoid (*delay_fn)(int retval, unsigned usec_delay, void *appdata_ptr)\fR
167 .PP
168 Both, PAM_AUTHTOK and PAM_OLDAUTHTOK, will be reset before returning to the application\&. Which means an application is not able to access the authentication tokens\&.
169 .SH "RETURN VALUES"
170 .PP
171 PAM_BAD_ITEM
172 .RS 4
173 The application attempted to set an undefined or inaccessible item\&.
174 .RE
175 .PP
176 PAM_BUF_ERR
177 .RS 4
178 Memory buffer error\&.
179 .RE
180 .PP
181 PAM_SUCCESS
182 .RS 4
183 Data was successful updated\&.
184 .RE
185 .PP
186 PAM_SYSTEM_ERR
187 .RS 4
188 The
189 \fIpam_handle_t\fR
190 passed as first argument was invalid\&.
191 .RE
192 .SH "SEE ALSO"
193 .PP
194 \fBpam_get_item\fR(3),
195 \fBpam_strerror\fR(3)