embedded_su man page on SmartOS

Man page or keyword search:  
man Server   16655 pages
apropos Keyword Search (all sections)
Output format
SmartOS logo
[printable version]

EMBEDDED_SU(1M)						       EMBEDDED_SU(1M)

NAME
       embedded_su  -  allow an application to prompt for credentials and exe‐
       cute 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 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  dis‐
       play. 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 send‐
       ing 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 "SUC‐
       CESS". 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 localiza‐
       tion is required.

   SECURITY
       embedded_su uses pam(3PAM) for authentication, account management,  and
       session management. Its primary function is to export the PAM conversa‐
       tion mechanism to an unprivileged program. Like su(1M), the PAM config‐
       uration policy can be used to control embedded_su. The PAM service name
       used is "embedded_su".

       embedded_su is almost exactly equivalent to su(1M)  for	security  pur‐
       poses.  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 pro‐
       viding  secret  data.  For those sites needing maximum security, poten‐
       tially at the expense of application functionality, the	EXAMPLES  sec‐
       tion 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
       See attributes(5) for descriptions of the following attributes:

       ┌────────────────────┬─────────────────┐
       │  ATTRIBUTE TYPE    │ ATTRIBUTE VALUE │
       ├────────────────────┼─────────────────┤
       │Interface Stability │ Stable	      │
       └────────────────────┴─────────────────┘

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

				 Feb 10, 2005		       EMBEDDED_SU(1M)
[top]

List of man pages available for SmartOS

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net