contrib/openpam/doc/man/pam_get_authtok.3

   1 .\" Generated from pam_get_authtok.c by gendoc.pl
   2 .\" $Id: pam_get_authtok.c 913 2017-01-21 15:11:12Z des $
   3 .Dd February 19, 2017
   4 .Dt PAM_GET_AUTHTOK 3
   5 .Os
   6 .Sh NAME
   7 .Nm pam_get_authtok
   8 .Nd retrieve authentication token
   9 .Sh SYNOPSIS
  10 .In sys/types.h
  11 .In security/pam_appl.h
  12 .Ft "int"
  13 .Fn pam_get_authtok "pam_handle_t *pamh" "int item" "const char **authtok" "const char *prompt"
  14 .Sh DESCRIPTION
  15 The
  16 .Fn pam_get_authtok
  17 function either prompts the user for an
  18 authentication token or retrieves a cached authentication token,
  19 depending on circumstances.
  20 Either way, a pointer to the authentication token is stored in the
  21 location pointed to by the
  22 .Fa authtok
  23 argument, and the corresponding PAM
  24 item is updated.
  25 .Pp
  26 The
  27 .Fa item
  28 argument must have one of the following values:
  29 .Bl -tag -width 18n
  30 .It Dv PAM_AUTHTOK
  31 Returns the current authentication token, or the new token
  32 when changing authentication tokens.
  33 .It Dv PAM_OLDAUTHTOK
  34 Returns the previous authentication token when changing
  35 authentication tokens.
  36 .El
  37 .Pp
  38 The
  39 .Fa prompt
  40 argument specifies a prompt to use if no token is cached.
  41 If it is
  42 .Dv NULL ,
  43 the
  44 .Dv PAM_AUTHTOK_PROMPT
  45 or
  46 .Dv PAM_OLDAUTHTOK_PROMPT
  47 item,
  48 as appropriate, will be used.
  49 If that item is also
  50 .Dv NULL ,
  51 a hardcoded default prompt will be used.
  52 Additionally, when
  53 .Fn pam_get_authtok
  54 is called from a service module,
  55 the prompt may be affected by module options as described below.
  56 The prompt is then expanded using
  57 .Xr openpam_subst 3
  58 before it is passed to
  59 the conversation function.
  60 .Pp
  61 If
  62 .Fa item
  63 is set to
  64 .Dv PAM_AUTHTOK
  65 and there is a non-null
  66 .Dv PAM_OLDAUTHTOK
  67 item,
  68 .Fn pam_get_authtok
  69 will ask the user to confirm the new token by
  70 retyping it.
  71 If there is a mismatch,
  72 .Fn pam_get_authtok
  73 will return
  74 .Dv PAM_TRY_AGAIN .
  75 .Sh MODULE OPTIONS
  76 When called by a service module,
  77 .Fn pam_get_authtok
  78 will recognize the
  79 following module options:
  80 .Bl -tag -width 18n
  81 .It Dv authtok_prompt
  82 Prompt to use when
  83 .Fa item
  84 is set to
  85 .Dv PAM_AUTHTOK .
  86 This option overrides both the
  87 .Fa prompt
  88 argument and the
  89 .Dv PAM_AUTHTOK_PROMPT
  90 item.
  91 .It Dv echo_pass
  92 If the application's conversation function allows it, this
  93 lets the user see what they are typing.
  94 This should only be used for non-reusable authentication
  95 tokens.
  96 .It Dv oldauthtok_prompt
  97 Prompt to use when
  98 .Fa item
  99 is set to
 100 .Dv PAM_OLDAUTHTOK .
 101 This option overrides both the
 102 .Fa prompt
 103 argument and the
 104 .Dv PAM_OLDAUTHTOK_PROMPT
 105 item.
 106 .It Dv try_first_pass
 107 If the requested item is non-null, return it without
 108 prompting the user.
 109 Typically, the service module will verify the token, and
 110 if it does not match, clear the item before calling
 111 .Fn pam_get_authtok
 112 a second time.
 113 .It Dv use_first_pass
 114 Do not prompt the user at all; just return the cached
 115 value, or
 116 .Dv PAM_AUTH_ERR
 117 if there is none.
 118 .El
 119 .Sh RETURN VALUES
 120 The
 121 .Fn pam_get_authtok
 122 function returns one of the following values:
 123 .Bl -tag -width 18n
 124 .It Bq Er PAM_BUF_ERR
 125 Memory buffer error.
 126 .It Bq Er PAM_CONV_ERR
 127 Conversation failure.
 128 .It Bq Er PAM_SYSTEM_ERR
 129 System error.
 130 .It Bq Er PAM_TRY_AGAIN
 131 Try again.
 132 .El
 133 .Sh SEE ALSO
 134 .Xr openpam_get_option 3 ,
 135 .Xr openpam_subst 3 ,
 136 .Xr pam 3 ,
 137 .Xr pam_conv 3 ,
 138 .Xr pam_get_item 3 ,
 139 .Xr pam_get_user 3 ,
 140 .Xr pam_strerror 3
 141 .Sh STANDARDS
 142 The
 143 .Fn pam_get_authtok
 144 function is an OpenPAM extension.
 145 .Sh AUTHORS
 146 The
 147 .Fn pam_get_authtok
 148 function and this manual page were
 149 developed for the
 150 .Fx
 151 Project by 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.
 156 .Pp
 157 The OpenPAM library is maintained by
 158 .An Dag-Erling Sm\(/orgrav Aq Mt des@des.no .