contrib/openpam/doc/man/pam_get_authtok.3

   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 December 18, 2011
  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
  51 The
  52 .Nm
  53 function returns the cached authentication token,
  54 or prompts the user if no token is currently cached.
  55 Either way, a pointer to the authentication token is stored in the
  56 location pointed to by the
  57 .Fa authtok
  58 argument.
  59 .Pp
  60 The
  61 .Fa item
  62 argument must have one of the following values:
  63 .Bl -tag -width 18n
  64 .It Dv PAM_AUTHTOK
  65 Returns the current authentication token, or the new token
  66 when changing authentication tokens.
  67 .It Dv PAM_OLDAUTHTOK
  68 Returns the previous authentication token when changing
  69 authentication tokens.
  70 .El
  71 .Pp
  72 The
  73 .Fa prompt
  74 argument specifies a prompt to use if no token is cached.
  75 If it is
  76 .Dv NULL ,
  77 the
  78 .Dv PAM_AUTHTOK_PROMPT
  79 or
  80 .Dv PAM_OLDAUTHTOK_PROMPT
  81 item,
  82 as appropriate, will be used.
  83 If that item is also
  84 .Dv NULL ,
  85 a hardcoded default prompt will be used.
  86 Either way, the prompt is expanded using
  87 .Xr openpam_subst 3
  88 before it is
  89 passed to the conversation function.
  90 .Pp
  91 If
  92 .Nm
  93 is called from a module and the
  94 .Dv authtok_prompt
  95 /
  96 .Dv oldauthtok_prompt
  97 option is set in the policy file, the value of that
  98 option takes precedence over both the
  99 .Fa prompt
 100 argument and the
 101 .Dv PAM_AUTHTOK_PROMPT
 102 /
 103 .Dv PAM_OLDAUTHTOK_PROMPT
 104 item.
 105 .Pp
 106 If
 107 .Fa item
 108 is set to
 109 .Dv PAM_AUTHTOK
 110 and there is a non-null
 111 .Dv PAM_OLDAUTHTOK
 112 item,
 113 .Nm
 114 will ask the user to confirm the new token by
 115 retyping it.
 116 If there is a mismatch,
 117 .Nm
 118 will return
 119 .Dv PAM_TRY_AGAIN .
 120 .Pp
 121 .Sh RETURN VALUES
 122 The
 123 .Nm
 124 function returns one of the following values:
 125 .Bl -tag -width 18n
 126 .It Bq Er PAM_BUF_ERR
 127 Memory buffer error.
 128 .It Bq Er PAM_CONV_ERR
 129 Conversation failure.
 130 .It Bq Er PAM_SYSTEM_ERR
 131 System error.
 132 .It Bq Er PAM_TRY_AGAIN
 133 Try 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
 142 The
 143 .Nm
 144 function is an OpenPAM extension.
 145 .Sh AUTHORS
 146 The
 147 .Nm
 148 function and this manual page were developed for the
 149 .Fx
 150 Project by
 151 ThinkSec AS and Network Associates Laboratories, the
 152 Security Research Division of Network Associates, Inc.\& under
 153 DARPA/SPAWAR contract N66001-01-C-8035
 154 .Pq Dq CBOSS ,
 155 as part of the DARPA CHATS research program.