1KSU(1)                           MIT Kerberos                           KSU(1)
2
3
4

NAME

6       ksu - Kerberized super-user
7

SYNOPSIS

9       ksu [ target_user ] [ -n target_principal_name ] [ -c source_cache_name
10       ] [ -k ] [ -r time ] [ -p | -P] [ -f | -F] [ -l lifetime ] [ -z | Z ] [
11       -q ] [ -e command [ args ...  ] ] [ -a [ args ...  ] ]
12

REQUIREMENTS

14       Must  have  Kerberos  version  5 installed to compile ksu.  Must have a
15       Kerberos version 5 server running to use ksu.
16

DESCRIPTION

18       ksu is a Kerberized version of the su program that  has  two  missions:
19       one is to securely change the real and effective user ID to that of the
20       target user, and the other is to create a new security context.
21
22       NOTE:
23          For the sake of clarity, all references to  and  attributes  of  the
24          user  invoking  the  program will start with "source" (e.g., "source
25          user", "source cache", etc.).
26
27          Likewise, all references to and attributes  of  the  target  account
28          will start with "target".
29

AUTHENTICATION

31       To  fulfill  the first mission, ksu operates in two phases: authentica‐
32       tion and authorization.  Resolving the target  principal  name  is  the
33       first  step in authentication.  The user can either specify his princi‐
34       pal name with the -n option (e.g., -n jqpublic@USC.EDU)  or  a  default
35       principal  name will be assigned using a heuristic described in the OP‐
36       TIONS section (see -n option).  The target user name must be the  first
37       argument  to ksu; if not specified root is the default.  If . is speci‐
38       fied then the target user will be the source user (e.g.,  ksu  .).   If
39       the  source  user is root or the target user is the source user, no au‐
40       thentication or authorization takes place.  Otherwise, ksu looks for an
41       appropriate Kerberos ticket in the source cache.
42
43       The ticket can either be for the end-server or a ticket granting ticket
44       (TGT) for  the  target  principal's  realm.   If  the  ticket  for  the
45       end-server  is  already  in the cache, it's decrypted and verified.  If
46       it's not in the cache but the TGT is, the TGT is  used  to  obtain  the
47       ticket for the end-server.  The end-server ticket is then verified.  If
48       neither  ticket  is  in  the  cache,  but  ksu  is  compiled  with  the
49       GET_TGT_VIA_PASSWD  define,  the  user  will be prompted for a Kerberos
50       password which will then be used to get a TGT.  If the user  is  logged
51       in remotely and does not have a secure channel, the password may be ex‐
52       posed.  If neither ticket is in the cache and GET_TGT_VIA_PASSWD is not
53       defined, authentication fails.
54

AUTHORIZATION

56       This section describes authorization of the source user when ksu is in‐
57       voked without the -e option.  For a description of the -e  option,  see
58       the OPTIONS section.
59
60       Upon successful authentication, ksu checks whether the target principal
61       is authorized to access the target account.  In the target user's  home
62       directory, ksu attempts to access two authorization files: .k5login and
63       .k5users.  In the .k5login file each line contains the name of a  prin‐
64       cipal that is authorized to access the account.
65
66       For example:
67
68          jqpublic@USC.EDU
69          jqpublic/secure@USC.EDU
70          jqpublic/admin@USC.EDU
71
72       The  format  of  .k5users is the same, except the principal name may be
73       followed by a list of commands that the principal is authorized to exe‐
74       cute (see the -e option in the OPTIONS section for details).
75
76       Thus  if  the  target  principal name is found in the .k5login file the
77       source user is authorized to access the target account.  Otherwise  ksu
78       looks  in  the  .k5users  file.   If the target principal name is found
79       without any trailing commands or followed only by  *  then  the  source
80       user is authorized.  If either .k5login or .k5users exist but an appro‐
81       priate entry for the target principal does not exist then access is de‐
82       nied.  If neither file exists then the principal will be granted access
83       to the account according to the aname->lname mapping rules.  Otherwise,
84       authorization fails.
85

EXECUTION OF THE TARGET SHELL

87       Upon  successful  authentication  and  authorization, ksu proceeds in a
88       similar fashion to su.  The environment is unmodified with  the  excep‐
89       tion  of  USER,  HOME  and  SHELL variables.  If the target user is not
90       root, USER gets set to the target user name.   Otherwise  USER  remains
91       unchanged.   Both  HOME and SHELL are set to the target login's default
92       values.  In addition, the environment variable KRB5CCNAME gets  set  to
93       the  name  of  the  target  cache.   The real and effective user ID are
94       changed to that of the target user.  The target user's  shell  is  then
95       invoked  (the shell name is specified in the password file).  Upon ter‐
96       mination of the shell, ksu deletes the target cache (unless ksu is  in‐
97       voked  with  the -k option).  This is implemented by first doing a fork
98       and then an exec, instead of just exec, as done by su.
99

CREATING A NEW SECURITY CONTEXT

101       ksu can be used to create a new security context for the target program
102       (either the target shell, or command specified via the -e option).  The
103       target program inherits a set of credentials from the source user.   By
104       default,  this  set includes all of the credentials in the source cache
105       plus any additional credentials obtained  during  authentication.   The
106       source user is able to limit the credentials in this set by using -z or
107       -Z option.  -z restricts the copy of tickets from the source  cache  to
108       the target cache to only the tickets where client == the target princi‐
109       pal name.  The -Z option provides the target user with a  fresh  target
110       cache  (no  creds  in the cache).  Note that for security reasons, when
111       the source user is root and target user is non-root, -z option  is  the
112       default mode of operation.
113
114       While  no  authentication  takes place if the source user is root or is
115       the same as the target user, additional tickets can still  be  obtained
116       for  the  target  cache.   If -n is specified and no credentials can be
117       copied to the target cache, the source user is prompted for a  Kerberos
118       password  (unless -Z specified or GET_TGT_VIA_PASSWD is undefined).  If
119       successful, a TGT is obtained from the Kerberos server  and  stored  in
120       the  target  cache.  Otherwise, if a password is not provided (user hit
121       return) ksu continues in a normal mode of operation (the  target  cache
122       will  not contain the desired TGT).  If the wrong password is typed in,
123       ksu fails.
124
125       NOTE:
126          During authentication, only the tickets that could be obtained with‐
127          out providing a password are cached in the source cache.
128

OPTIONS

130       -n target_principal_name
131              Specify  a  Kerberos target principal name.  Used in authentica‐
132              tion and authorization phases of ksu.
133
134              If ksu is invoked without -n, a default principal  name  is  as‐
135              signed via the following heuristic:
136
137              • Case 1: source user is non-root.
138
139                If  the  target  user is the source user the default principal
140                name is set to the default principal of the source cache.   If
141                the  cache  does  not exist then the default principal name is
142                set to target_user@local_realm.   If  the  source  and  target
143                users  are  different  and  neither  ~target_user/.k5users nor
144                ~target_user/.k5login exist then the default principal name is
145                target_user_login_name@local_realm.   Otherwise, starting with
146                the first principal listed below, ksu checks if the  principal
147                is  authorized  to access the target account and whether there
148                is a legitimate ticket for that principal in the source cache.
149                If  both conditions are met that principal becomes the default
150                target principal, otherwise go to the next principal.
151
152                a. default principal of the source cache
153
154                b. target_user@local_realm
155
156                c. source_user@local_realm
157
158                If a-c fails try any principal for which there is a ticket  in
159                the  source  cache and that is authorized to access the target
160                account.  If that fails select the first principal that is au‐
161                thorized to access the target account from the above list.  If
162                none   are   authorized   and   ksu   is    configured    with
163                PRINC_LOOK_AHEAD  turned  on,  select the default principal as
164                follows:
165
166                For each candidate in the above  list,  select  an  authorized
167                principal  that  has the same realm name and first part of the
168                principal name equal to the prefix of the candidate.  For  ex‐
169                ample  if  candidate  a)  is jqpublic@ISI.EDU and jqpublic/se‐
170                cure@ISI.EDU is authorized to access the target  account  then
171                the default principal is set to jqpublic/secure@ISI.EDU.
172
173              • Case 2: source user is root.
174
175                If the target user is non-root then the default principal name
176                is target_user@local_realm.  Else, if the source cache  exists
177                the  default principal name is set to the default principal of
178                the source cache.  If the source cache does not exist, default
179                principal name is set to root\@local_realm.
180
181       -c source_cache_name
182          Specify  source cache name (e.g., -c FILE:/tmp/my_cache).  If -c op‐
183          tion is not used then the name is obtained from KRB5CCNAME  environ‐
184          ment  variable.   If KRB5CCNAME is not defined the source cache name
185          is set to krb5cc_<source uid>.  The target cache name  is  automati‐
186          cally  set  to krb5cc_<target uid>.(gen_sym()), where gen_sym gener‐
187          ates a new number such that the resulting cache does not already ex‐
188          ist.  For example:
189
190              krb5cc_1984.2
191
192       -k     Do  not  delete  the target cache upon termination of the target
193              shell or a command (-e command).  Without -k,  ksu  deletes  the
194              target cache.
195
196       -z     Restrict the copy of tickets from the source cache to the target
197              cache to only the tickets where client == the  target  principal
198              name.   Use the -n option if you want the tickets for other then
199              the default principal.  Note that the -z option is mutually  ex‐
200              clusive with the -Z option.
201
202       -Z     Don't  copy  any  tickets  from  the  source cache to the target
203              cache.  Just create a fresh  target  cache,  where  the  default
204              principal name of the cache is initialized to the target princi‐
205              pal name.  Note that the -Z option is  mutually  exclusive  with
206              the -z option.
207
208       -q     Suppress the printing of status messages.
209
210       Ticket granting ticket options:
211
212       -l lifetime -r time -p -P -f -F
213              The  ticket granting ticket options only apply to the case where
214              there are no appropriate tickets in the  cache  to  authenticate
215              the  source  user.   In this case if ksu is configured to prompt
216              users for a Kerberos password (GET_TGT_VIA_PASSWD  is  defined),
217              the  ticket  granting  ticket options that are specified will be
218              used when getting a ticket granting  ticket  from  the  Kerberos
219              server.
220
221       -l lifetime
222              (Time  duration string.)  Specifies the lifetime to be requested
223              for the ticket; if this option is  not  specified,  the  default
224              ticket lifetime (12 hours) is used instead.
225
226       -r time
227              (Time  duration  string.)   Specifies  that the renewable option
228              should be requested for the ticket, and  specifies  the  desired
229              total lifetime of the ticket.
230
231       -p     specifies  that the proxiable option should be requested for the
232              ticket.
233
234       -P     specifies that the proxiable option should not be requested  for
235              the  ticket,  even  if  the  default configuration is to ask for
236              proxiable tickets.
237
238       -f     option specifies that the forwardable option should be requested
239              for the ticket.
240
241       -F     option  specifies  that the forwardable option should not be re‐
242              quested for the ticket, even if the default configuration is  to
243              ask for forwardable tickets.
244
245       -e command [args ...]
246              ksu  proceeds  exactly the same as if it was invoked without the
247              -e option, except instead of executing the target shell, ksu ex‐
248              ecutes the specified command. Example of usage:
249
250                 ksu bob -e ls -lag
251
252              The authorization algorithm for -e is as follows:
253
254              If the source user is root or source user == target user, no au‐
255              thorization takes place and the command is executed.  If  source
256              user id != 0, and ~target_user/.k5users file does not exist, au‐
257              thorization fails.  Otherwise, ~target_user/.k5users  file  must
258              have  an  appropriate  entry  for target principal to get autho‐
259              rized.
260
261              The .k5users file format:
262
263              A single principal entry on each line that may be followed by  a
264              list of commands that the principal is authorized to execute.  A
265              principal name followed by a * means that the user is authorized
266              to execute any command.  Thus, in the following example:
267
268                 jqpublic@USC.EDU ls mail /local/kerberos/klist
269                 jqpublic/secure@USC.EDU *
270                 jqpublic/admin@USC.EDU
271
272              jqpublic@USC.EDU  is  only  authorized  to  execute ls, mail and
273              klist commands.  jqpublic/secure@USC.EDU is authorized  to  exe‐
274              cute  any  command.  jqpublic/admin@USC.EDU is not authorized to
275              execute any command.  Note, that jqpublic/admin@USC.EDU  is  au‐
276              thorized  to  execute the target shell (regular ksu, without the
277              -e option) but jqpublic@USC.EDU is not.
278
279              The commands listed after the principal name must  be  either  a
280              full  path  names or just the program name.  In the second case,
281              CMD_PATH specifying the location of authorized programs must  be
282              defined at the compilation time of ksu.  Which command gets exe‐
283              cuted?
284
285              If the source user is root or the target user is the source user
286              or  the user is authorized to execute any command (* entry) then
287              command can be either a full or a relative path leading  to  the
288              target  program.  Otherwise, the user must specify either a full
289              path or just the program name.
290
291       -a args
292              Specify arguments to be passed to the target shell.   Note  that
293              all  flags  and  parameters  following  -a will be passed to the
294              shell, thus all options intended for ksu must precede -a.
295
296              The -a option can be used to simulate the -e option if  used  as
297              follows:
298
299                 -a -c [command [arguments]].
300
301              -c is interpreted by the c-shell to execute the command.
302

