contrib/openpam/doc/man/pam_get_authtok.3

   1 .\"-
   2 .\" Copyright (c) 2001-2003 Networks Associates Technology, Inc.
   3 .\" Copyright (c) 2004-2007 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 .\" $P4$
  36 .\"
  37 .Dd December 21, 2007
  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 .Pp
  87 If
  88 .Fa item
  89 is set to
  90 .Dv PAM_AUTHTOK
  91 and there is a non-null
  92 .Dv PAM_OLDAUTHTOK
  93 item,
  94 .Nm
  95 will ask the user to confirm the new token by
  96 retyping it.
  97 If there is a mismatch,
  98 .Nm
  99 will return
 100 .Dv PAM_TRY_AGAIN .
 101 .Pp
 102 .Sh RETURN VALUES
 103 The
 104 .Nm
 105 function returns one of the following values:
 106 .Bl -tag -width 18n
 107 .It Bq Er PAM_BUF_ERR
 108 Memory buffer error.
 109 .It Bq Er PAM_CONV_ERR
 110 Conversation failure.
 111 .It Bq Er PAM_SYSTEM_ERR
 112 System error.
 113 .It Bq Er PAM_TRY_AGAIN
 114 Try again.
 115 .El
 116 .Sh SEE ALSO
 117 .Xr pam 3 ,
 118 .Xr pam_get_item 3 ,
 119 .Xr pam_get_user 3 ,
 120 .Xr pam_strerror 3
 121 .Sh STANDARDS
 122 The
 123 .Nm
 124 function is an OpenPAM extension.
 125 .Sh AUTHORS
 126 The
 127 .Nm
 128 function and this manual page were developed for the
 129 .Fx
 130 Project by ThinkSec AS and Network Associates Laboratories, the
 131 Security Research Division of Network Associates, Inc.\& under
 132 DARPA/SPAWAR contract N66001-01-C-8035
 133 .Pq Dq CBOSS ,
 134 as part of the DARPA CHATS research program.