Debian Codegraph @

upstream/debian-unstable/man3/pam_get_item.3

raw
1 '\" t
2 .\" Title: pam_get_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_GET_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_get_item \- getting 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_get_item('u
40 .BI "int pam_get_item(const\ pam_handle_t\ *" "pamh" ", int\ " "item_type" ", const\ void\ **" "item" ");"
41 .SH "DESCRIPTION"
42 .PP
43 The
44 \fBpam_get_item\fR
45 function allows applications and PAM service modules to access and retrieve PAM information of
46 \fIitem_type\fR\&. Upon successful return,
47 \fIitem\fR
48 contains a pointer to the value of the corresponding item\&. Note, this is a pointer to the
49 \fIactual\fR
50 data and should
51 \fBnot\fR
52 be
53 \fIfree()\fR\*(Aqed or over\-written! The following values are supported for
54 \fIitem_type\fR:
55 .PP
56 PAM_SERVICE
57 .RS 4
58 The service name (which identifies that PAM stack that the PAM functions will use to authenticate the program)\&.
59 .RE
60 .PP
61 PAM_USER
62 .RS 4
63 The username of the entity under whose identity service will be given\&. That is, following authentication,
64 \fIPAM_USER\fR
65 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
66 \fIPAM_USER\fR
67 after each call to a PAM function\&.
68 .RE
69 .PP
70 PAM_USER_PROMPT
71 .RS 4
72 The string used when prompting for a user\*(Aqs name\&. The default value for this string is a localized version of "login: "\&.
73 .RE
74 .PP
75 PAM_TTY
76 .RS 4
77 The terminal name prefixed by
78 /dev/
79 for device files\&. In the past, graphical X\-based applications used to store the
80 \fI$DISPLAY\fR
81 variable here, but with the introduction of
82 \fIPAM_XDISPLAY\fR
83 this usage is deprecated\&.
84 .RE
85 .PP
86 PAM_RUSER
87 .RS 4
88 The requesting user name: local name for a locally requesting user or a remote user name for a remote requesting user\&.
89 .sp
90 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\&.
91 .sp
92 \fIPAM_RUSER@PAM_RHOST\fR
93 should always identify the requesting user\&. In some cases,
94 \fIPAM_RUSER\fR
95 may be NULL\&. In such situations, it is unclear who the requesting entity is\&.
96 .RE
97 .PP
98 PAM_RHOST
99 .RS 4
100 The requesting hostname (the hostname of the machine from which the
101 \fIPAM_RUSER\fR
102 entity is requesting service)\&. That is
103 \fIPAM_RUSER@PAM_RHOST\fR
104 does identify the requesting user\&. In some applications,
105 \fIPAM_RHOST\fR
106 may be NULL\&. In such situations, it is unclear where the authentication request is originating from\&.
107 .RE
108 .PP
109 PAM_AUTHTOK
110 .RS 4
111 The authentication token (often a password)\&. This token should be ignored by all module functions besides
112 \fBpam_sm_authenticate\fR(3)
113 and
114 \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\&.
115 .RE
116 .PP
117 PAM_OLDAUTHTOK
118 .RS 4
119 The old authentication token\&. This token should be ignored by all module functions except
120 \fBpam_sm_chauthtok\fR(3)\&.
121 .RE
122 .PP
123 PAM_CONV
124 .RS 4
125 The pam_conv structure\&. See
126 \fBpam_conv\fR(3)\&.
127 .RE
128 .PP
129 The following additional items are specific to Linux\-PAM and should not be used in portable applications:
130 .PP
131 PAM_FAIL_DELAY
132 .RS 4
133 A function pointer to redirect centrally managed failure delays\&. See
134 \fBpam_fail_delay\fR(3)\&.
135 .RE
136 .PP
137 PAM_XDISPLAY
138 .RS 4
139 The name of the X display\&. For graphical, X\-based applications the value for this item should be the
140 \fI$DISPLAY\fR
141 variable\&. This value may be used independently of
142 \fIPAM_TTY\fR
143 for passing the name of the display\&.
144 .RE
145 .PP
146 PAM_XAUTHDATA
147 .RS 4
148 A pointer to a structure containing the X authentication data required to make a connection to the display specified by
149 \fIPAM_XDISPLAY\fR, if such information is necessary\&. See
150 \fBpam_xauth_data\fR(3)\&.
151 .RE
152 .PP
153 PAM_AUTHTOK_TYPE
154 .RS 4
155 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
156 \fIUNIX\fR
157 can be replaced with this item, by default it is empty\&. This item is used by
158 \fBpam_get_authtok\fR(3)\&.
159 .RE
160 .PP
161 If a service module wishes to obtain the name of the user, it should not use this function, but instead perform a call to
162 \fBpam_get_user\fR(3)\&.
163 .PP
164 Only a service module is privileged to read the authentication tokens, PAM_AUTHTOK and PAM_OLDAUTHTOK\&.
165 .SH "RETURN VALUES"
166 .PP
167 PAM_BAD_ITEM
168 .RS 4
169 The application attempted to set an undefined or inaccessible item\&.
170 .RE
171 .PP
172 PAM_BUF_ERR
173 .RS 4
174 Memory buffer error\&.
175 .RE
176 .PP
177 PAM_PERM_DENIED
178 .RS 4
179 The value of
180 \fIitem\fR
181 was NULL\&.
182 .RE
183 .PP
184 PAM_SUCCESS
185 .RS 4
186 Data was successful updated\&.
187 .RE
188 .PP
189 PAM_SYSTEM_ERR
190 .RS 4
191 The
192 \fIpam_handle_t\fR
193 passed as first argument was invalid\&.
194 .RE
195 .SH "SEE ALSO"
196 .PP
197 \fBpam_set_item\fR(3),
198 \fBpam_strerror\fR(3)