Tribblix: manual page: embedded

EMBEDDED_SU(8) Maintenance Commands and Procedures EMBEDDED_SU(8)

NAME

embedded_su - allow an application to prompt for credentials and
execute commands as the super user or another user

SYNOPSIS

/usr/lib/embedded_su [-] [username [arg...]]

DESCRIPTION

The embedded_su 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 rbac(7) for information on role-
based access control). The default username is root (super user).

embedded_su is identical to su(8), except that the user interaction
is packaged in a form suitable for another program to interpret and
display. Typically, embedded_su 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.

PROTOCOL

embedded_su implements a simple protocol over standard input,
standard output, and standard error. This protocol consists of three
phases, roughly corresponding to PAM initialization, the PAM dialog,
and PAM completion.

Phase 1: Initialization
After starting embedded_su, the application must send an
initialization block on embedded_su'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 (.).

Phase 2: Conversation
embedded_su then emits zero or more conversation blocks on its
standard output. Each conversation block may require zero or more
responses.

A conversation block starts with a line consisting of the word CONV,
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.

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.

A message header line consists of a PAM message style name, as
described in pam_start(3PAM). The message header values are:

PAM_PROMPT_ECHO_OFF
The application is to prompt the user for a
value, with echoing disabled.

PAM_PROMPT_ECHO_ON
The application is to prompt the user for a
value, with echoing enabled.

PAM_ERROR_MSG
The application is to display the message in a
form appropriate for displaying an error.

PAM_TEXT_INFO
The application is to display the message in a
form appropriate for general information.

The PAM message style may be followed by whitespace and additional
data. This data, if present, must be ignored.

After writing all of the messages in the conversation block, if any
of them were PAM_PROMPT_ECHO_OFF or PAM_PROMPT_ECHO_ON, embedded_su
waits for the response values. It expects the response values one per
line, in the order the messages were given.

Phase 3: Completion
After zero or more conversation blocks, embedded_su emits a result
block instead of a conversation block.

Upon success, embedded_su emits a single line containing the word
"SUCCESS". The word SUCCESS may be followed by whitespace and
additional data. This data, if present, must be ignored.

Upon failure, embedded_su emits a single line containing the word
"ERROR", followed by a text block as described under "Text Bocks".
The text block gives an error message. The word ERROR may be followed
by whitespace and additional data. This data, if present, must be
ignored.

Text Blocks

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.

Internationalization

All messages are localized to the current locale; no further
localization is required.

SECURITY

embedded_su uses pam(3PAM) for authentication, account management,
and session management. Its primary function is to export the PAM
conversation mechanism to an unprivileged program. Like su(8), the
PAM configuration policy can be used to control embedded_su. The PAM
service name used is "embedded_su".

embedded_su is almost exactly equivalent to su(8) for security
purposes. The only exception is that it is slightly easier to use
embedded_su 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 embedded_su.

EXAMPLES

In the following examples, left angle brackets (<<<) indicate a line
written by embedded_su and read by the invoking application. Right
angle brackets (>>>) indicate a line written by the application and
read by embedded_su.

Example 1: Executing a command with the Correct Password

The following example shows an attempt to execute "somecommand" as
"someuser", with the correct password supplied:

/usr/lib/embedded_su someuser -c somecommand
>>>.
<<<CONV 1
<<<PAM_PROMPT_ECHO_OFF
<<<Password:
<<<.
>>>[ correct password ]
<<<SUCCESS
[ somecommand executes ]

Example 2: Executing a command with the Incorrect Password

The following example shows an attempt to execute "somecommand" as
"someuser", with the incorrect password supplied:

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

Example 3: Message Examples

A pam_message structure with msg_style equal to PAM_TEXT_INFO and msg
equal to "foo" produces:

PAM_TEXT_INFO
foo
.

A pam_message structure with msg_style equal to PAM_ERROR_MESSAGE and
msg equal to "bar\n" produces:

PAM_ERROR_MESSAGE
bar
[ blank line ]
.

A pam_message structure with msg_style equal to PAM_ERROR_MESSAGE and
msg equal to "aaa\nbbb" produces:

PAM_ERROR_MESSAGE
aaa
bbb
.

A pam_message structure with msg_style equal to PAM_TEXT_INFO and msg
equal to "" produces:

PAM_TEXT_INFO
[ blank line ]
.

A pam_message structure with msg_style equal to PAM_TEXT_INFO and msg
equal to NULL produces:

PAM_TEXT_INFO
.

Example 4: Disabling embedded_su

To disable embedded_su, add a line to the /etc/pam.conf file similar
to:

embedded_su auth requisite pam_deny.so.1

ATTRIBUTES