'\" te
.\" Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved
.\" 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.
.\" 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.
.\" 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]
.TH EMBEDDED_SU 1M "Feb 10, 2005"
.SH NAME
embedded_su \- allow an application to prompt for credentials and execute
commands as the super user or another user
.SH SYNOPSIS
.LP
.nf
\fB/usr/lib/embedded_su\fR [\fB-\fR] [\fIusername\fR [arg...]]
.fi

.SH DESCRIPTION
.sp
.LP
The \fBembedded_su\fR command allows an application to prompt the user for
security credentials and then use those credentials to execute a program as
another user or role (see \fBrbac\fR(5) for information on role-based access
control). The default \fIusername\fR is \fBroot\fR (super user).
.sp
.LP
\fBembedded_su\fR is identical to \fBsu\fR(1M), except that the user
interaction is packaged in a form suitable for another program to interpret and
display. Typically, \fBembedded_su\fR would be used to allow a graphical
program to prompt for the super user password and execute a command as the
super user, without requiring that the requesting program be run as the super
user.
.SS "PROTOCOL"
.sp
.LP
\fBembedded_su\fR implements a simple protocol over standard input, standard
output, and standard error. This protocol consists of three phases, roughly
corresponding to \fBPAM\fR initialization, the \fBPAM\fR dialog, and \fBPAM\fR
completion.
.SS "Phase 1: Initialization"
.sp
.LP
After starting \fBembedded_su\fR, the application must send an initialization
block on \fBembedded_su\fR's standard input. This block is a text block, as
described under "Text Blocks". There are currently no initialization parameters
defined; the application should send an empty block by sending a line
consisting solely of a period (.).
.SS "Phase 2: Conversation"
.sp
.LP
\fBembedded_su\fR then emits zero or more conversation blocks on its standard
output. Each conversation block may require zero or more responses.
.sp
.LP
A conversation block starts with a line consisting of the word \fBCONV\fR,
followed by whitespace, followed by the number of messages in the conversation
block as a decimal integer. The number of messages may be followed by
whitespace and additional data. This data, if present, must be ignored.
.sp
.LP
Each message consists of a line containing a header followed by a text block,
as described under "Text Blocks". A single newline is appended to each message,
allowing the message to end with a line that does not end with a newline.
.sp
.LP
A message header line consists of a \fBPAM\fR message style name, as described
in \fBpam_start\fR(3PAM). The message header values are:
.sp
.ne 2
.na
\fB\fBPAM_PROMPT_ECHO_OFF\fR\fR
.ad
.RS 23n
The application is to prompt the user for a value, with echoing disabled.
.RE

.sp
.ne 2
.na
\fB\fBPAM_PROMPT_ECHO_ON\fR\fR
.ad
.RS 23n
The application is to prompt the user for a value, with echoing enabled.
.RE

.sp
.ne 2
.na
\fB\fBPAM_ERROR_MSG\fR\fR
.ad
.RS 23n
The application is to display the message in a form appropriate for displaying
an error.
.RE

.sp
.ne 2
.na
\fB\fBPAM_TEXT_INFO\fR\fR
.ad
.RS 23n
The application is to display the message in a form appropriate for general
information.
.RE

