1embedded_su(1M)         System Administration Commands         embedded_su(1M)
2
3
4

NAME

6       embedded_su  -  allow an application to prompt for credentials and exe‐
7       cute commands as the super user or another user
8

SYNOPSIS

10       /usr/lib/embedded_su [-] [username [arg...]]
11
12

DESCRIPTION

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
19
20       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
27   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
33   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
40   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
44
45       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
51
52       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
57
58       A  message  header  line  consists  of  a  PAM  message  style name, as
59       described in pam_start(3PAM). The message header values are:
60
61       PAM_PROMPT_ECHO_OFF    The application is to  prompt  the  user  for  a
62                              value, with echoing disabled.
63
64
65       PAM_PROMPT_ECHO_ON     The  application  is  to  prompt  the user for a
66                              value, with echoing enabled.
67
68
69       PAM_ERROR_MSG          The application is to display the message  in  a
70                              form appropriate for displaying an error.
71
72
73       PAM_TEXT_INFO          The  application  is to display the message in a
74                              form appropriate for general information.
75
76
77
78       The PAM message style may be  followed  by  whitespace  and  additional
79       data. This data, if present, must be ignored.
80
81
82       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
87   Phase 3: Completion
88       After zero or more conversation  blocks,  embedded_su  emits  a  result
89       block instead of a conversation block.
90
91
92       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
96
97       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
102   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
108   Internationalization
109       All  messages are localized to the current locale; no further localiza‐
110       tion is required.
111
112   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
119
120       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

EXAMPLES

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
133       Example 1 Executing a command with the Correct Password
134
135
136       The following example shows an  attempt  to  execute  "somecommand"  as
137       "someuser", with the correct password supplied:
138
139
140          /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
150
151
152       Example 2 Executing a command with the Incorrect Password
153
154
155       The  following  example  shows  an  attempt to execute "somecommand" as
156       "someuser", with the incorrect password supplied:
157
158
159          /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
172
173
174       Example 3 Message Examples
175
176
177       A pam_message structure with msg_style equal to PAM_TEXT_INFO  and  msg
178       equal to "foo" produces:
179
180
181         PAM_TEXT_INFO
182         foo
183         .
184
185
186
187
188       A  pam_message  structure with msg_style equal to PAM_ERROR_MESSAGE and
189       msg equal to "bar\n" produces:
190
191
192         PAM_ERROR_MESSAGE
193         bar
194         [ blank line ]
195         .
196
197
198
199
200       A pam_message structure with msg_style equal to  PAM_ERROR_MESSAGE  and
201       msg equal to "aaa\nbbb" produces:
202
203
204         PAM_ERROR_MESSAGE
205         aaa
206         bbb
207         .
208
209
210
211
212       A  pam_message  structure with msg_style equal to PAM_TEXT_INFO and msg
213       equal to "" produces:
214
215
216         PAM_TEXT_INFO
217         [ blank line ]
218         .
219
220
221
222
223       A pam_message structure with msg_style equal to PAM_TEXT_INFO  and  msg
224       equal to NULL produces:
225
226
227         PAM_TEXT_INFO
228         .
229
230
231
232       Example 4 Disabling embedded_su
233
234
235       To  disable  embedded_su,  add a line to the /etc/pam.conf file similar
236       to:
237
238
239         embedded_su  auth  requisite  pam_deny.so.1
240
241
242

ATTRIBUTES

244       See attributes(5) for descriptions of the following attributes:
245
246
247
248
249       ┌─────────────────────────────┬─────────────────────────────┐
250       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
251       ├─────────────────────────────┼─────────────────────────────┤
252       │Availability                 │SUNWcsu                      │
253       ├─────────────────────────────┼─────────────────────────────┤
254       │Interface Stability          │Stable                       │
255       └─────────────────────────────┴─────────────────────────────┘
256

SEE ALSO

258       su(1M), pam(3PAM), pam_start(3PAM), attributes(5), rbac(5)
259
260
261
262SunOS 5.11                        10 Feb 2005                  embedded_su(1M)
Impressum