contrib/openpam/doc/man/pam_conv.3

   1 .\"-
   2 .\" Copyright (c) 2002-2003 Networks Associates Technology, Inc.
   3 .\" All rights reserved.
   4 .\"
   5 .\" This software was developed for the FreeBSD Project by ThinkSec AS and
   6 .\" Network Associates Laboratories, the Security Research Division of
   7 .\" Network Associates, Inc. under DARPA/SPAWAR contract N66001-01-C-8035
   8 .\" ("CBOSS"), as part of the DARPA CHATS research program.
   9 .\"
  10 .\" Redistribution and use in source and binary forms, with or without
  11 .\" modification, are permitted provided that the following conditions
  12 .\" are met:
  13 .\" 1. Redistributions of source code must retain the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer.
  15 .\" 2. Redistributions in binary form must reproduce the above copyright
  16 .\"    notice, this list of conditions and the following disclaimer in the
  17 .\"    documentation and/or other materials provided with the distribution.
  18 .\" 3. The name of the author may not be used to endorse or promote
  19 .\"    products derived from this software without specific prior written
  20 .\"    permission.
  21 .\"
  22 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  23 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  24 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  25 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  26 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  27 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  28 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  29 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  30 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  31 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  32 .\" SUCH DAMAGE.
  33 .\"
  34 .\" $P4: //depot/projects/openpam/doc/man/pam_conv.3#4 $
  35 .\"
  36 .Dd June 16, 2005
  37 .Dt PAM_CONV 3
  38 .Os
  39 .Sh NAME
  40 .Nm pam_conv
  41 .Nd PAM conversation system
  42 .Sh LIBRARY
  43 .Lb libpam
  44 .Sh SYNOPSIS
  45 .In security/pam_appl.h
  46 .Bd -literal
  47 struct pam_message {
  48         int      msg_style;
  49         char    *msg;
  50 };
  51
  52 struct pam_response {
  53         char    *resp;
  54         int      resp_retcode;
  55 };
  56
  57 struct pam_conv {
  58         int     (*conv)(int, const struct pam_message **,
  59             struct pam_response **, void *);
  60         void    *appdata_ptr;
  61 };
  62 .Ed
  63 .Sh DESCRIPTION
  64 The PAM library uses an application-defined callback to communicate
  65 with the user.
  66 This callback is specified by the
  67 .Vt struct pam_conv
  68 passed to
  69 .Fn pam_start
  70 at the start of the transaction.
  71 It is also possible to set or change the conversation function at any
  72 point during a PAM transaction by changing the value of the
  73 .Dv PAM_CONV
  74 item.
  75 .Pp
  76 The conversation function's first argument specifies the number of
  77 messages (up to
  78 .Dv PAM_NUM_MSG )
  79 to process.
  80 The second argument is a pointer to an array of pointers to
  81 .Vt pam_message
  82 structures containing the actual messages.
  83 .Pp
  84 Each message can have one of four types, specified by the
  85 .Va msg_style
  86 member of
  87 .Vt struct pam_message :
  88 .Bl -tag -width 18n
  89 .It Dv PAM_PROMPT_ECHO_OFF
  90 Display a prompt and accept the user's response without echoing it to
  91 the terminal.
  92 This is commonly used for passwords.
  93 .It Dv PAM_PROMPT_ECHO_ON
  94 Display a prompt and accept the user's response, echoing it to the
  95 terminal.
  96 This is commonly used for login names and one-time passphrases.
  97 .It Dv PAM_ERROR_MSG
  98 Display an error message.
  99 .It Dv PAM_TEXT_INFO
 100 Display an informational message.
 101 .El
 102 .Pp
 103 In each case, the prompt or message to display is pointed to by the
 104 .Va msg
 105 member of
 106 .Vt struct pam_message .
 107 It can be up to
 108 .Dv PAM_MAX_MSG_SIZE
 109 characters long, including the terminating NUL.
 110 .Pp
 111 On success, the conversation function should allocate and fill a
 112 contiguous array of
 113 .Vt struct pam_response ,
 114 one for each message that was passed in.
 115 A pointer to the user's response to each message (or
 116 .Dv NULL
 117 in the case of informational or error messages) should be stored in
 118 the
 119 .Va resp
 120 member of the corresponding
 121 .Vt struct pam_response .
 122 Each response can be up to
 123 .Dv PAM_MAX_RESP_SIZE
 124 characters long, including the terminating NUL.
 125 .Pp
 126 The
 127 .Va resp_retcode
 128 member of
 129 .Vt struct pam_response
 130 is unused and should be set to zero.
 131 .Pp
 132 The conversation function should store a pointer to this array in the
 133 location pointed to by its third argument.
 134 It is the caller's responsibility to release both this array and the
 135 responses themselves, using
 136 .Xr free 3 .
 137 It is the conversation function's responsibility to ensure that it is
 138 legal to do so.
 139 .Pp
 140 The
 141 .Va appdata_ptr
 142 member of
 143 .Vt struct pam_conv
 144 is passed unmodified to the conversation function as its fourth and
 145 final argument.
 146 .Pp
 147 On failure, the conversation function should release any resources it
 148 has allocated, and return one of the predefined PAM error codes.
 149 .Sh RETURN VALUES
 150 The conversation function should return one of the following values:
 151 .Bl -tag -width 18n
 152 .It Bq Er PAM_BUF_ERR
 153 Memory buffer error.
 154 .It Bq Er PAM_CONV_ERR
 155 Conversation failure.
 156 .It Bq Er PAM_SUCCESS
 157 Success.
 158 .It Bq Er PAM_SYSTEM_ERR
 159 System error.
 160 .El
 161 .Sh SEE ALSO
 162 .Xr openpam_nullconv 3 ,
 163 .Xr openpam_ttyconv 3 ,
 164 .Xr pam 3 ,
 165 .Xr pam_error 3 ,
 166 .Xr pam_get_item 3 ,
 167 .Xr pam_info 3 ,
 168 .Xr pam_prompt 3 ,
 169 .Xr pam_set_item 3 ,
 170 .Xr pam_start 3
 171 .Sh STANDARDS
 172 .Rs
 173 .%T "X/Open Single Sign-On Service (XSSO) - Pluggable Authentication Modules"
 174 .%D "June 1997"
 175 .Re
 176 .Sh AUTHORS
 177 The OpenPAM library and this manual page were developed for the
 178 FreeBSD Project by ThinkSec AS and Network Associates Laboratories,
 179 the Security Research Division of Network Associates, Inc.\& under
 180 DARPA/SPAWAR contract N66001-01-C-8035
 181 .Pq Dq CBOSS ,
 182 as part of the DARPA CHATS research program.