Debian Codegraph @

upstream/debian-unstable/man3/pam_get_authtok.3

raw
1 '\" t
2 .\" Title: pam_get_authtok
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_AUTHTOK" "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_authtok, pam_get_authtok_verify, pam_get_authtok_noverify \- get authentication token
32 .SH "SYNOPSIS"
33 .sp
34 .ft B
35 .nf
36 #include <security/pam_ext\&.h>
37 .fi
38 .ft
39 .HP \w'int\ pam_get_authtok('u
40 .BI "int pam_get_authtok(pam_handle_t\ *" "pamh" ", int\ " "item" ", const\ char\ **" "authtok" ", const\ char\ *" "prompt" ");"
41 .HP \w'int\ pam_get_authtok_noverify('u
42 .BI "int pam_get_authtok_noverify(pam_handle_t\ *" "pamh" ", const\ char\ **" "authtok" ", const\ char\ *" "prompt" ");"
43 .HP \w'int\ pam_get_authtok_verify('u
44 .BI "int pam_get_authtok_verify(pam_handle_t\ *" "pamh" ", const\ char\ **" "authtok" ", const\ char\ *" "prompt" ");"
45 .SH "DESCRIPTION"
46 .PP
47 The
48 \fBpam_get_authtok\fR
49 function returns the cached authentication token, or prompts the user if no token is currently cached\&. It is intended for internal use by Linux\-PAM and PAM service modules\&. Upon successful return,
50 \fIauthtok\fR
51 contains a pointer to the value of the authentication token\&. Note, this is a pointer to the
52 \fIactual\fR
53 data and should
54 \fBnot\fR
55 be
56 \fIfree()\fR\*(Aqed or over\-written!
57 .PP
58 The
59 \fIprompt\fR
60 argument specifies a prompt to use if no token is cached\&. If a NULL pointer is given,
61 \fBpam_get_authtok\fR
62 uses pre\-defined prompts\&.
63 .PP
64 The following values are supported for
65 \fIitem\fR:
66 .PP
67 PAM_AUTHTOK
68 .RS 4
69 Returns the current authentication token\&. Called from
70 \fBpam_sm_chauthtok\fR(3)
71 \fBpam_get_authtok\fR
72 will ask the user to confirm the new token by retyping it\&. If a prompt was specified, "Retype" will be used as prefix\&.
73 .RE
74 .PP
75 PAM_OLDAUTHTOK
76 .RS 4
77 Returns the previous authentication token when changing authentication tokens\&.
78 .RE
79 .PP
80 The
81 \fBpam_get_authtok_noverify\fR
82 function can only be used for changing the password (from
83 \fBpam_sm_chauthtok\fR(3))\&. It returns the cached authentication token, or prompts the user if no token is currently cached\&. The difference to
84 \fBpam_get_authtok\fR
85 is, that this function does not ask a second time for the password to verify it\&. Upon successful return,
86 \fIauthtok\fR
87 contains a pointer to the value of the authentication token\&. Note, this is a pointer to the
88 \fIactual\fR
89 data and should
90 \fBnot\fR
91 be
92 \fIfree()\fR\*(Aqed or over\-written!
93 .PP
94 The
95 \fBpam_get_authtok_verify\fR
96 function can only be used to verify a password for mistypes gotten by
97 \fBpam_get_authtok_noverify\fR(3)\&. This function asks a second time for the password and verify it with the password provided by
98 \fIauthtok\fR
99 argument\&. In case of an error, the value of
100 \fIauthtok\fR
101 is undefined\&. Else this argument will point to the
102 \fIactual\fR
103 data and should
104 \fBnot\fR
105 be
106 \fIfree()\fR\*(Aqed or over\-written!
107 .SH "OPTIONS"
108 .PP
109 \fBpam_get_authtok\fR
110 honours the following module options:
111 .PP
112 try_first_pass
113 .RS 4
114 Before prompting the user for their password, the module first tries the previous stacked module\*(Aqs password in case that satisfies this module as well\&.
115 .RE
116 .PP
117 use_first_pass
118 .RS 4
119 The argument
120 \fBuse_first_pass\fR
121 forces the module to use a previous stacked modules password and will never prompt the user \- if no password is available or the password is not appropriate, the user will be denied access\&.
122 .RE
123 .PP
124 use_authtok
125 .RS 4
126 When password changing enforce the module to set the new token to the one provided by a previously stacked
127 \fBpassword\fR
128 module\&. If no token is available token changing will fail\&.
129 .RE
130 .PP
131 authtok_type=XXX
132 .RS 4
133 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
134 \fIUNIX\fR
135 can be replaced with this option, by default it is empty\&.
136 .RE
137 .SH "RETURN VALUES"
138 .PP
139 PAM_AUTH_ERR
140 .RS 4
141 Authentication token could not be retrieved\&.
142 .RE
143 .PP
144 PAM_AUTHTOK_ERR
145 .RS 4
146 New authentication could not be retrieved\&.
147 .RE
148 .PP
149 PAM_SUCCESS
150 .RS 4
151 Authentication token was successfully retrieved\&.
152 .RE
153 .PP
154 PAM_SYSTEM_ERR
155 .RS 4
156 A NULL pointer was specified as the PAM handle, or no space for an authentication token was provided\&.
157 .RE
158 .PP
159 PAM_TRY_AGAIN
160 .RS 4
161 New authentication tokens mismatch\&.
162 .RE
163 .SH "SEE ALSO"
164 .PP
165 \fBpam\fR(7)
166 .SH "STANDARDS"
167 .PP
168 The
169 \fBpam_get_authtok\fR
170 function is a Linux\-PAM extensions\&.