jpayne@68: .\" Man page generated from reStructuredText. jpayne@68: . jpayne@68: .TH "KSU" "1" " " "1.20.1" "MIT Kerberos" jpayne@68: .SH NAME jpayne@68: ksu \- Kerberized super-user jpayne@68: . jpayne@68: .nr rst2man-indent-level 0 jpayne@68: . jpayne@68: .de1 rstReportMargin jpayne@68: \\$1 \\n[an-margin] jpayne@68: level \\n[rst2man-indent-level] jpayne@68: level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] jpayne@68: - jpayne@68: \\n[rst2man-indent0] jpayne@68: \\n[rst2man-indent1] jpayne@68: \\n[rst2man-indent2] jpayne@68: .. jpayne@68: .de1 INDENT jpayne@68: .\" .rstReportMargin pre: jpayne@68: . RS \\$1 jpayne@68: . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] jpayne@68: . nr rst2man-indent-level +1 jpayne@68: .\" .rstReportMargin post: jpayne@68: .. jpayne@68: .de UNINDENT jpayne@68: . RE jpayne@68: .\" indent \\n[an-margin] jpayne@68: .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] jpayne@68: .nr rst2man-indent-level -1 jpayne@68: .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] jpayne@68: .in \\n[rst2man-indent\\n[rst2man-indent-level]]u jpayne@68: .. jpayne@68: .SH SYNOPSIS jpayne@68: .sp jpayne@68: \fBksu\fP jpayne@68: [ \fItarget_user\fP ] jpayne@68: [ \fB\-n\fP \fItarget_principal_name\fP ] jpayne@68: [ \fB\-c\fP \fIsource_cache_name\fP ] jpayne@68: [ \fB\-k\fP ] jpayne@68: [ \fB\-r\fP time ] jpayne@68: [ \fB\-p\fP | \fB\-P\fP] jpayne@68: [ \fB\-f\fP | \fB\-F\fP] jpayne@68: [ \fB\-l\fP \fIlifetime\fP ] jpayne@68: [ \fB\-z | Z\fP ] jpayne@68: [ \fB\-q\fP ] jpayne@68: [ \fB\-e\fP \fIcommand\fP [ args ... ] ] [ \fB\-a\fP [ args ... ] ] jpayne@68: .SH REQUIREMENTS jpayne@68: .sp jpayne@68: Must have Kerberos version 5 installed to compile ksu. Must have a jpayne@68: Kerberos version 5 server running to use ksu. jpayne@68: .SH DESCRIPTION jpayne@68: .sp jpayne@68: ksu is a Kerberized version of the su program that has two missions: jpayne@68: one is to securely change the real and effective user ID to that of jpayne@68: the target user, and the other is to create a new security context. jpayne@68: .sp jpayne@68: \fBNOTE:\fP jpayne@68: .INDENT 0.0 jpayne@68: .INDENT 3.5 jpayne@68: For the sake of clarity, all references to and attributes of jpayne@68: the user invoking the program will start with "source" jpayne@68: (e.g., "source user", "source cache", etc.). jpayne@68: .sp jpayne@68: Likewise, all references to and attributes of the target jpayne@68: account will start with "target". jpayne@68: .UNINDENT jpayne@68: .UNINDENT jpayne@68: .SH AUTHENTICATION jpayne@68: .sp jpayne@68: To fulfill the first mission, ksu operates in two phases: jpayne@68: authentication and authorization. Resolving the target principal name jpayne@68: is the first step in authentication. The user can either specify his jpayne@68: principal name with the \fB\-n\fP option (e.g., \fB\-n jqpublic@USC.EDU\fP) jpayne@68: or a default principal name will be assigned using a heuristic jpayne@68: described in the OPTIONS section (see \fB\-n\fP option). The target user jpayne@68: name must be the first argument to ksu; if not specified root is the jpayne@68: default. If \fB\&.\fP is specified then the target user will be the jpayne@68: source user (e.g., \fBksu .\fP). If the source user is root or the jpayne@68: target user is the source user, no authentication or authorization jpayne@68: takes place. Otherwise, ksu looks for an appropriate Kerberos ticket jpayne@68: in the source cache. jpayne@68: .sp jpayne@68: The ticket can either be for the end\-server or a ticket granting jpayne@68: ticket (TGT) for the target principal\(aqs realm. If the ticket for the jpayne@68: end\-server is already in the cache, it\(aqs decrypted and verified. If jpayne@68: it\(aqs not in the cache but the TGT is, the TGT is used to obtain the jpayne@68: ticket for the end\-server. The end\-server ticket is then verified. jpayne@68: If neither ticket is in the cache, but ksu is compiled with the jpayne@68: \fBGET_TGT_VIA_PASSWD\fP define, the user will be prompted for a jpayne@68: Kerberos password which will then be used to get a TGT. If the user jpayne@68: is logged in remotely and does not have a secure channel, the password jpayne@68: may be exposed. If neither ticket is in the cache and jpayne@68: \fBGET_TGT_VIA_PASSWD\fP is not defined, authentication fails. jpayne@68: .SH AUTHORIZATION jpayne@68: .sp jpayne@68: This section describes authorization of the source user when ksu is jpayne@68: invoked without the \fB\-e\fP option. For a description of the \fB\-e\fP jpayne@68: option, see the OPTIONS section. jpayne@68: .sp jpayne@68: Upon successful authentication, ksu checks whether the target jpayne@68: principal is authorized to access the target account. In the target jpayne@68: user\(aqs home directory, ksu attempts to access two authorization files: jpayne@68: \&.k5login(5) and .k5users. In the .k5login file each line jpayne@68: contains the name of a principal that is authorized to access the jpayne@68: account. jpayne@68: .sp jpayne@68: For example: jpayne@68: .INDENT 0.0 jpayne@68: .INDENT 3.5 jpayne@68: .sp jpayne@68: .nf jpayne@68: .ft C jpayne@68: jqpublic@USC.EDU jpayne@68: jqpublic/secure@USC.EDU jpayne@68: jqpublic/admin@USC.EDU jpayne@68: .ft P jpayne@68: .fi jpayne@68: .UNINDENT jpayne@68: .UNINDENT jpayne@68: .sp jpayne@68: The format of .k5users is the same, except the principal name may be jpayne@68: followed by a list of commands that the principal is authorized to jpayne@68: execute (see the \fB\-e\fP option in the OPTIONS section for details). jpayne@68: .sp jpayne@68: Thus if the target principal name is found in the .k5login file the jpayne@68: source user is authorized to access the target account. Otherwise ksu jpayne@68: looks in the .k5users file. If the target principal name is found jpayne@68: without any trailing commands or followed only by \fB*\fP then the jpayne@68: source user is authorized. If either .k5login or .k5users exist but jpayne@68: an appropriate entry for the target principal does not exist then jpayne@68: access is denied. If neither file exists then the principal will be jpayne@68: granted access to the account according to the aname\->lname mapping jpayne@68: rules. Otherwise, authorization fails. jpayne@68: .SH EXECUTION OF THE TARGET SHELL jpayne@68: .sp jpayne@68: Upon successful authentication and authorization, ksu proceeds in a jpayne@68: similar fashion to su. The environment is unmodified with the jpayne@68: exception of USER, HOME and SHELL variables. If the target user is jpayne@68: not root, USER gets set to the target user name. Otherwise USER jpayne@68: remains unchanged. Both HOME and SHELL are set to the target login\(aqs jpayne@68: default values. In addition, the environment variable \fBKRB5CCNAME\fP jpayne@68: gets set to the name of the target cache. The real and effective user jpayne@68: ID are changed to that of the target user. The target user\(aqs shell is jpayne@68: then invoked (the shell name is specified in the password file). Upon jpayne@68: termination of the shell, ksu deletes the target cache (unless ksu is jpayne@68: invoked with the \fB\-k\fP option). This is implemented by first doing a jpayne@68: fork and then an exec, instead of just exec, as done by su. jpayne@68: .SH CREATING A NEW SECURITY CONTEXT jpayne@68: .sp jpayne@68: ksu can be used to create a new security context for the target jpayne@68: program (either the target shell, or command specified via the \fB\-e\fP jpayne@68: option). The target program inherits a set of credentials from the jpayne@68: source user. By default, this set includes all of the credentials in jpayne@68: the source cache plus any additional credentials obtained during jpayne@68: authentication. The source user is able to limit the credentials in jpayne@68: this set by using \fB\-z\fP or \fB\-Z\fP option. \fB\-z\fP restricts the copy jpayne@68: of tickets from the source cache to the target cache to only the jpayne@68: tickets where client == the target principal name. The \fB\-Z\fP option jpayne@68: provides the target user with a fresh target cache (no creds in the jpayne@68: cache). Note that for security reasons, when the source user is root jpayne@68: and target user is non\-root, \fB\-z\fP option is the default mode of jpayne@68: operation. jpayne@68: .sp jpayne@68: While no authentication takes place if the source user is root or is jpayne@68: the same as the target user, additional tickets can still be obtained jpayne@68: for the target cache. If \fB\-n\fP is specified and no credentials can jpayne@68: be copied to the target cache, the source user is prompted for a jpayne@68: Kerberos password (unless \fB\-Z\fP specified or \fBGET_TGT_VIA_PASSWD\fP jpayne@68: is undefined). If successful, a TGT is obtained from the Kerberos jpayne@68: server and stored in the target cache. Otherwise, if a password is jpayne@68: not provided (user hit return) ksu continues in a normal mode of jpayne@68: operation (the target cache will not contain the desired TGT). If the jpayne@68: wrong password is typed in, ksu fails. jpayne@68: .sp jpayne@68: \fBNOTE:\fP jpayne@68: .INDENT 0.0 jpayne@68: .INDENT 3.5 jpayne@68: During authentication, only the tickets that could be jpayne@68: obtained without providing a password are cached in the jpayne@68: source cache. jpayne@68: .UNINDENT jpayne@68: .UNINDENT jpayne@68: .SH OPTIONS jpayne@68: .INDENT 0.0 jpayne@68: .TP jpayne@68: \fB\-n\fP \fItarget_principal_name\fP jpayne@68: Specify a Kerberos target principal name. Used in authentication jpayne@68: and authorization phases of ksu. jpayne@68: .sp jpayne@68: If ksu is invoked without \fB\-n\fP, a default principal name is jpayne@68: assigned via the following heuristic: jpayne@68: .INDENT 7.0 jpayne@68: .IP \(bu 2 jpayne@68: Case 1: source user is non\-root. jpayne@68: .sp jpayne@68: If the target user is the source user the default principal name jpayne@68: is set to the default principal of the source cache. If the jpayne@68: cache does not exist then the default principal name is set to jpayne@68: \fBtarget_user@local_realm\fP\&. If the source and target users are jpayne@68: different and neither \fB~target_user/.k5users\fP nor jpayne@68: \fB~target_user/.k5login\fP exist then the default principal name jpayne@68: is \fBtarget_user_login_name@local_realm\fP\&. Otherwise, starting jpayne@68: with the first principal listed below, ksu checks if the jpayne@68: principal is authorized to access the target account and whether jpayne@68: there is a legitimate ticket for that principal in the source jpayne@68: cache. If both conditions are met that principal becomes the jpayne@68: default target principal, otherwise go to the next principal. jpayne@68: .INDENT 2.0 jpayne@68: .IP a. 3 jpayne@68: default principal of the source cache jpayne@68: .IP b. 3 jpayne@68: target_user@local_realm jpayne@68: .IP c. 3 jpayne@68: source_user@local_realm jpayne@68: .UNINDENT jpayne@68: .sp jpayne@68: If a\-c fails try any principal for which there is a ticket in jpayne@68: the source cache and that is authorized to access the target jpayne@68: account. If that fails select the first principal that is jpayne@68: authorized to access the target account from the above list. If jpayne@68: none are authorized and ksu is configured with jpayne@68: \fBPRINC_LOOK_AHEAD\fP turned on, select the default principal as jpayne@68: follows: jpayne@68: .sp jpayne@68: For each candidate in the above list, select an authorized jpayne@68: principal that has the same realm name and first part of the jpayne@68: principal name equal to the prefix of the candidate. For jpayne@68: example if candidate a) is \fBjqpublic@ISI.EDU\fP and jpayne@68: \fBjqpublic/secure@ISI.EDU\fP is authorized to access the target jpayne@68: account then the default principal is set to jpayne@68: \fBjqpublic/secure@ISI.EDU\fP\&. jpayne@68: .IP \(bu 2 jpayne@68: Case 2: source user is root. jpayne@68: .sp jpayne@68: If the target user is non\-root then the default principal name jpayne@68: is \fBtarget_user@local_realm\fP\&. Else, if the source cache jpayne@68: exists the default principal name is set to the default jpayne@68: principal of the source cache. If the source cache does not jpayne@68: exist, default principal name is set to \fBroot\e@local_realm\fP\&. jpayne@68: .UNINDENT jpayne@68: .UNINDENT jpayne@68: .sp jpayne@68: \fB\-c\fP \fIsource_cache_name\fP jpayne@68: .INDENT 0.0 jpayne@68: .INDENT 3.5 jpayne@68: Specify source cache name (e.g., \fB\-c FILE:/tmp/my_cache\fP). If jpayne@68: \fB\-c\fP option is not used then the name is obtained from jpayne@68: \fBKRB5CCNAME\fP environment variable. If \fBKRB5CCNAME\fP is not jpayne@68: defined the source cache name is set to \fBkrb5cc_\fP\&. jpayne@68: The target cache name is automatically set to \fBkrb5cc_.(gen_sym())\fP, where gen_sym generates a new number such that jpayne@68: the resulting cache does not already exist. For example: jpayne@68: .INDENT 0.0 jpayne@68: .INDENT 3.5 jpayne@68: .sp jpayne@68: .nf jpayne@68: .ft C jpayne@68: krb5cc_1984.2 jpayne@68: .ft P jpayne@68: .fi jpayne@68: .UNINDENT jpayne@68: .UNINDENT jpayne@68: .UNINDENT jpayne@68: .UNINDENT jpayne@68: .INDENT 0.0 jpayne@68: .TP jpayne@68: \fB\-k\fP jpayne@68: Do not delete the target cache upon termination of the target jpayne@68: shell or a command (\fB\-e\fP command). Without \fB\-k\fP, ksu deletes jpayne@68: the target cache. jpayne@68: .TP jpayne@68: \fB\-z\fP jpayne@68: Restrict the copy of tickets from the source cache to the target jpayne@68: cache to only the tickets where client == the target principal jpayne@68: name. Use the \fB\-n\fP option if you want the tickets for other then jpayne@68: the default principal. Note that the \fB\-z\fP option is mutually jpayne@68: exclusive with the \fB\-Z\fP option. jpayne@68: .TP jpayne@68: \fB\-Z\fP jpayne@68: Don\(aqt copy any tickets from the source cache to the target cache. jpayne@68: Just create a fresh target cache, where the default principal name jpayne@68: of the cache is initialized to the target principal name. Note jpayne@68: that the \fB\-Z\fP option is mutually exclusive with the \fB\-z\fP jpayne@68: option. jpayne@68: .TP jpayne@68: \fB\-q\fP jpayne@68: Suppress the printing of status messages. jpayne@68: .UNINDENT jpayne@68: .sp jpayne@68: Ticket granting ticket options: jpayne@68: .INDENT 0.0 jpayne@68: .TP jpayne@68: \fB\-l\fP \fIlifetime\fP \fB\-r\fP \fItime\fP \fB\-p\fP \fB\-P\fP \fB\-f\fP \fB\-F\fP jpayne@68: The ticket granting ticket options only apply to the case where jpayne@68: there are no appropriate tickets in the cache to authenticate the jpayne@68: source user. In this case if ksu is configured to prompt users jpayne@68: for a Kerberos password (\fBGET_TGT_VIA_PASSWD\fP is defined), the jpayne@68: ticket granting ticket options that are specified will be used jpayne@68: when getting a ticket granting ticket from the Kerberos server. jpayne@68: .TP jpayne@68: \fB\-l\fP \fIlifetime\fP jpayne@68: (duration string.) Specifies the lifetime to be requested jpayne@68: for the ticket; if this option is not specified, the default ticket jpayne@68: lifetime (12 hours) is used instead. jpayne@68: .TP jpayne@68: \fB\-r\fP \fItime\fP jpayne@68: (duration string.) Specifies that the \fBrenewable\fP option jpayne@68: should be requested for the ticket, and specifies the desired jpayne@68: total lifetime of the ticket. jpayne@68: .TP jpayne@68: \fB\-p\fP jpayne@68: specifies that the \fBproxiable\fP option should be requested for jpayne@68: the ticket. jpayne@68: .TP jpayne@68: \fB\-P\fP jpayne@68: specifies that the \fBproxiable\fP option should not be requested jpayne@68: for the ticket, even if the default configuration is to ask for jpayne@68: proxiable tickets. jpayne@68: .TP jpayne@68: \fB\-f\fP jpayne@68: option specifies that the \fBforwardable\fP option should be jpayne@68: requested for the ticket. jpayne@68: .TP jpayne@68: \fB\-F\fP jpayne@68: option specifies that the \fBforwardable\fP option should not be jpayne@68: requested for the ticket, even if the default configuration is to jpayne@68: ask for forwardable tickets. jpayne@68: .TP jpayne@68: \fB\-e\fP \fIcommand\fP [\fIargs\fP ...] jpayne@68: ksu proceeds exactly the same as if it was invoked without the jpayne@68: \fB\-e\fP option, except instead of executing the target shell, ksu jpayne@68: executes the specified command. Example of usage: jpayne@68: .INDENT 7.0 jpayne@68: .INDENT 3.5 jpayne@68: .sp jpayne@68: .nf jpayne@68: .ft C jpayne@68: ksu bob \-e ls \-lag jpayne@68: .ft P jpayne@68: .fi jpayne@68: .UNINDENT jpayne@68: .UNINDENT jpayne@68: .sp jpayne@68: The authorization algorithm for \fB\-e\fP is as follows: jpayne@68: .sp jpayne@68: If the source user is root or source user == target user, no jpayne@68: authorization takes place and the command is executed. If source jpayne@68: user id != 0, and \fB~target_user/.k5users\fP file does not exist, jpayne@68: authorization fails. Otherwise, \fB~target_user/.k5users\fP file jpayne@68: must have an appropriate entry for target principal to get jpayne@68: authorized. jpayne@68: .sp jpayne@68: The .k5users file format: jpayne@68: .sp jpayne@68: A single principal entry on each line that may be followed by a jpayne@68: list of commands that the principal is authorized to execute. A jpayne@68: principal name followed by a \fB*\fP means that the user is jpayne@68: authorized to execute any command. Thus, in the following jpayne@68: example: jpayne@68: .INDENT 7.0 jpayne@68: .INDENT 3.5 jpayne@68: .sp jpayne@68: .nf jpayne@68: .ft C jpayne@68: jqpublic@USC.EDU ls mail /local/kerberos/klist jpayne@68: jqpublic/secure@USC.EDU * jpayne@68: jqpublic/admin@USC.EDU jpayne@68: .ft P jpayne@68: .fi jpayne@68: .UNINDENT jpayne@68: .UNINDENT jpayne@68: .sp jpayne@68: \fBjqpublic@USC.EDU\fP is only authorized to execute \fBls\fP, jpayne@68: \fBmail\fP and \fBklist\fP commands. \fBjqpublic/secure@USC.EDU\fP is jpayne@68: authorized to execute any command. \fBjqpublic/admin@USC.EDU\fP is jpayne@68: not authorized to execute any command. Note, that jpayne@68: \fBjqpublic/admin@USC.EDU\fP is authorized to execute the target jpayne@68: shell (regular ksu, without the \fB\-e\fP option) but jpayne@68: \fBjqpublic@USC.EDU\fP is not. jpayne@68: .sp jpayne@68: The commands listed after the principal name must be either a full jpayne@68: path names or just the program name. In the second case, jpayne@68: \fBCMD_PATH\fP specifying the location of authorized programs must jpayne@68: be defined at the compilation time of ksu. Which command gets jpayne@68: executed? jpayne@68: .sp jpayne@68: If the source user is root or the target user is the source user jpayne@68: or the user is authorized to execute any command (\fB*\fP entry) jpayne@68: then command can be either a full or a relative path leading to jpayne@68: the target program. Otherwise, the user must specify either a jpayne@68: full path or just the program name. jpayne@68: .TP jpayne@68: \fB\-a\fP \fIargs\fP jpayne@68: Specify arguments to be passed to the target shell. Note that all jpayne@68: flags and parameters following \-a will be passed to the shell, jpayne@68: thus all options intended for ksu must precede \fB\-a\fP\&. jpayne@68: .sp jpayne@68: The \fB\-a\fP option can be used to simulate the \fB\-e\fP option if jpayne@68: used as follows: jpayne@68: .INDENT 7.0 jpayne@68: .INDENT 3.5 jpayne@68: .sp jpayne@68: .nf jpayne@68: .ft C jpayne@68: \-a \-c [command [arguments]]. jpayne@68: .ft P jpayne@68: .fi jpayne@68: .UNINDENT jpayne@68: .UNINDENT jpayne@68: .sp jpayne@68: \fB\-c\fP is interpreted by the c\-shell to execute the command. jpayne@68: .UNINDENT jpayne@68: .SH INSTALLATION INSTRUCTIONS jpayne@68: .sp jpayne@68: ksu can be compiled with the following four flags: jpayne@68: .INDENT 0.0 jpayne@68: .TP jpayne@68: \fBGET_TGT_VIA_PASSWD\fP jpayne@68: In case no appropriate tickets are found in the source cache, the jpayne@68: user will be prompted for a Kerberos password. The password is jpayne@68: then used to get a ticket granting ticket from the Kerberos jpayne@68: server. The danger of configuring ksu with this macro is if the jpayne@68: source user is logged in remotely and does not have a secure jpayne@68: channel, the password may get exposed. jpayne@68: .TP jpayne@68: \fBPRINC_LOOK_AHEAD\fP jpayne@68: During the resolution of the default principal name, jpayne@68: \fBPRINC_LOOK_AHEAD\fP enables ksu to find principal names in jpayne@68: the .k5users file as described in the OPTIONS section jpayne@68: (see \fB\-n\fP option). jpayne@68: .TP jpayne@68: \fBCMD_PATH\fP jpayne@68: Specifies a list of directories containing programs that users are jpayne@68: authorized to execute (via .k5users file). jpayne@68: .TP jpayne@68: \fBHAVE_GETUSERSHELL\fP jpayne@68: If the source user is non\-root, ksu insists that the target user\(aqs jpayne@68: shell to be invoked is a "legal shell". \fIgetusershell(3)\fP is jpayne@68: called to obtain the names of "legal shells". Note that the jpayne@68: target user\(aqs shell is obtained from the passwd file. jpayne@68: .UNINDENT jpayne@68: .sp jpayne@68: Sample configuration: jpayne@68: .INDENT 0.0 jpayne@68: .INDENT 3.5 jpayne@68: .sp jpayne@68: .nf jpayne@68: .ft C jpayne@68: KSU_OPTS = \-DGET_TGT_VIA_PASSWD \-DPRINC_LOOK_AHEAD \-DCMD_PATH=\(aq"/bin /usr/ucb /local/bin" jpayne@68: .ft P jpayne@68: .fi jpayne@68: .UNINDENT jpayne@68: .UNINDENT jpayne@68: .sp jpayne@68: ksu should be owned by root and have the set user id bit turned on. jpayne@68: .sp jpayne@68: ksu attempts to get a ticket for the end server just as Kerberized jpayne@68: telnet and rlogin. Thus, there must be an entry for the server in the jpayne@68: Kerberos database (e.g., \fBhost/nii.isi.edu@ISI.EDU\fP). The keytab jpayne@68: file must be in an appropriate location. jpayne@68: .SH SIDE EFFECTS jpayne@68: .sp jpayne@68: ksu deletes all expired tickets from the source cache. jpayne@68: .SH AUTHOR OF KSU jpayne@68: .sp jpayne@68: GENNADY (ARI) MEDVINSKY jpayne@68: .SH ENVIRONMENT jpayne@68: .sp jpayne@68: See kerberos(7) for a description of Kerberos environment jpayne@68: variables. jpayne@68: .SH SEE ALSO jpayne@68: .sp jpayne@68: kerberos(7), kinit(1) jpayne@68: .SH AUTHOR jpayne@68: MIT jpayne@68: .SH COPYRIGHT jpayne@68: 1985-2022, MIT jpayne@68: .\" Generated by docutils manpage writer. jpayne@68: .