INSTALLATION INSTRUCTIONS

304       ksu can be compiled with the following four flags:
305
306       GET_TGT_VIA_PASSWD
307              In  case  no  appropriate tickets are found in the source cache,
308              the user will be prompted for a Kerberos password.  The password
309              is  then  used to get a ticket granting ticket from the Kerberos
310              server.  The danger of configuring ksu with this macro is if the
311              source  user  is  logged  in remotely and does not have a secure
312              channel, the password may get exposed.
313
314       PRINC_LOOK_AHEAD
315              During  the  resolution   of   the   default   principal   name,
316              PRINC_LOOK_AHEAD  enables  ksu  to  find  principal names in the
317              .k5users file as described in the OPTIONS section  (see  -n  op‐
318              tion).
319
320       CMD_PATH
321              Specifies  a  list of directories containing programs that users
322              are authorized to execute (via .k5users file).
323
324       HAVE_GETUSERSHELL
325              If the source user is non-root,  ksu  insists  that  the  target
326              user's  shell to be invoked is a "legal shell".  getusershell(3)
327              is called to obtain the names of "legal shells".  Note that  the
328              target user's shell is obtained from the passwd file.
329
330       Sample configuration:
331
332          KSU_OPTS = -DGET_TGT_VIA_PASSWD -DPRINC_LOOK_AHEAD -DCMD_PATH='"/bin /usr/ucb /local/bin"
333
334       ksu should be owned by root and have the set user id bit turned on.
335
336       ksu attempts to get a ticket for the end server just as Kerberized tel‐
337       net and rlogin.  Thus, there must be an entry for  the  server  in  the
338       Kerberos  database  (e.g.,  host/nii.isi.edu@ISI.EDU).  The keytab file
339       must be in an appropriate location.
340

SIDE EFFECTS

342       ksu deletes all expired tickets from the source cache.
343

AUTHOR OF KSU

345       GENNADY (ARI) MEDVINSKY
346

ENVIRONMENT

348       See kerberos for a description of Kerberos environment variables.
349

SEE ALSO

351       kerberos, kinit
352

AUTHOR

354       MIT
355
357       1985-2023, MIT
358
359
360
361
3621.21                                                                    KSU(1)
Impressum