share/man/man3pam/pam_start.3pam

   1 '\" te
   2 .\" Copyright (c) 2005, Sun Microsystems, Inc.  All Rights Reserved.
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH PAM_START 3PAM "Feb 22, 2005"
   7 .SH NAME
   8 pam_start, pam_end \- PAM authentication transaction functions
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 \fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-lpam\fR [ \fIlibrary\fR ... ]
  13 #include <security/pam_appl.h>
  14
  15 \fBint\fR \fBpam_start\fR(\fBconst char *\fR\fIservice\fR, \fBconst char *\fR\fIuser\fR,
  16      \fBconst struct pam_conv *\fR\fIpam_conv\fR, \fBpam_handle_t *\fR\fI*pamh\fR);
  17 .fi
  18
  19 .LP
  20 .nf
  21 \fBint\fR \fBpam_end\fR(\fBpam_handle_t *\fR\fIpamh\fR, \fBint\fR \fIstatus\fR);
  22 .fi
  23
  24 .SH DESCRIPTION
  25 .sp
  26 .LP
  27 The \fBpam_start()\fR function is called to initiate an authentication
  28 transaction. It takes as arguments the name of the current service,
  29 \fIservice\fR, the name of the user to be authenticated, \fIuser\fR, the
  30 address of the conversation structure, \fIpam_conv\fR, and the address of a
  31 variable to be assigned the authentication handle \fIpamh\fR. Upon successful
  32 completion,  \fIpamh\fR refers to a \fBPAM\fR handle for use with subsequent
  33 calls to the authentication library.
  34 .sp
  35 .LP
  36 The  \fIpam_conv\fR structure contains the address of the conversation function
  37 provided by the application.  The underlying \fBPAM\fR service module invokes
  38 this function to output information to and retrieve input from the user. The
  39 \fBpam_conv\fR structure has the following entries:
  40 .sp
  41 .in +2
  42 .nf
  43 struct pam_conv {
  44     int   (*conv)();     /* Conversation function */
  45     void  *appdata_ptr;  /* Application data */
  46 };
  47 .fi
  48 .in -2
  49
  50 .sp
  51 .in +2
  52 .nf
  53 int conv(int num_msg, const struct pam_message **msg,
  54          struct pam_response **resp, void *appdata_ptr);
  55 .fi
  56 .in -2
  57
  58 .sp
  59 .LP
  60 The \fBconv()\fR function is called by a service module to hold a \fBPAM\fR
  61 conversation with the application or user. For window applications, the
  62 application can create a new pop-up window to be used by the interaction.
  63 .sp
  64 .LP
  65 The \fInum_msg\fR  parameter is the number of messages associated with the
  66 call. The parameter \fImsg\fR is a pointer to an array of length \fInum_msg\fR
  67 of the \fIpam_message\fR structure.
  68 .sp
  69 .LP
  70 The \fBpam_message\fR structure is used to pass prompt, error message, or any
  71 text information from the authentication service to the application or user. It
  72 is the responsibility of the \fBPAM\fR service modules to localize the
  73 messages. The memory used by \fBpam_message\fR has to be allocated and freed by
  74 the  \fBPAM\fR modules.  The \fBpam_message\fR structure has the following
  75 entries:
  76 .sp
  77 .in +2
  78 .nf
  79 struct pam_message{
  80     int     msg_style;
  81     char    *msg;
  82 };
  83 .fi
  84 .in -2
  85
  86 .sp
  87 .LP
  88 The message style, \fBmsg_style\fR, can be set to one of the following values:
  89 .sp
  90 .ne 2
  91 .na
  92 \fB\fBPAM_PROMPT_ECHO_OFF\fR\fR
  93 .ad
  94 .RS 23n
  95 Prompt user, disabling echoing of response.
  96 .RE
  97
  98 .sp
  99 .ne 2
 100 .na
 101 \fB\fBPAM_PROMPT_ECHO_ON\fR\fR
 102 .ad
 103 .RS 23n
 104 Prompt user, enabling echoing of response.
 105 .RE
 106
 107 .sp
 108 .ne 2
 109 .na
 110 \fB\fBPAM_ERROR_MSG\fR\fR
 111 .ad
 112 .RS 23n
 113 Print error message.
 114 .RE
 115
 116 .sp
 117 .ne 2
 118 .na
 119 \fB\fBPAM_TEXT_INFO\fR\fR
 120 .ad
 121 .RS 23n
 122 Print general text information.
 123 .RE
 124
 125 .sp
 126 .LP
 127 The maximum size of the message and the response string is
 128 \fBPAM_MAX_MSG_SIZE\fR as defined in <\fBsecurity/pam.appl.h\fR>.
 129 .sp
 130 .LP
 131 The structure \fIpam_response\fR is used by the authentication service to get
 132 the user's response back from the application or user. The storage used by
 133 \fIpam_response\fR has to be allocated by the application and freed by the
 134 \fBPAM\fR modules. The \fIpam_response\fR structure has the following entries:
 135 .sp
 136 .in +2
 137 .nf
 138 struct pam_response{
 139     char *resp;
 140     int  resp_retcode;  /* currently not used, */
 141                         /* should be set to 0 */
 142  };
 143 .fi
 144 .in -2
 145
 146 .sp
 147 .LP
 148 It is the responsibility of the conversation function to strip off
 149 \fBNEWLINE\fR characters for \fBPAM_PROMPT_ECHO_OFF\fR and
 150 \fBPAM_PROMPT_ECHO_ON\fR message styles, and to add \fBNEWLINE\fR characters
 151 (if appropriate) for \fBPAM_ERROR_MSG\fR and \fBPAM_TEXT_INFO\fR message
 152 styles.
 153 .sp
 154 .LP
 155 The \fIappdata_ptr\fR argument is an application data pointer which is passed
 156 by the application to the  \fBPAM\fR service modules. Since the  \fBPAM\fR
 157 modules pass it back through the conversation function, the applications can
 158 use this pointer to point to any application-specific data.
 159 .sp
 160 .LP
 161 The \fBpam_end()\fR function is called to terminate the authentication
 162 transaction identified by  \fIpamh\fR and to free any storage area allocated by
 163 the authentication module. The argument, \fIstatus\fR, is passed to the
 164 \fBcleanup(|)\fR function stored within the  \fBpam\fR handle, and is used to
 165 determine what module-specific state must be purged.  A cleanup function is
 166 attached to the handle by the underlying \fBPAM\fR modules through a call to
 167 \fBpam_set_data\fR(3PAM) to free module-specific data.
 168 .sp
 169 .LP
 170 Refer to \fISolaris Security for Developers Guide\fR for information about
 171 providing authentication, account management, session management, and password
 172 management through PAM modules.
 173 .SH RETURN VALUES
 174 .sp
 175 .LP
 176 Refer to the RETURN VALUES section on \fBpam\fR(3PAM).
 177 .SH ATTRIBUTES
 178 .sp
 179 .LP
 180 See \fBattributes\fR(5) for description of the following attributes:
 181 .sp
 182
 183 .sp
 184 .TS
 185 box;
 186 c | c
 187 l | l .
 188 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 189 _
 190 Interface Stability      Stable
 191 _
 192 MT-Level        MT-Safe with exceptions
 193 .TE
 194
 195 .SH SEE ALSO
 196 .sp
 197 .LP
 198 \fBlibpam\fR(3LIB), \fBpam\fR(3PAM), \fBpam_acct_mgmt\fR(3PAM),
 199 \fBpam_authenticate\fR(3PAM), \fBpam_chauthtok\fR(3PAM),
 200 \fBpam_open_session\fR(3PAM), \fBpam_setcred\fR(3PAM),
 201 \fBpam_set_data\fR(3PAM), \fBpam_strerror\fR(3PAM), \fBattributes\fR(5)
 202 .sp
 203 .LP
 204 \fISolaris Security for Developers Guide\fR
 205 .SH NOTES
 206 .sp
 207 .LP
 208 The interfaces in \fBlibpam\fR are MT-Safe only if each thread within the
 209 multithreaded application uses its own \fBPAM\fR handle.