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