contrib/openpam/doc/man/pam_get_authtok.3

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