dist/openpam/doc/man/pam_conv.3

   1 .\"     $NetBSD: pam_conv.3,v 1.4 2005/02/20 19:33:59 wiz Exp $
   2 .\"
   3 .\"-
   4 .\" Copyright (c) 2002-2003 Networks Associates Technology, Inc.
   5 .\" Copyright (c) 2004-2007 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: pam_conv.3,v 1.5 2008/01/27 01:22:56 christos Exp $
  38 .\"
  39 .Dd June 16, 2005
  40 .Dt PAM_CONV 3
  41 .Os
  42 .Sh NAME
  43 .Nm pam_conv
  44 .Nd PAM conversation system
  45 .Sh LIBRARY
  46 .Lb libpam
  47 .Sh SYNOPSIS
  48 .In security/pam_appl.h
  49 .Bd -literal
  50 struct pam_message {
  51         int      msg_style;
  52         char    *msg;
  53 };
  54
  55 struct pam_response {
  56         char    *resp;
  57         int      resp_retcode;
  58 };
  59
  60 struct pam_conv {
  61         int     (*conv)(int, const struct pam_message **,
  62             struct pam_response **, void *);
  63         void    *appdata_ptr;
  64 };
  65 .Ed
  66 .Sh DESCRIPTION
  67 The PAM library uses an application-defined callback to communicate
  68 with the user.
  69 This callback is specified by the
  70 .Vt struct pam_conv
  71 passed to
  72 .Fn pam_start
  73 at the start of the transaction.
  74 It is also possible to set or change the conversation function at any
  75 point during a PAM transaction by changing the value of the
  76 .Dv PAM_CONV
  77 item.
  78 .Pp
  79 The conversation function's first argument specifies the number of
  80 messages (up to
  81 .Dv PAM_NUM_MSG )
  82 to process.
  83 The second argument is a pointer to an array of pointers to
  84 .Vt pam_message
  85 structures containing the actual messages.
  86 .Pp
  87 Each message can have one of four types, specified by the
  88 .Va msg_style
  89 member of
  90 .Vt struct pam_message :
  91 .Bl -tag -width 18n
  92 .It Dv PAM_PROMPT_ECHO_OFF
  93 Display a prompt and accept the user's response without echoing it to
  94 the terminal.
  95 This is commonly used for passwords.
  96 .It Dv PAM_PROMPT_ECHO_ON
  97 Display a prompt and accept the user's response, echoing it to the
  98 terminal.
  99 This is commonly used for login names and one-time passphrases.
 100 .It Dv PAM_ERROR_MSG
 101 Display an error message.
 102 .It Dv PAM_TEXT_INFO
 103 Display an informational message.
 104 .El
 105 .Pp
 106 In each case, the prompt or message to display is pointed to by the
 107 .Va msg
 108 member of
 109 .Vt struct pam_message .
 110 It can be up to
 111 .Dv PAM_MAX_MSG_SIZE
 112 characters long, including the terminating NUL.
 113 .Pp
 114 On success, the conversation function should allocate and fill a
 115 contiguous array of
 116 .Vt struct pam_response ,
 117 one for each message that was passed in.
 118 A pointer to the user's response to each message (or
 119 .Dv NULL
 120 in the case of informational or error messages) should be stored in
 121 the
 122 .Va resp
 123 member of the corresponding
 124 .Vt struct pam_response .
 125 Each response can be up to
 126 .Dv PAM_MAX_RESP_SIZE
 127 characters long, including the terminating NUL.
 128 .Pp
 129 The
 130 .Va resp_retcode
 131 member of
 132 .Vt struct pam_response
 133 is unused and should be set to zero.
 134 .Pp
 135 The conversation function should store a pointer to this array in the
 136 location pointed to by its third argument.
 137 It is the caller's responsibility to release both this array and the
 138 responses themselves, using
 139 .Xr free 3 .
 140 It is the conversation function's responsibility to ensure that it is
 141 legal to do so.
 142 .Pp
 143 The
 144 .Va appdata_ptr
 145 member of
 146 .Vt struct pam_conv
 147 is passed unmodified to the conversation function as its fourth and
 148 final argument.
 149 .Pp
 150 On failure, the conversation function should release any resources it
 151 has allocated, and return one of the predefined PAM error codes.
 152 .Sh RETURN VALUES
 153 The conversation function should return one of the following values:
 154 .Bl -tag -width 18n
 155 .It Bq Er PAM_BUF_ERR
 156 Memory buffer error.
 157 .It Bq Er PAM_CONV_ERR
 158 Conversation failure.
 159 .It Bq Er PAM_SUCCESS
 160 Success.
 161 .It Bq Er PAM_SYSTEM_ERR
 162 System error.
 163 .El
 164 .Sh SEE ALSO
 165 .Xr openpam_nullconv 3 ,
 166 .Xr openpam_ttyconv 3 ,
 167 .Xr pam 3 ,
 168 .Xr pam_error 3 ,
 169 .Xr pam_get_item 3 ,
 170 .Xr pam_info 3 ,
 171 .Xr pam_prompt 3 ,
 172 .Xr pam_set_item 3 ,
 173 .Xr pam_start 3
 174 .Sh STANDARDS
 175 .Rs
 176 .%T "X/Open Single Sign-On Service (XSSO) - Pluggable Authentication Modules"
 177 .%D "June 1997"
 178 .Re
 179 .Sh AUTHORS
 180 The OpenPAM library and this manual page were developed for the
 181 .Fx
 182 Project by ThinkSec AS and Network Associates Laboratories,
 183 the Security Research Division of Network Associates, Inc. under
 184 DARPA/SPAWAR contract N66001-01-C-8035
 185 .Pq Dq CBOSS ,
 186 as part of the DARPA CHATS research program.