.sp
.LP
The \fBPAM\fR message style may be followed by whitespace and additional data.
This data, if present, must be ignored.
.sp
.LP
After writing all of the messages in the conversation block, if any of them
were \fBPAM_PROMPT_ECHO_OFF\fR or \fBPAM_PROMPT_ECHO_ON\fR, \fBembedded_su\fR
waits for the response values. It expects the response values one per line, in
the order the messages were given.
.SS "Phase 3: Completion"
.sp
.LP
After zero or more conversation blocks, \fBembedded_su\fR emits a result block
instead of a conversation block.
.sp
.LP
Upon success, \fBembedded_su\fR emits a single line containing the word
"\fBSUCCESS\fR". The word \fBSUCCESS\fR may be followed by whitespace and
additional data. This data, if present, must be ignored.
.sp
.LP
Upon failure, \fBembedded_su\fR emits a single line containing the word
"\fBERROR\fR", followed by a text block as described under "Text Bocks". The
text block gives an error message. The word \fBERROR\fR may be followed by
whitespace and additional data. This data, if present, must be ignored.
.SS "Text Blocks"
.sp
.LP
Initialization blocks, message blocks, and error blocks are all text blocks.
These are blocks of text that are terminated by a line containing a single
period (.). Lines in the block that begin with a "." have an extra "."
prepended to them.
.SS "Internationalization"
.sp
.LP
All messages are localized to the current locale; no further localization is
required.
.SS "SECURITY"
.sp
.LP
\fBembedded_su\fR uses \fBpam\fR(3PAM) for authentication, account management,
and session management. Its primary function is to export the \fBPAM\fR
conversation mechanism to an unprivileged program. Like \fBsu\fR(1M), the
\fBPAM\fR configuration policy can be used to control \fBembedded_su\fR. The
\fBPAM\fR service name used is "embedded_su".
.sp
.LP
\fBembedded_su\fR is almost exactly equivalent to \fBsu\fR(1M) for security
purposes. The only exception is that it is slightly easier to use
\fBembedded_su\fR in writing a malicious program that might trick a user into
providing secret data. For those sites needing maximum security, potentially at
the expense of application functionality, the EXAMPLES section shows how to
disable \fBembedded_su\fR.
.SH EXAMPLES
.sp
.LP
In the following examples, left angle brackets (<<<) indicate a line written by
\fBembedded_su\fR and read by the invoking application. Right angle brackets
(>>>) indicate a line written by the application and read by \fBembedded_su\fR.
.LP
\fBExample 1 \fRExecuting a command with the Correct Password
.sp
.LP
The following example shows an attempt to execute "somecommand" as "someuser",
with the correct password supplied:

.sp
.in +2
.nf
 /usr/lib/embedded_su someuser -c somecommand
    >>>.
    <<<CONV 1
    <<<PAM_PROMPT_ECHO_OFF
    <<<Password:
    <<<.
    >>>[ correct password ]
    <<<SUCCESS
    [ somecommand executes  ]
.fi
.in -2
.sp

.LP
\fBExample 2 \fRExecuting a command with the Incorrect Password
.sp
.LP
The following example shows an attempt to execute "somecommand" as "someuser",
with the incorrect password supplied:

.sp
.in +2
.nf
 /usr/lib/embedded_su someuser -c somecommand
    >>>.
    <<<CONV 1
    <<<PAM_PROMPT_ECHO_OFF
    <<<Password:
    <<<.
    >>>[ incorrect password ]
    [ delay ]
    <<<ERROR
    <<<embedded_su:Sorry
    <<<.
    [ exit ]
.fi
.in -2
.sp

.LP
\fBExample 3 \fRMessage Examples
.sp
.LP
A \fBpam_message\fR structure with \fImsg_style\fR equal to \fBPAM_TEXT_INFO\fR
and \fBmsg\fR equal to "foo" produces:

.sp
.in +2
.nf
PAM_TEXT_INFO
foo
\&.
.fi
.in -2
.sp

.sp
.LP
A \fBpam_message\fR structure with \fImsg_style\fR equal to
\fBPAM_ERROR_MESSAGE\fR and \fBmsg\fR equal to "bar\en" produces:

.sp
.in +2
.nf
PAM_ERROR_MESSAGE
bar
[ blank line ]
\&.
.fi
.in -2
.sp

.sp
.LP
A \fBpam_message\fR structure with \fImsg_style\fR equal to
\fBPAM_ERROR_MESSAGE\fR and \fBmsg\fR equal to "aaa\enbbb" produces:

.sp
.in +2
.nf
PAM_ERROR_MESSAGE
aaa
bbb
\&.
.fi
.in -2
.sp

.sp
.LP
A \fBpam_message\fR structure with \fImsg_style\fR equal to \fBPAM_TEXT_INFO\fR
and \fBmsg\fR equal to "" produces:

.sp
.in +2
.nf
PAM_TEXT_INFO
[ blank line ]
\&.
.fi
.in -2
.sp

.sp
.LP
A \fBpam_message\fR structure with \fImsg_style\fR equal to \fBPAM_TEXT_INFO\fR
and \fBmsg\fR equal to NULL produces:

.sp
.in +2
.nf
PAM_TEXT_INFO
\&.
.fi
.in -2
.sp

.LP
\fBExample 4 \fRDisabling embedded_su
.sp
.LP
To disable \fBembedded_su\fR, add a line to the \fB/etc/pam.conf\fR file
similar to:

.sp
.in +2
.nf
embedded_su  auth  requisite  pam_deny.so.1
.fi
.in -2
.sp

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Stable
.TE

.SH SEE ALSO
.sp
.LP
\fBsu\fR(1M), \fBpam\fR(3PAM), \fBpam_start\fR(3PAM), \fBattributes\fR(5),
\fBrbac\fR(5)