src/man/ksu.man

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