src/clients/ksu/ksu.M

   1 .\" Copyright (c) 1994 by the University of Southern California
   2 .\"
   3 .\" EXPORT OF THIS SOFTWARE from the United States of America may
   4 .\"     require a specific license from the United States Government.
   5 .\"     It is the responsibility of any person or organization contemplating
   6 .\"     export to obtain such a license before exporting.
   7 .\"
   8 .\" WITHIN THAT CONSTRAINT, permission to copy, modify, and distribute
   9 .\"     this software and its documentation in source and binary forms is
  10 .\"     hereby granted, provided that any documentation or other materials
  11 .\"     related to such distribution or use acknowledge that the software
  12 .\"     was developed by the University of Southern California.
  13 .\"
  14 .\" DISCLAIMER OF WARRANTY.  THIS SOFTWARE IS PROVIDED "AS IS".  The
  15 .\"     University of Southern California MAKES NO REPRESENTATIONS OR
  16 .\"     WARRANTIES, EXPRESS OR IMPLIED.  By way of example, but not
  17 .\"     limitation, the University of Southern California MAKES NO
  18 .\"     REPRESENTATIONS OR WARRANTIES OF MERCHANTABILITY OR FITNESS FOR ANY
  19 .\"     PARTICULAR PURPOSE. The University of Southern
  20 .\"     California shall not be held liable for any liability nor for any
  21 .\"     direct, indirect, or consequential damages with respect to any
  22 .\"     claim by the user or distributor of the ksu software.
  23 .\"
  24 .\" KSU was written by:  Ari Medvinsky, ari@isi.edu
  25 .\" "
  26 .TH KSU 1
  27 .SH NAME
  28 ksu \- Kerberized super-user
  29 .SH SYNOPSIS
  30 .B ksu
  31 [
  32 .I target_user
  33 ] [
  34 .B \-n
  35 .I target_principal_name
  36 ] [
  37 .B \-c
  38 .I source_cache_name
  39 ] [
  40 .B \-k
  41 ] [
  42 .B \-D
  43 ] [
  44 .B \-r
  45 .I time
  46 ] [
  47 .B \-pf
  48 ] [
  49 .B \-l
  50 .I lifetime
  51 ] [
  52 .B \-zZ
  53 ] [
  54 .B \-q
  55 ] [
  56 .B \-e
  57 .I command
  58 [
  59 .I args ...
  60 ] ] [
  61 .B \-a
  62 [
  63 .I args ...
  64 ] ]
  65 .br
  66 .SH REQUIREMENTS
  67 Must have Kerberos version 5 installed to compile ksu.
  68 Must have a Kerberos version 5 server running to use ksu.
  69 .br
  70 .SH DESCRIPTION
  71 .I ksu
  72 is a Kerberized version of the su program that has two missions:
  73 one is to securely change the real and effective user ID to that
  74 of the target user, and the other is to create a new security context.
  75 For the sake of clarity, all references to and attributes of
  76 the user invoking the program will start with 'source' (e.g.
  77 source user, source cache, etc.).  Likewise, all references
  78 to and attributes of the target account will start with 'target'.
  79 .br
  80 .SH AUTHENTICATION
  81 To fulfill the first mission, ksu operates in two phases: authentication
  82 and authorization.  Resolving the target principal name is the
  83 first step in authentication.  The user
  84 can either specify his principal name with the
  85 .B \-n
  86 option
  87 (e.g.
  88 .B \-n
  89 jqpublic@USC.EDU) or a default principal name will be assigned
  90 using a heuristic described in the OPTIONS section (see
  91 .B \-n
  92 option).
  93 The target user name must be the first argument to ksu; if not specified
  94 root is the default.  If '.' is specified then the target user will be
  95 the source user (e.g. ksu .).
  96 If the source user is root or the target user is the source user, no
  97 authentication or authorization takes place.  Otherwise, ksu looks
  98 for an appropriate Kerberos ticket in the source cache.
  99 .PP
 100 The ticket can either be for
 101 the end-server
 102 or a ticket granting ticket (TGT) for the target principal's realm.  If the
 103 ticket for the end-server is already in the cache, it's decrypted and
 104 verified.  If it's not in the cache but the TGT is, the TGT is used to
 105 obtain the ticket for the end-server.   The end-server ticket is then
 106 verified.  If neither ticket is in the cache, but ksu is compiled
 107 with the GET_TGT_VIA_PASSWD define, the user will be prompted
 108 for a Kerberos password which will then be used to get a TGT.
 109 If the user is logged in remotely and
 110 does not have a secure channel, the password may be exposed.
 111 If neither ticket is in the cache and GET_TGT_VIA_PASSWD is not defined,
 112 authentication fails.
 113 .br
 114 .SH AUTHORIZATION
 115 This section describes authorization of the source user when ksu
 116 is invoked without the
 117 .B \-e
 118 option.
 119 For a description of the
 120 .B \-e
 121 option, see the OPTIONS section.
 122 .PP
 123 Upon successful authentication, ksu checks whether the target principal
 124 is authorized to access the target account.
 125 In the target user's home directory, ksu attempts to access
 126 two authorization files: .k5login and .k5users.  In the .k5login
 127 file each line contains the name of a
 128 principal that is authorized to access the account.
 129 .TP 12
 130 For example:
 131 jqpublic@USC.EDU
 132 .br
 133 jqpublic/secure@USC.EDU
 134 .br
 135 jqpublic/admin@USC.EDU
 136 .PP
 137 The format of .k5users is the same, except the
 138 principal name may be followed by a list of commands that
 139 the principal is authorized to execute. (see the
 140 .B \-e
 141 option in the OPTIONS section for details).
 142 .PP
 143 Thus if the target principal
 144 name is found in the .k5login file the source user is authorized to access
 145 the target account. Otherwise ksu looks in the .k5users file.
 146 If the target principal name is found without any trailing commands
 147 or followed only by '*' then the source user is authorized.
 148 If either .k5login or .k5users exist but an appropriate entry for the target
 149 principal does not exist then access is denied. If neither
 150 file exists then the principal will be granted access
 151 to the account according to the aname\->lname mapping rules (see
 152 .IR krb5_anadd(8)
 153 for more details).
 154 Otherwise, authorization fails.
 155 .br
 156 .SH EXECUTION OF THE TARGET SHELL
 157 Upon successful authentication and authorization, ksu
 158 proceeds in a similar fashion to su.  The environment
 159 is unmodified with the exception of USER, HOME and SHELL variables.
 160 If the target user is not root, USER gets set to the target user
 161 name. Otherwise USER remains unchanged. Both HOME and SHELL are
 162 set to the target login's default values.
 163 In addition, the environment variable KRB5CCNAME gets set to the
 164 name of the target cache.
 165 The real and effective user ID are changed to that of the
 166 target user.  The target user's shell is then invoked
 167 (the shell name is specified in the password file).
 168 Upon termination of the shell, ksu deletes the target cache (unless
 169 ksu is invoked with the
 170 .B \-k option).
 171 This is implemented by first doing a fork and then an exec, instead
 172 of just exec, as done by su.
 173 .br
 174 .SH CREATING A NEW SECURITY CONTEXT
 175 .PP
 176 Ksu can be used to create a new security context for the
 177 target program (either the target
 178 shell, or command specified via the -e option).
 179 The target program inherits a set
 180 of credentials from the source user.
 181 By default, this set includes all of the credentials
 182 in the source cache plus any
 183 additional credentials obtained during authentication.
 184 The source user is able to limit the credentials in this set
 185 by using -z or -Z option.
 186 -z restricts the copy of tickets from the source cache
 187 to the target cache to only the tickets where client ==
 188 the target principal name.  The -Z option
 189 provides the target user with a fresh target cache
 190 (no creds in the cache). Note that for security reasons,
 191 when the source user is root and target user is non-root,
 192 -z option is the default mode of operation.
 193
 194 While no authentication takes place if the source user
 195 is root or is the same as the target user, additional
 196 tickets can still be obtained for the target cache.
 197 If -n is specified and no credentials can be copied to the target
 198 cache,  the  source user is prompted for a Kerberos password
 199 (unless -Z specified or GET_TGT_VIA_PASSWD is undefined). If
 200 successful,  a  TGT is obtained from the Kerberos server and
 201 stored in the target cache.  Otherwise,
 202 if a password is not provided (user hit return)
 203 ksu continues  in  a
 204 normal  mode  of  operation (the target cache will
 205 not contain the desired TGT).
 206 If the wrong password is typed in, ksu fails.
 207 .PP
 208 \fISide Note:\fP during authentication, only the tickets that could be
 209 obtained without providing a password are cached in
 210 in the source cache.
 211 .SH OPTIONS
 212 .TP 10
 213 \fB\-n \fItarget_principal_name
 214 Specify a Kerberos target principal name.
 215 Used in authentication and authorization
 216 phases of ksu.
 217
 218 If ksu is invoked without
 219 .B \-n,
 220 a default principal name is
 221 assigned via the following heuristic:
 222
 223 \fICase 1:\fP source user is non-root.
 224 .br
 225 If the target user is the source user the default principal name
 226 is set to the default principal of the source cache. If the
 227 cache does not exist then the default principal name is set to
 228 target_user@local_realm.
 229 If the source and target users are different and
 230 neither ~target_user/.k5users
 231 nor ~target_user/.k5login exist then
 232 the default principal name is
 233 target_user_login_name@local_realm. Otherwise,
 234 starting with the first principal listed below,
 235 ksu checks if the principal is authorized
 236 to  access the target account and whether
 237 there is a legitimate ticket for that principal
 238 in the source cache. If both conditions are met
 239 that principal becomes the default target principal,
 240 otherwise go to the next principal.
 241
 242 a) default principal of the source cache
 243 .br
 244 b) target_user@local_realm
 245 .br
 246 c) source_user@local_realm
 247
 248 If a-c fails try any principal for which there is
 249 a ticket in the source cache and that is
 250 authorized to access the target account.
 251 If that fails select the first principal that
 252 is authorized to access the target account from
 253 the above list.
 254 If none are authorized and ksu is configured with PRINC_LOOK_AHEAD
 255 turned on, select the default principal as follows:
 256
 257 For each candidate in the above list,
 258 select an authorized principal that has
 259 the same realm name and first part
 260 of the principal name equal to the prefix of the candidate.
 261 For example if candidate a) is jqpublic@ISI.EDU and jqpublic/secure@ISI.EDU
 262 is authorized to access the target account then the default principal
 263 is set to jqpublic/secure@ISI.EDU.
 264
 265 \fICase 2:\fP source user is root.
 266 .br
 267 If the target user is non-root then the
 268 default principal name is target_user@local_realm.
 269 Else, if the source cache exists the default
 270 principal name is set to the default principal
 271 of the source cache. If the source cache does not
 272 exist, default principal name is set to
 273 root@local_realm.
 274 .TP 10
 275 \fB\-c \fIsource_cache_name
 276 Specify source cache name (e.g.
 277 .B \-c
 278 FILE:/tmp/my_cache).
 279 If
 280 .B \-c
 281 option is not used then the
 282 name is obtained from KRB5CCNAME environment variable.
 283 If KRB5CCNAME is not defined the source cache name
 284 is set to krb5cc_<source uid>.
 285 The target cache name is automatically
 286 set to krb5cc_<target uid>.(gen_sym()),
 287 where gen_sym generates a new number such that
 288 the resulting cache does not already exist.
 289 .br
 290 For example: krb5cc_1984.2
 291 .TP 10
 292 \fB\-k
 293 Do not delete the target cache upon termination of the
 294 target shell or a command (
 295 .B \-e
 296 command).
 297 Without
 298 .B \-k,
 299 ksu deletes the target cache.
 300 .TP 10
 301 \fB\-D
 302 turn on debug mode.
 303 .TP 10
 304 \fITicket granting ticket options: -l lifetime -r time -pf\fP
 305 The ticket granting ticket options only apply to the
 306 case where there are no appropriate tickets in
 307 the cache to authenticate the source user. In this case
 308 if ksu is configured to prompt users for a
 309 Kerberos password (GET_TGT_VIA_PASSWD is defined),
 310 the ticket granting
 311 ticket options that are specified will be used
 312 when getting a ticket granting ticket from the Kerberos
 313 server.
 314 .TP 10
 315 \fB\-l \fIlifetime
 316 option specifies the lifetime to be
 317 requested for the ticket; if this option is not
 318 specified, the  default ticket lifetime
 319 (configured by each site) is used instead.
 320 .TP 10
 321 \fB\-r \fItime
 322 option  specifies  that  the  RENEWABLE  option
 323 should be requested for the ticket, and specifies
 324 the desired total lifetime of the ticket.
 325 .TP 10
 326 \fB\-p
 327 option specifies that the PROXIABLE option should  be
 328 requested for the ticket.
 329 .TP 10
 330 \fB\-f
 331 option specifies that the FORWARDABLE  option  should
 332 be requested for the ticket.
 333 .TP 10
 334 \fB\-z
 335 restrict the copy of tickets from the source cache
 336 to the target cache to only the tickets where client ==
 337 the target principal name. Use the
 338 .B \-n
 339 option
 340 if you want the tickets for other then the default
 341 principal. Note that the
 342 .B \-z
 343 option is mutually
 344 exclusive with the -Z option.
 345 .TP 10
 346 \fB\-Z
 347 Don't copy any tickets from the source cache to the
 348 target cache. Just create a fresh target cache,
 349 where the default principal name of the cache is
 350 initialized to the target principal name.  Note that
 351 .B \-Z
 352 option is mutually
 353 exclusive with the -z option.
 354 .TP 10
 355 \fB\-q
 356 suppress the printing of status messages.
 357 .TP 10
 358 \fB\-e \fIcommand [args ...]
 359 ksu proceeds exactly the same as if it was invoked without the
 360 .B \-e
 361 option,
 362 except instead of executing the target shell, ksu executes the
 363 specified command (Example of usage: ksu bob
 364 .B \-e
 365 ls
 366 .B \-lag).
 367
 368 \fIThe authorization algorithm for -e is as follows:\fP
 369
 370 If the source user is root or source user == target user,
 371 no authorization takes place and
 372 the command is executed.  If source user id != 0, and ~target_user/.k5users
 373 file does not exist, authorization fails.
 374 Otherwise, ~target_user/.k5users file must have an
 375 appropriate entry for target principal
 376 to get authorized.
 377
 378 \fIThe .k5users file format:\fP
 379
 380 A single principal entry on each line
 381 that may be followed by a list of commands that
 382 the principal is authorized to execute.
 383 A principal name followed by a '*' means
 384 that the user is authorized to execute
 385 any command. Thus, in the following example:
 386
 387 jqpublic@USC.EDU ls mail /local/kerberos/klist
 388 .br
 389 jqpublic/secure@USC.EDU *
 390 .br
 391 jqpublic/admin@USC.EDU
 392
 393 jqpublic@USC.EDU is only authorized to execute ls, mail
 394 and klist commands. jqpublic/secure@USC.EDU is authorized
 395 to execute any command. jqpublic/admin@USC.EDU is not
 396 authorized to execute any command.  Note, that
 397 jqpublic/admin@USC.EDU is authorized to execute
 398 the target shell (regular ksu, without the
 399 .B \-e
 400 option) but jqpublic@USC.EDU is not.
 401
 402 The commands listed after the principal name must
 403 be either a full path names or just the program name.
 404 In the second case, CMD_PATH specifying the location
 405 of authorized programs must be defined at the
 406 compilation time of ksu.
 407
 408 \fIWhich command gets executed ?\fP
 409
 410 If the source user is root or
 411 the target user is the source user or
 412 the user
 413 is authorized to execute any command ('*' entry)
 414 then command can be either a full or a relative
 415 path leading to the target program.
 416 Otherwise, the user must specify either a full
 417 path or just the program name.
 418 .TP 10
 419 \fB\-a \fIargs
 420 specify arguments to be passed to the target shell.
 421 Note: that all flags and parameters following -a
 422 will be passed to the shell, thus all options
 423 intended for ksu must precede
 424 .B \-a.
 425 The
 426 .B \-a
 427 option can be used to simulate the
 428 .B \-e
 429 option if used as follows:
 430 .B \-a
 431 .B \-c
 432 [command [arguments]].
 433 .B \-c
 434 is interpreted by the c-shell to execute the command.
 435 .PP
 436 .SH INSTALLATION INSTRUCTIONS
 437 ksu can be compiled with the following 4 flags (see the Imakefile):
 438 .TP 10
 439 \fIGET_TGT_VIA_PASSWD\fP
 440 in case no appropriate tickets are found in the source
 441 cache, the user will be prompted for a Kerberos
 442 password.  The password is then used to get a
 443 ticket granting ticket from the Kerberos server.
 444 The danger of configuring ksu with this macro is
 445 if the source user is logged in remotely and does not
 446 have a secure channel, the password may get exposed.
 447 .TP 10
 448 \fIPRINC_LOOK_AHEAD\fP
 449 during the resolution of the default principal name,
 450 PRINC_LOOK_AHEAD enables ksu to find principal names
 451 in the .k5users file as described in the OPTIONS section
 452 (see -n option).
 453 .TP 10
 454 \fICMD_PATH\fP
 455 specifies a list of directories containing programs
 456 that users are authorized to execute (via .k5users file).
 457 .TP 10
 458 \fIHAS_GETUSERSHELL\fP
 459 If the source user is non-root, ksu insists that
 460 the target user's shell to be invoked
 461 is a "legal shell". getusershell(3) is called to obtain
 462 the names of "legal shells".  Note that the target user's
 463 shell is obtained from the passwd file.
 464 .TP 10
 465 SAMPLE CONFIGURATION:
 466 KSU_OPTS = -DGET_TGT_VIA_PASSWD
 467 -DPRINC_LOOK_AHEAD -DCMD_PATH='"/bin /usr/ucb /local/bin"
 468 .TP 10
 469 PERMISSIONS FOR KSU
 470 ksu should be owned by root and have the set user id  bit turned on.
 471 .TP 10
 472 END-SERVER ENTRY
 473
 474 ksu attempts to get a ticket for the end server just as Kerberized
 475 telnet and rlogin.  Thus, there must be an entry for the server in the
 476 Kerberos database (e.g. host/nii.isi.edu@ISI.EDU).  The keytab file must
 477 be in an appropriate location.
 478
 479 .SH SIDE EFFECTS
 480 ksu deletes all expired tickets from the source cache.
 481 .SH AUTHOR OF KSU:      GENNADY (ARI) MEDVINSKY