embedded_su(1M) 														   embedded_su(1M)

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...]]

       The  embedded_su command allows an application to prompt the user for security credentials and then use those credentials to execute a pro-
       gram as another user or role (see rbac(5) for information on role-based access control). The default username is root (super user).

       embedded_su is identical to su(1M), 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 con-
       versation 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  con-
       taining 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 con-
       versation mechanism to an unprivileged program. Like su(1M), the PAM configuration policy can be used to control embedded_su. The PAM  ser-
       vice name used is "embedded_su".

       embedded_su  is	almost	exactly equivalent to su(1M) for security purposes. The only exception is that it is slightly easier to use embed-
       ded_su in writing a malicious program that might trick a user into providing secret data. For those sites needing maximum security,  poten-
       tially 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
" produces:

       PAM_ERROR_MESSAGE
       bar
       [ blank line ]
       .

       A pam_message structure with msg_style equal to PAM_ERROR_MESSAGE and msg equal to "aaa
bbb" 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

       See attributes(5) for descriptions of the following attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Availability		     |SUNWcsu			   |
       +-----------------------------+-----------------------------+
       |Interface Stability	     |Stable			   |
       +-----------------------------+-----------------------------+

       su(1M), pam(3PAM), pam_start(3PAM), attributes(5), rbac(5)

								    20 Apr 2005 						   embedded_su(1M)