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