1embedded_su(1M) System Administration Commands embedded_su(1M)
2
6 embedded_su - allow an application to prompt for credentials and exe‐
7 cute commands as the super user or another user
8
10 /usr/lib/embedded_su [-] [username [arg...]]
11
14 The embedded_su command allows an application to prompt the user for
15 security credentials and then use those credentials to execute a pro‐
16 gram as another user or role (see rbac(5) for information on role-based
17 access control). The default username is root (super user).
18 embedded_su is identical to su(1M), except that the user interaction is
21 packaged in a form suitable for another program to interpret and dis‐
22 play. Typically, embedded_su would be used to allow a graphical program
23 to prompt for the super user password and execute a command as the
24 super user, without requiring that the requesting program be run as the
25 super user.
26 PROTOCOL
28 embedded_su implements a simple protocol over standard input, standard
29 output, and standard error. This protocol consists of three phases,
30 roughly corresponding to PAM initialization, the PAM dialog, and PAM
31 completion.
32 Phase 1: Initialization
34 After starting embedded_su, the application must send an initialization
35 block on embedded_su's standard input. This block is a text block, as
36 described under "Text Blocks". There are currently no initialization
37 parameters defined; the application should send an empty block by send‐
38 ing a line consisting solely of a period (.).
39 Phase 2: Conversation
41 embedded_su then emits zero or more conversation blocks on its standard
42 output. Each conversation block may require zero or more responses.
43 A conversation block starts with a line consisting of the word CONV,
46 followed by whitespace, followed by the number of messages in the con‐
47 versation block as a decimal integer. The number of messages may be
48 followed by whitespace and additional data. This data, if present, must
49 be ignored.
50 Each message consists of a line containing a header followed by a text
53 block, as described under "Text Blocks". A single newline is appended
54 to each message, allowing the message to end with a line that does not
55 end with a newline.
56 A message header line consists of a PAM message style name, as
59 described in pam_start(3PAM). The message header values are:
60 PAM_PROMPT_ECHO_OFF The application is to prompt the user for a
62 value, with echoing disabled.
63 PAM_PROMPT_ECHO_ON The application is to prompt the user for a
66 value, with echoing enabled.
67 PAM_ERROR_MSG The application is to display the message in a
70 form appropriate for displaying an error.
71 PAM_TEXT_INFO The application is to display the message in a
74 form appropriate for general information.
75 The PAM message style may be followed by whitespace and additional
79 data. This data, if present, must be ignored.
80 After writing all of the messages in the conversation block, if any of
83 them were PAM_PROMPT_ECHO_OFF or PAM_PROMPT_ECHO_ON, embedded_su waits
84 for the response values. It expects the response values one per line,
85 in the order the messages were given.
86 Phase 3: Completion
88 After zero or more conversation blocks, embedded_su emits a result
89 block instead of a conversation block.
90 Upon success, embedded_su emits a single line containing the word "SUC‐
93 CESS". The word SUCCESS may be followed by whitespace and additional
94 data. This data, if present, must be ignored.
95 Upon failure, embedded_su emits a single line containing the word
98 "ERROR", followed by a text block as described under "Text Bocks". The
99 text block gives an error message. The word ERROR may be followed by
100 whitespace and additional data. This data, if present, must be ignored.
101 Text Blocks
103 Initialization blocks, message blocks, and error blocks are all text
104 blocks. These are blocks of text that are terminated by a line contain‐
105 ing a single period (.). Lines in the block that begin with a "." have
106 an extra "." prepended to them.
107 Internationalization
109 All messages are localized to the current locale; no further localiza‐
110 tion is required.
111 SECURITY
113 embedded_su uses pam(3PAM) for authentication, account management, and
114 session management. Its primary function is to export the PAM conversa‐
115 tion mechanism to an unprivileged program. Like su(1M), the PAM config‐
116 uration policy can be used to control embedded_su. The PAM service name
117 used is "embedded_su".
118 embedded_su is almost exactly equivalent to su(1M) for security pur‐
121 poses. The only exception is that it is slightly easier to use embed‐
122 ded_su in writing a malicious program that might trick a user into pro‐
123 viding secret data. For those sites needing maximum security, poten‐
124 tially at the expense of application functionality, the EXAMPLES sec‐
125 tion shows how to disable embedded_su.
126
128 In the following examples, left angle brackets (<<<) indicate a line
129 written by embedded_su and read by the invoking application. Right
130 angle brackets (>>>) indicate a line written by the application and
131 read by embedded_su.
132 Example 1 Executing a command with the Correct Password
134 The following example shows an attempt to execute "somecommand" as
137 "someuser", with the correct password supplied:
138 /usr/lib/embedded_su someuser -c somecommand
141 >>>.
142 <<<CONV 1
143 <<<PAM_PROMPT_ECHO_OFF
144 <<<Password:
145 <<<.
146 >>>[ correct password ]
147 <<<SUCCESS
148 [ somecommand executes ]
149 Example 2 Executing a command with the Incorrect Password
153 The following example shows an attempt to execute "somecommand" as
156 "someuser", with the incorrect password supplied:
157 /usr/lib/embedded_su someuser -c somecommand
160 >>>.
161 <<<CONV 1
162 <<<PAM_PROMPT_ECHO_OFF
163 <<<Password:
164 <<<.
165 >>>[ incorrect password ]
166 [ delay ]
167 <<<ERROR
168 <<<embedded_su:Sorry
169 <<<.
170 [ exit ]
171 Example 3 Message Examples
175 A pam_message structure with msg_style equal to PAM_TEXT_INFO and msg
178 equal to "foo" produces:
179 PAM_TEXT_INFO
182 foo
183 .
184 A pam_message structure with msg_style equal to PAM_ERROR_MESSAGE and
189 msg equal to "bar\n" produces:
190 PAM_ERROR_MESSAGE
193 bar
194 [ blank line ]
195 .
196 A pam_message structure with msg_style equal to PAM_ERROR_MESSAGE and
201 msg equal to "aaa\nbbb" produces:
202 PAM_ERROR_MESSAGE
205 aaa
206 bbb
207 .
208 A pam_message structure with msg_style equal to PAM_TEXT_INFO and msg
213 equal to "" produces:
214 PAM_TEXT_INFO
217 [ blank line ]
218 .
219 A pam_message structure with msg_style equal to PAM_TEXT_INFO and msg
224 equal to NULL produces:
225 PAM_TEXT_INFO
228 .
229 Example 4 Disabling embedded_su
233 To disable embedded_su, add a line to the /etc/pam.conf file similar
236 to:
237 embedded_su auth requisite pam_deny.so.1
240
244 See attributes(5) for descriptions of the following attributes:
245 ┌─────────────────────────────┬─────────────────────────────┐
250 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
251 ├─────────────────────────────┼─────────────────────────────┤
252 │Availability │SUNWcsu │
253 ├─────────────────────────────┼─────────────────────────────┤
254 │Interface Stability │Stable │
255 └─────────────────────────────┴─────────────────────────────┘
256
258 su(1M), pam(3PAM), pam_start(3PAM), attributes(5), rbac(5)
259SunOS 5.11 10 Feb 2005 embedded_su(1M)