1.\"- 2.\" Copyright (c) 2001-2003 Networks Associates Technology, Inc. 3.\" Copyright (c) 2004-2011 Dag-Erling Smørgrav 4.\" All rights reserved. 5.\" 6.\" This software was developed for the FreeBSD Project by ThinkSec AS and 7.\" Network Associates Laboratories, the Security Research Division of 8.\" Network Associates, Inc. under DARPA/SPAWAR contract N66001-01-C-8035 9.\" ("CBOSS"), as part of the DARPA CHATS research program. 10.\" 11.\" Redistribution and use in source and binary forms, with or without 12.\" modification, are permitted provided that the following conditions 13.\" are met: 14.\" 1. Redistributions of source code must retain the above copyright 15.\" notice, this list of conditions and the following disclaimer. 16.\" 2. Redistributions in binary form must reproduce the above copyright 17.\" notice, this list of conditions and the following disclaimer in the 18.\" documentation and/or other materials provided with the distribution. 19.\" 3. The name of the author may not be used to endorse or promote 20.\" products derived from this software without specific prior written 21.\" permission. 22.\" 23.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 24.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 25.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 26.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 27.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 28.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 29.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 30.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 31.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 32.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 33.\" SUCH DAMAGE. 34.\" 35.\" $Id$ 36.\" 37.Dd May 26, 2012 38.Dt PAM_GET_AUTHTOK 3 39.Os 40.Sh NAME 41.Nm pam_get_authtok 42.Nd retrieve authentication token 43.Sh LIBRARY 44.Lb libpam 45.Sh SYNOPSIS 46.In sys/types.h 47.In security/pam_appl.h 48.Ft "int" 49.Fn pam_get_authtok "pam_handle_t *pamh" "int item" "const char **authtok" "const char *prompt" 50.Sh DESCRIPTION 51The 52.Fn pam_get_authtok 53function returns the cached authentication token, 54or prompts the user if no token is currently cached. 55Either way, a pointer to the authentication token is stored in the 56location pointed to by the 57.Fa authtok 58argument. 59.Pp 60The 61.Fa item 62argument must have one of the following values: 63.Bl -tag -width 18n 64.It Dv PAM_AUTHTOK 65Returns the current authentication token, or the new token 66when changing authentication tokens. 67.It Dv PAM_OLDAUTHTOK 68Returns the previous authentication token when changing 69authentication tokens. 70.El 71.Pp 72The 73.Fa prompt 74argument specifies a prompt to use if no token is cached. 75If it is 76.Dv NULL , 77the 78.Dv PAM_AUTHTOK_PROMPT 79or 80.Dv PAM_OLDAUTHTOK_PROMPT 81item, 82as appropriate, will be used. 83If that item is also 84.Dv NULL , 85a hardcoded default prompt will be used. 86Either way, the prompt is expanded using 87.Xr openpam_subst 3 88before it is 89passed to the conversation function. 90.Pp 91If 92.Fn pam_get_authtok 93is called from a module and the 94.Dv authtok_prompt 95/ 96.Dv oldauthtok_prompt 97option is set in the policy file, the value of that 98option takes precedence over both the 99.Fa prompt 100argument and the 101.Dv PAM_AUTHTOK_PROMPT 102/ 103.Dv PAM_OLDAUTHTOK_PROMPT 104item. 105.Pp 106If 107.Fa item 108is set to 109.Dv PAM_AUTHTOK 110and there is a non-null 111.Dv PAM_OLDAUTHTOK 112item, 113.Fn pam_get_authtok 114will ask the user to confirm the new token by 115retyping it. 116If there is a mismatch, 117.Fn pam_get_authtok 118will return 119.Dv PAM_TRY_AGAIN . 120.Pp 121.Sh RETURN VALUES 122The 123.Fn pam_get_authtok 124function returns one of the following values: 125.Bl -tag -width 18n 126.It Bq Er PAM_BUF_ERR 127Memory buffer error. 128.It Bq Er PAM_CONV_ERR 129Conversation failure. 130.It Bq Er PAM_SYSTEM_ERR 131System error. 132.It Bq Er PAM_TRY_AGAIN 133Try again. 134.El 135.Sh SEE ALSO 136.Xr openpam_subst 3 , 137.Xr pam 3 , 138.Xr pam_get_item 3 , 139.Xr pam_get_user 3 , 140.Xr pam_strerror 3 141.Sh STANDARDS 142The 143.Fn pam_get_authtok 144function is an OpenPAM extension. 145.Sh AUTHORS 146The 147.Fn pam_get_authtok 148function and this manual page were 149developed for the 150.Fx 151Project by ThinkSec AS and Network Associates Laboratories, the 152Security Research Division of Network Associates, Inc.\& under 153DARPA/SPAWAR contract N66001-01-C-8035 154.Pq Dq CBOSS , 155as part of the DARPA CHATS research program. 156