usr/src/man/man1m/embedded_su.1m

   1 '\" te
   2 .\" Copyright (c) 2003, 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 EMBEDDED_SU 1M "Feb 10, 2005"
   7 .SH NAME
   8 embedded_su \- allow an application to prompt for credentials and execute
   9 commands as the super user or another user
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 \fB/usr/lib/embedded_su\fR [\fB-\fR] [\fIusername\fR [arg...]]
  14 .fi
  15
  16 .SH DESCRIPTION
  17 .sp
  18 .LP
  19 The \fBembedded_su\fR command allows an application to prompt the user for
  20 security credentials and then use those credentials to execute a program as
  21 another user or role (see \fBrbac\fR(5) for information on role-based access
  22 control). The default \fIusername\fR is \fBroot\fR (super user).
  23 .sp
  24 .LP
  25 \fBembedded_su\fR is identical to \fBsu\fR(1M), except that the user
  26 interaction is packaged in a form suitable for another program to interpret and
  27 display. Typically, \fBembedded_su\fR would be used to allow a graphical
  28 program to prompt for the super user password and execute a command as the
  29 super user, without requiring that the requesting program be run as the super
  30 user.
  31 .SS "PROTOCOL"
  32 .sp
  33 .LP
  34 \fBembedded_su\fR implements a simple protocol over standard input, standard
  35 output, and standard error. This protocol consists of three phases, roughly
  36 corresponding to \fBPAM\fR initialization, the \fBPAM\fR dialog, and \fBPAM\fR
  37 completion.
  38 .SS "Phase 1: Initialization"
  39 .sp
  40 .LP
  41 After starting \fBembedded_su\fR, the application must send an initialization
  42 block on \fBembedded_su\fR's standard input. This block is a text block, as
  43 described under "Text Blocks". There are currently no initialization parameters
  44 defined; the application should send an empty block by sending a line
  45 consisting solely of a period (.).
  46 .SS "Phase 2: Conversation"
  47 .sp
  48 .LP
  49 \fBembedded_su\fR then emits zero or more conversation blocks on its standard
  50 output. Each conversation block may require zero or more responses.
  51 .sp
  52 .LP
  53 A conversation block starts with a line consisting of the word \fBCONV\fR,
  54 followed by whitespace, followed by the number of messages in the conversation
  55 block as a decimal integer. The number of messages may be followed by
  56 whitespace and additional data. This data, if present, must be ignored.
  57 .sp
  58 .LP
  59 Each message consists of a line containing a header followed by a text block,
  60 as described under "Text Blocks". A single newline is appended to each message,
  61 allowing the message to end with a line that does not end with a newline.
  62 .sp
  63 .LP
  64 A message header line consists of a \fBPAM\fR message style name, as described
  65 in \fBpam_start\fR(3PAM). The message header values are:
  66 .sp
  67 .ne 2
  68 .na
  69 \fB\fBPAM_PROMPT_ECHO_OFF\fR\fR
  70 .ad
  71 .RS 23n
  72 The application is to prompt the user for a value, with echoing disabled.
  73 .RE
  74
  75 .sp
  76 .ne 2
  77 .na
  78 \fB\fBPAM_PROMPT_ECHO_ON\fR\fR
  79 .ad
  80 .RS 23n
  81 The application is to prompt the user for a value, with echoing enabled.
  82 .RE
  83
  84 .sp
  85 .ne 2
  86 .na
  87 \fB\fBPAM_ERROR_MSG\fR\fR
  88 .ad
  89 .RS 23n
  90 The application is to display the message in a form appropriate for displaying
  91 an error.
  92 .RE
  93
  94 .sp
  95 .ne 2
  96 .na
  97 \fB\fBPAM_TEXT_INFO\fR\fR
  98 .ad
  99 .RS 23n
 100 The application is to display the message in a form appropriate for general
 101 information.
 102 .RE
 103
 104 .sp
 105 .LP
 106 The \fBPAM\fR message style may be followed by whitespace and additional data.
 107 This data, if present, must be ignored.
 108 .sp
 109 .LP
 110 After writing all of the messages in the conversation block, if any of them
 111 were \fBPAM_PROMPT_ECHO_OFF\fR or \fBPAM_PROMPT_ECHO_ON\fR, \fBembedded_su\fR
 112 waits for the response values. It expects the response values one per line, in
 113 the order the messages were given.
 114 .SS "Phase 3: Completion"
 115 .sp
 116 .LP
 117 After zero or more conversation blocks, \fBembedded_su\fR emits a result block
 118 instead of a conversation block.
 119 .sp
 120 .LP
 121 Upon success, \fBembedded_su\fR emits a single line containing the word
 122 "\fBSUCCESS\fR". The word \fBSUCCESS\fR may be followed by whitespace and
 123 additional data. This data, if present, must be ignored.
 124 .sp
 125 .LP
 126 Upon failure, \fBembedded_su\fR emits a single line containing the word
 127 "\fBERROR\fR", followed by a text block as described under "Text Bocks". The
 128 text block gives an error message. The word \fBERROR\fR may be followed by
 129 whitespace and additional data. This data, if present, must be ignored.
 130 .SS "Text Blocks"
 131 .sp
 132 .LP
 133 Initialization blocks, message blocks, and error blocks are all text blocks.
 134 These are blocks of text that are terminated by a line containing a single
 135 period (.). Lines in the block that begin with a "." have an extra "."
 136 prepended to them.
 137 .SS "Internationalization"
 138 .sp
 139 .LP
 140 All messages are localized to the current locale; no further localization is
 141 required.
 142 .SS "SECURITY"
 143 .sp
 144 .LP
 145 \fBembedded_su\fR uses \fBpam\fR(3PAM) for authentication, account management,
 146 and session management. Its primary function is to export the \fBPAM\fR
 147 conversation mechanism to an unprivileged program. Like \fBsu\fR(1M), the
 148 \fBPAM\fR configuration policy can be used to control \fBembedded_su\fR. The
 149 \fBPAM\fR service name used is "embedded_su".
 150 .sp
 151 .LP
 152 \fBembedded_su\fR is almost exactly equivalent to \fBsu\fR(1M) for security
 153 purposes. The only exception is that it is slightly easier to use
 154 \fBembedded_su\fR in writing a malicious program that might trick a user into
 155 providing secret data. For those sites needing maximum security, potentially at
 156 the expense of application functionality, the EXAMPLES section shows how to
 157 disable \fBembedded_su\fR.
 158 .SH EXAMPLES
 159 .sp
 160 .LP
 161 In the following examples, left angle brackets (<<<) indicate a line written by
 162 \fBembedded_su\fR and read by the invoking application. Right angle brackets
 163 (>>>) indicate a line written by the application and read by \fBembedded_su\fR.
 164 .LP
 165 \fBExample 1 \fRExecuting a command with the Correct Password
 166 .sp
 167 .LP
 168 The following example shows an attempt to execute "somecommand" as "someuser",
 169 with the correct password supplied:
 170
 171 .sp
 172 .in +2
 173 .nf
 174  /usr/lib/embedded_su someuser -c somecommand
 175     >>>.
 176     <<<CONV 1
 177     <<<PAM_PROMPT_ECHO_OFF
 178     <<<Password:
 179     <<<.
 180     >>>[ correct password ]
 181     <<<SUCCESS
 182     [ somecommand executes  ]
 183 .fi
 184 .in -2
 185 .sp
 186
 187 .LP
 188 \fBExample 2 \fRExecuting a command with the Incorrect Password
 189 .sp
 190 .LP
 191 The following example shows an attempt to execute "somecommand" as "someuser",
 192 with the incorrect password supplied:
 193
 194 .sp
 195 .in +2
 196 .nf
 197  /usr/lib/embedded_su someuser -c somecommand
 198     >>>.
 199     <<<CONV 1
 200     <<<PAM_PROMPT_ECHO_OFF
 201     <<<Password:
 202     <<<.
 203     >>>[ incorrect password ]
 204     [ delay ]
 205     <<<ERROR
 206     <<<embedded_su:Sorry
 207     <<<.
 208     [ exit ]
 209 .fi
 210 .in -2
 211 .sp
 212
 213 .LP
 214 \fBExample 3 \fRMessage Examples
 215 .sp
 216 .LP
 217 A \fBpam_message\fR structure with \fImsg_style\fR equal to \fBPAM_TEXT_INFO\fR
 218 and \fBmsg\fR equal to "foo" produces:
 219
 220 .sp
 221 .in +2
 222 .nf
 223 PAM_TEXT_INFO
 224 foo
 225 \&.
 226 .fi
 227 .in -2
 228 .sp
 229
 230 .sp
 231 .LP
 232 A \fBpam_message\fR structure with \fImsg_style\fR equal to
 233 \fBPAM_ERROR_MESSAGE\fR and \fBmsg\fR equal to "bar\en" produces:
 234
 235 .sp
 236 .in +2
 237 .nf
 238 PAM_ERROR_MESSAGE
 239 bar
 240 [ blank line ]
 241 \&.
 242 .fi
 243 .in -2
 244 .sp
 245
 246 .sp
 247 .LP
 248 A \fBpam_message\fR structure with \fImsg_style\fR equal to
 249 \fBPAM_ERROR_MESSAGE\fR and \fBmsg\fR equal to "aaa\enbbb" produces:
 250
 251 .sp
 252 .in +2
 253 .nf
 254 PAM_ERROR_MESSAGE
 255 aaa
 256 bbb
 257 \&.
 258 .fi
 259 .in -2
 260 .sp
 261
 262 .sp
 263 .LP
 264 A \fBpam_message\fR structure with \fImsg_style\fR equal to \fBPAM_TEXT_INFO\fR
 265 and \fBmsg\fR equal to "" produces:
 266
 267 .sp
 268 .in +2
 269 .nf
 270 PAM_TEXT_INFO
 271 [ blank line ]
 272 \&.
 273 .fi
 274 .in -2
 275 .sp
 276
 277 .sp
 278 .LP
 279 A \fBpam_message\fR structure with \fImsg_style\fR equal to \fBPAM_TEXT_INFO\fR
 280 and \fBmsg\fR equal to NULL produces:
 281
 282 .sp
 283 .in +2
 284 .nf
 285 PAM_TEXT_INFO
 286 \&.
 287 .fi
 288 .in -2
 289 .sp
 290
 291 .LP
 292 \fBExample 4 \fRDisabling embedded_su
 293 .sp
 294 .LP
 295 To disable \fBembedded_su\fR, add a line to the \fB/etc/pam.conf\fR file
 296 similar to:
 297
 298 .sp
 299 .in +2
 300 .nf
 301 embedded_su  auth  requisite  pam_deny.so.1
 302 .fi
 303 .in -2
 304 .sp
 305
 306 .SH ATTRIBUTES
 307 .sp
 308 .LP
 309 See \fBattributes\fR(5) for descriptions of the following attributes:
 310 .sp
 311
 312 .sp
 313 .TS
 314 box;
 315 c | c
 316 l | l .
 317 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 318 _
 319 Interface Stability     Stable
 320 .TE
 321
 322 .SH SEE ALSO
 323 .sp
 324 .LP
 325 \fBsu\fR(1M), \fBpam\fR(3PAM), \fBpam_start\fR(3PAM), \fBattributes\fR(5),
 326 \fBrbac\fR(5)