src/man/ksu.1

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