doc/user/user_commands/ksu.rst

   1 .. _ksu(1):
   2
   3 ksu
   4 ===
   5
   6 SYNOPSIS
   7 --------
   8
   9 **ksu**
  10 [ *target_user* ]
  11 [ **-n** *target_principal_name* ]
  12 [ **-c** *source_cache_name* ]
  13 [ **-k** ]
  14 [ **-r** time ]
  15 [ **-pf** ]
  16 [ **-l** *lifetime* ]
  17 [ **-z | Z** ]
  18 [ **-q** ]
  19 [ **-e** *command* [ args ...  ] ] [ **-a** [ args ...  ] ]
  20
  21
  22 REQUIREMENTS
  23 ------------
  24
  25 Must have Kerberos version 5 installed to compile ksu.  Must have a
  26 Kerberos version 5 server running to use ksu.
  27
  28
  29 DESCRIPTION
  30 -----------
  31
  32 ksu is a Kerberized version of the su program that has two missions:
  33 one is to securely change the real and effective user ID to that of
  34 the target user, and the other is to create a new security context.
  35
  36 .. note::
  37
  38           For the sake of clarity, all references to and attributes of
  39           the user invoking the program will start with "source"
  40           (e.g., "source user", "source cache", etc.).
  41
  42           Likewise, all references to and attributes of the target
  43           account will start with "target".
  44
  45 AUTHENTICATION
  46 --------------
  47
  48 To fulfill the first mission, ksu operates in two phases:
  49 authentication and authorization.  Resolving the target principal name
  50 is the first step in authentication.  The user can either specify his
  51 principal name with the **-n** option (e.g., ``-n jqpublic@USC.EDU``)
  52 or a default principal name will be assigned using a heuristic
  53 described in the OPTIONS section (see **-n** option).  The target user
  54 name must be the first argument to ksu; if not specified root is the
  55 default.  If ``.`` is specified then the target user will be the
  56 source user (e.g., ``ksu .``).  If the source user is root or the
  57 target user is the source user, no authentication or authorization
  58 takes place.  Otherwise, ksu looks for an appropriate Kerberos ticket
  59 in the source cache.
  60
  61 The ticket can either be for the end-server or a ticket granting
  62 ticket (TGT) for the target principal's realm.  If the ticket for the
  63 end-server is already in the cache, it's decrypted and verified.  If
  64 it's not in the cache but the TGT is, the TGT is used to obtain the
  65 ticket for the end-server.  The end-server ticket is then verified.
  66 If neither ticket is in the cache, but ksu is compiled with the
  67 **GET_TGT_VIA_PASSWD** define, the user will be prompted for a
  68 Kerberos password which will then be used to get a TGT.  If the user
  69 is logged in remotely and does not have a secure channel, the password
  70 may be exposed.  If neither ticket is in the cache and
  71 **GET_TGT_VIA_PASSWD** is not defined, authentication fails.
  72
  73
  74 AUTHORIZATION
  75 -------------
  76
  77 This section describes authorization of the source user when ksu is
  78 invoked without the **-e** option.  For a description of the **-e**
  79 option, see the OPTIONS section.
  80
  81 Upon successful authentication, ksu checks whether the target
  82 principal is authorized to access the target account.  In the target
  83 user's home directory, ksu attempts to access two authorization files:
  84 :ref:`.k5login(5)` and .k5users.  In the .k5login file each line
  85 contains the name of a principal that is authorized to access the
  86 account.
  87
  88 For example::
  89
  90     jqpublic@USC.EDU
  91     jqpublic/secure@USC.EDU
  92     jqpublic/admin@USC.EDU
  93
  94 The format of .k5users is the same, except the principal name may be
  95 followed by a list of commands that the principal is authorized to
  96 execute (see the **-e** option in the OPTIONS section for details).
  97
  98 Thus if the target principal name is found in the .k5login file the
  99 source user is authorized to access the target account.  Otherwise ksu
 100 looks in the .k5users file.  If the target principal name is found
 101 without any trailing commands or followed only by ``*`` then the
 102 source user is authorized.  If either .k5login or .k5users exist but
 103 an appropriate entry for the target principal does not exist then
 104 access is denied.  If neither file exists then the principal will be
 105 granted access to the account according to the aname->lname mapping
 106 rules.  Otherwise, authorization fails.
 107
 108
 109 EXECUTION OF THE TARGET SHELL
 110 -----------------------------
 111
 112 Upon successful authentication and authorization, ksu proceeds in a
 113 similar fashion to su.  The environment is unmodified with the
 114 exception of USER, HOME and SHELL variables.  If the target user is
 115 not root, USER gets set to the target user name.  Otherwise USER
 116 remains unchanged.  Both HOME and SHELL are set to the target login's
 117 default values.  In addition, the environment variable **KRB5CCNAME**
 118 gets set to the name of the target cache.  The real and effective user
 119 ID are changed to that of the target user.  The target user's shell is
 120 then invoked (the shell name is specified in the password file).  Upon
 121 termination of the shell, ksu deletes the target cache (unless ksu is
 122 invoked with the **-k** option).  This is implemented by first doing a
 123 fork and then an exec, instead of just exec, as done by su.
 124
 125
 126 CREATING A NEW SECURITY CONTEXT
 127 -------------------------------
 128
 129 ksu can be used to create a new security context for the target
 130 program (either the target shell, or command specified via the **-e**
 131 option).  The target program inherits a set of credentials from the
 132 source user.  By default, this set includes all of the credentials in
 133 the source cache plus any additional credentials obtained during
 134 authentication.  The source user is able to limit the credentials in
 135 this set by using **-z** or **-Z** option.  **-z** restricts the copy
 136 of tickets from the source cache to the target cache to only the
 137 tickets where client == the target principal name.  The **-Z** option
 138 provides the target user with a fresh target cache (no creds in the
 139 cache).  Note that for security reasons, when the source user is root
 140 and target user is non-root, **-z** option is the default mode of
 141 operation.
 142
 143 While no authentication takes place if the source user is root or is
 144 the same as the target user, additional tickets can still be obtained
 145 for the target cache.  If **-n** is specified and no credentials can
 146 be copied to the target cache, the source user is prompted for a
 147 Kerberos password (unless **-Z** specified or **GET_TGT_VIA_PASSWD**
 148 is undefined).  If successful, a TGT is obtained from the Kerberos
 149 server and stored in the target cache.  Otherwise, if a password is
 150 not provided (user hit return) ksu continues in a normal mode of
 151 operation (the target cache will not contain the desired TGT).  If the
 152 wrong password is typed in, ksu fails.
 153
 154 .. note::
 155
 156           During authentication, only the tickets that could be
 157           obtained without providing a password are cached in in the
 158           source cache.
 159
 160
 161 OPTIONS
 162 -------
 163
 164 **-n** *target_principal_name*
 165     Specify a Kerberos target principal name.  Used in authentication
 166     and authorization phases of ksu.
 167
 168     If ksu is invoked without **-n**, a default principal name is
 169     assigned via the following heuristic:
 170
 171     * Case 1: source user is non-root.
 172
 173       If the target user is the source user the default principal name
 174       is set to the default principal of the source cache.  If the
 175       cache does not exist then the default principal name is set to
 176       ``target_user@local_realm``.  If the source and target users are
 177       different and neither ``~target_user/.k5users`` nor
 178       ``~target_user/.k5login`` exist then the default principal name
 179       is ``target_user_login_name@local_realm``.  Otherwise, starting
 180       with the first principal listed below, ksu checks if the
 181       principal is authorized to access the target account and whether
 182       there is a legitimate ticket for that principal in the source
 183       cache.  If both conditions are met that principal becomes the
 184       default target principal, otherwise go to the next principal.
 185
 186       a) default principal of the source cache
 187       b) target_user\@local_realm
 188       c) source_user\@local_realm
 189
 190       If a-c fails try any principal for which there is a ticket in
 191       the source cache and that is authorized to access the target
 192       account.  If that fails select the first principal that is
 193       authorized to access the target account from the above list.  If
 194       none are authorized and ksu is configured with
 195       **PRINC_LOOK_AHEAD** turned on, select the default principal as
 196       follows:
 197
 198       For each candidate in the above list, select an authorized
 199       principal that has the same realm name and first part of the
 200       principal name equal to the prefix of the candidate.  For
 201       example if candidate a) is ``jqpublic@ISI.EDU`` and
 202       ``jqpublic/secure@ISI.EDU`` is authorized to access the target
 203       account then the default principal is set to
 204       ``jqpublic/secure@ISI.EDU``.
 205
 206     * Case 2: source user is root.
 207
 208       If the target user is non-root then the default principal name
 209       is ``target_user@local_realm``.  Else, if the source cache
 210       exists the default principal name is set to the default
 211       principal of the source cache.  If the source cache does not
 212       exist, default principal name is set to ``root\@local_realm``.
 213
 214 **-c** *source_cache_name*
 215
 216     Specify source cache name (e.g., ``-c FILE:/tmp/my_cache``).  If
 217     **-c** option is not used then the name is obtained from
 218     **KRB5CCNAME** environment variable.  If **KRB5CCNAME** is not
 219     defined the source cache name is set to ``krb5cc_<source uid>``.
 220     The target cache name is automatically set to ``krb5cc_<target
 221     uid>.(gen_sym())``, where gen_sym generates a new number such that
 222     the resulting cache does not already exist.  For example::
 223
 224         krb5cc_1984.2
 225
 226 **-k**
 227     Do not delete the target cache upon termination of the target
 228     shell or a command (**-e** command).  Without **-k**, ksu deletes
 229     the target cache.
 230
 231 **-z**
 232     Restrict the copy of tickets from the source cache to the target
 233     cache to only the tickets where client == the target principal
 234     name.  Use the **-n** option if you want the tickets for other then
 235     the default principal.  Note that the **-z** option is mutually
 236     exclusive with the **-Z** option.
 237
 238 **-Z**
 239     Don't copy any tickets from the source cache to the target cache.
 240     Just create a fresh target cache, where the default principal name
 241     of the cache is initialized to the target principal name.  Note
 242     that the **-Z** option is mutually exclusive with the **-z**
 243     option.
 244
 245 **-q**
 246     Suppress the printing of status messages.
 247
 248 Ticket granting ticket options:
 249
 250 **-l** *lifetime* **-r** *time* **-pf**
 251     The ticket granting ticket options only apply to the case where
 252     there are no appropriate tickets in the cache to authenticate the
 253     source user.  In this case if ksu is configured to prompt users
 254     for a Kerberos password (**GET_TGT_VIA_PASSWD** is defined), the
 255     ticket granting ticket options that are specified will be used
 256     when getting a ticket granting ticket from the Kerberos server.
 257
 258 **-l** *lifetime*
 259     (:ref:`duration` string.)  Specifies the lifetime to be requested
 260     for the ticket; if this option is not specified, the default ticket
 261     lifetime (12 hours) is used instead.
 262
 263 **-r** *time*
 264     (:ref:`duration` string.)  Specifies that the **renewable** option
 265     should be requested for the ticket, and specifies the desired
 266     total lifetime of the ticket.
 267
 268 **-p**
 269     specifies that the **proxiable** option should be requested for
 270     the ticket.
 271
 272 **-f**
 273     option specifies that the **forwardable** option should be
 274     requested for the ticket.
 275
 276 **-e** *command* [*args* ...]
 277     ksu proceeds exactly the same as if it was invoked without the
 278     **-e** option, except instead of executing the target shell, ksu
 279     executes the specified command. Example of usage::
 280
 281         ksu bob -e ls -lag
 282
 283     The authorization algorithm for **-e** is as follows:
 284
 285     If the source user is root or source user == target user, no
 286     authorization takes place and the command is executed.  If source
 287     user id != 0, and ``~target_user/.k5users`` file does not exist,
 288     authorization fails.  Otherwise, ``~target_user/.k5users`` file
 289     must have an appropriate entry for target principal to get
 290     authorized.
 291
 292     The .k5users file format:
 293
 294     A single principal entry on each line that may be followed by a
 295     list of commands that the principal is authorized to execute.  A
 296     principal name followed by a ``*`` means that the user is
 297     authorized to execute any command.  Thus, in the following
 298     example::
 299
 300         jqpublic@USC.EDU ls mail /local/kerberos/klist
 301         jqpublic/secure@USC.EDU *
 302         jqpublic/admin@USC.EDU
 303
 304     ``jqpublic@USC.EDU`` is only authorized to execute ``ls``,
 305     ``mail`` and ``klist`` commands.  ``jqpublic/secure@USC.EDU`` is
 306     authorized to execute any command.  ``jqpublic/admin@USC.EDU`` is
 307     not authorized to execute any command.  Note, that
 308     ``jqpublic/admin@USC.EDU`` is authorized to execute the target
 309     shell (regular ksu, without the **-e** option) but
 310     ``jqpublic@USC.EDU`` is not.
 311
 312     The commands listed after the principal name must be either a full
 313     path names or just the program name.  In the second case,
 314     **CMD_PATH** specifying the location of authorized programs must
 315     be defined at the compilation time of ksu.  Which command gets
 316     executed?
 317
 318     If the source user is root or the target user is the source user
 319     or the user is authorized to execute any command (``*`` entry)
 320     then command can be either a full or a relative path leading to
 321     the target program.  Otherwise, the user must specify either a
 322     full path or just the program name.
 323
 324 **-a** *args*
 325     Specify arguments to be passed to the target shell.  Note that all
 326     flags and parameters following -a will be passed to the shell,
 327     thus all options intended for ksu must precede **-a**.
 328
 329     The **-a** option can be used to simulate the **-e** option if
 330     used as follows::
 331
 332         -a -c [command [arguments]].
 333
 334     **-c** is interpreted by the c-shell to execute the command.
 335
 336
 337 INSTALLATION INSTRUCTIONS
 338 -------------------------
 339
 340 ksu can be compiled with the following four flags:
 341
 342 **GET_TGT_VIA_PASSWD**
 343     In case no appropriate tickets are found in the source cache, the
 344     user will be prompted for a Kerberos password.  The password is
 345     then used to get a ticket granting ticket from the Kerberos
 346     server.  The danger of configuring ksu with this macro is if the
 347     source user is logged in remotely and does not have a secure
 348     channel, the password may get exposed.
 349
 350 **PRINC_LOOK_AHEAD**
 351     During the resolution of the default principal name,
 352     **PRINC_LOOK_AHEAD** enables ksu to find principal names in
 353     the .k5users file as described in the OPTIONS section
 354     (see **-n** option).
 355
 356 **CMD_PATH**
 357     Specifies a list of directories containing programs that users are
 358     authorized to execute (via .k5users file).
 359
 360 **HAVE_GETUSERSHELL**
 361     If the source user is non-root, ksu insists that the target user's
 362     shell to be invoked is a "legal shell".  *getusershell(3)* is
 363     called to obtain the names of "legal shells".  Note that the
 364     target user's shell is obtained from the passwd file.
 365
 366 Sample configuration::
 367
 368     KSU_OPTS = -DGET_TGT_VIA_PASSWD -DPRINC_LOOK_AHEAD -DCMD_PATH='"/bin /usr/ucb /local/bin"
 369
 370 ksu should be owned by root and have the set user id bit turned on.
 371
 372 ksu attempts to get a ticket for the end server just as Kerberized
 373 telnet and rlogin.  Thus, there must be an entry for the server in the
 374 Kerberos database (e.g., ``host/nii.isi.edu@ISI.EDU``).  The keytab
 375 file must be in an appropriate location.
 376
 377
 378 SIDE EFFECTS
 379 ------------
 380
 381 ksu deletes all expired tickets from the source cache.
 382
 383
 384 AUTHOR OF KSU
 385 -------------
 386
 387 GENNADY (ARI) MEDVINSKY
 388
 389
 390 ENVIRONMENT
 391 -----------
 392
 393 See :ref:`kerberos(7)` for a description of Kerberos environment
 394 variables.
 395
 396
 397 SEE ALSO
 398 --------
 399
 400 :ref:`kerberos(7)`, :ref:`kinit(1)`