diff options
Diffstat (limited to 'src/clients/ksu/ksu.M')
| -rw-r--r-- | src/clients/ksu/ksu.M | 481 |
1 files changed, 0 insertions, 481 deletions
diff --git a/src/clients/ksu/ksu.M b/src/clients/ksu/ksu.M deleted file mode 100644 index 00e000847a..0000000000 --- a/src/clients/ksu/ksu.M +++ /dev/null @@ -1,481 +0,0 @@ -.\" Copyright (c) 1994 by the University of Southern California -.\" -.\" EXPORT OF THIS SOFTWARE from the United States of America may -.\" require a specific license from the United States Government. -.\" It is the responsibility of any person or organization contemplating -.\" export to obtain such a license before exporting. -.\" -.\" WITHIN THAT CONSTRAINT, permission to copy, modify, and distribute -.\" this software and its documentation in source and binary forms is -.\" hereby granted, provided that any documentation or other materials -.\" related to such distribution or use acknowledge that the software -.\" was developed by the University of Southern California. -.\" -.\" DISCLAIMER OF WARRANTY. THIS SOFTWARE IS PROVIDED "AS IS". The -.\" University of Southern California MAKES NO REPRESENTATIONS OR -.\" WARRANTIES, EXPRESS OR IMPLIED. By way of example, but not -.\" limitation, the University of Southern California MAKES NO -.\" REPRESENTATIONS OR WARRANTIES OF MERCHANTABILITY OR FITNESS FOR ANY -.\" PARTICULAR PURPOSE. The University of Southern -.\" California shall not be held liable for any liability nor for any -.\" direct, indirect, or consequential damages with respect to any -.\" claim by the user or distributor of the ksu software. -.\" -.\" KSU was written by: Ari Medvinsky, ari@isi.edu -.\" " -.TH KSU 1 -.SH NAME -ksu \- Kerberized super-user -.SH SYNOPSIS -.B ksu -[ -.I target_user -] [ -.B \-n -.I target_principal_name -] [ -.B \-c -.I source_cache_name -] [ -.B \-k -] [ -.B \-D -] [ -.B \-r -.I time -] [ -.B \-pf -] [ -.B \-l -.I lifetime -] [ -.B \-zZ -] [ -.B \-q -] [ -.B \-e -.I command -[ -.I args ... -] ] [ -.B \-a -[ -.I args ... -] ] -.br -.SH REQUIREMENTS -Must have Kerberos version 5 installed to compile ksu. -Must have a Kerberos version 5 server running to use ksu. -.br -.SH DESCRIPTION -.I ksu -is a Kerberized version of the su program that has two missions: -one is to securely change the real and effective user ID to that -of the target user, and the other is to create a new security context. -For the sake of clarity, all references to and attributes of -the user invoking the program will start with 'source' (e.g. -source user, source cache, etc.). Likewise, all references -to and attributes of the target account will start with 'target'. -.br -.SH AUTHENTICATION -To fulfill the first mission, ksu operates in two phases: authentication -and authorization. Resolving the target principal name is the -first step in authentication. The user -can either specify his principal name with the -.B \-n -option -(e.g. -.B \-n -jqpublic@USC.EDU) or a default principal name will be assigned -using a heuristic described in the OPTIONS section (see -.B \-n -option). -The target user name must be the first argument to ksu; if not specified -root is the default. If '.' is specified then the target user will be -the source user (e.g. ksu .). -If the source user is root or the target user is the source user, no -authentication or authorization takes place. Otherwise, ksu looks -for an appropriate Kerberos ticket in the source cache. -.PP -The ticket can either be for -the end-server -or a ticket granting ticket (TGT) for the target principal's realm. If the -ticket for the end-server is already in the cache, it's decrypted and -verified. If it's not in the cache but the TGT is, the TGT is used to -obtain the ticket for the end-server. The end-server ticket is then -verified. If neither ticket is in the cache, but ksu is compiled -with the GET_TGT_VIA_PASSWD define, the user will be prompted -for a Kerberos password which will then be used to get a TGT. -If the user is logged in remotely and -does not have a secure channel, the password may be exposed. -If neither ticket is in the cache and GET_TGT_VIA_PASSWD is not defined, -authentication fails. -.br -.SH AUTHORIZATION -This section describes authorization of the source user when ksu -is invoked without the -.B \-e -option. -For a description of the -.B \-e -option, see the OPTIONS section. -.PP -Upon successful authentication, ksu checks whether the target principal -is authorized to access the target account. -In the target user's home directory, ksu attempts to access -two authorization files: .k5login and .k5users. In the .k5login -file each line contains the name of a -principal that is authorized to access the account. -.TP 12 -For example: -jqpublic@USC.EDU -.br -jqpublic/secure@USC.EDU -.br -jqpublic/admin@USC.EDU -.PP -The format of .k5users is the same, except the -principal name may be followed by a list of commands that -the principal is authorized to execute. (see the -.B \-e -option in the OPTIONS section for details). -.PP -Thus if the target principal -name is found in the .k5login file the source user is authorized to access -the target account. Otherwise ksu looks in the .k5users file. -If the target principal name is found without any trailing commands -or followed only by '*' then the source user is authorized. -If either .k5login or .k5users exist but an appropriate entry for the target -principal does not exist then access is denied. If neither -file exists then the principal will be granted access -to the account according to the aname\->lname mapping rules (see -.IR krb5_anadd(8) -for more details). -Otherwise, authorization fails. -.br -.SH EXECUTION OF THE TARGET SHELL -Upon successful authentication and authorization, ksu -proceeds in a similar fashion to su. The environment -is unmodified with the exception of USER, HOME and SHELL variables. -If the target user is not root, USER gets set to the target user -name. Otherwise USER remains unchanged. Both HOME and SHELL are -set to the target login's default values. -In addition, the environment variable KRB5CCNAME gets set to the -name of the target cache. -The real and effective user ID are changed to that of the -target user. The target user's shell is then invoked -(the shell name is specified in the password file). -Upon termination of the shell, ksu deletes the target cache (unless -ksu is invoked with the -.B \-k option). -This is implemented by first doing a fork and then an exec, instead -of just exec, as done by su. -.br -.SH CREATING A NEW SECURITY CONTEXT -.PP -Ksu can be used to create a new security context for the -target program (either the target -shell, or command specified via the -e option). -The target program inherits a set -of credentials from the source user. -By default, this set includes all of the credentials -in the source cache plus any -additional credentials obtained during authentication. -The source user is able to limit the credentials in this set -by using -z or -Z option. --z restricts the copy of tickets from the source cache -to the target cache to only the tickets where client == -the target principal name. The -Z option -provides the target user with a fresh target cache -(no creds in the cache). Note that for security reasons, -when the source user is root and target user is non-root, --z option is the default mode of operation. - -While no authentication takes place if the source user -is root or is the same as the target user, additional -tickets can still be obtained for the target cache. -If -n is specified and no credentials can be copied to the target -cache, the source user is prompted for a Kerberos password -(unless -Z specified or GET_TGT_VIA_PASSWD is undefined). If -successful, a TGT is obtained from the Kerberos server and -stored in the target cache. Otherwise, -if a password is not provided (user hit return) -ksu continues in a -normal mode of operation (the target cache will -not contain the desired TGT). -If the wrong password is typed in, ksu fails. -.PP -\fISide Note:\fP during authentication, only the tickets that could be -obtained without providing a password are cached in -in the source cache. -.SH OPTIONS -.TP 10 -\fB\-n \fItarget_principal_name -Specify a Kerberos target principal name. -Used in authentication and authorization -phases of ksu. - -If ksu is invoked without -.B \-n, -a default principal name is -assigned via the following heuristic: - -\fICase 1:\fP source user is non-root. -.br -If the target user is the source user the default principal name -is set to the default principal of the source cache. If the -cache does not exist then the default principal name is set to -target_user@local_realm. -If the source and target users are different and -neither ~target_user/.k5users -nor ~target_user/.k5login exist then -the default principal name is -target_user_login_name@local_realm. Otherwise, -starting with the first principal listed below, -ksu checks if the principal is authorized -to access the target account and whether -there is a legitimate ticket for that principal -in the source cache. If both conditions are met -that principal becomes the default target principal, -otherwise go to the next principal. - -a) default principal of the source cache -.br -b) target_user@local_realm -.br -c) source_user@local_realm - -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. -If that fails select the first principal that -is authorized to access the target account from -the above list. -If none are authorized and ksu is configured with PRINC_LOOK_AHEAD -turned on, select the default principal as follows: - -For each candidate in the above list, -select an authorized principal that has -the same realm name and first part -of the principal name equal to the prefix of the candidate. -For example if candidate a) is jqpublic@ISI.EDU and jqpublic/secure@ISI.EDU -is authorized to access the target account then the default principal -is set to jqpublic/secure@ISI.EDU. - -\fICase 2:\fP source user is root. -.br -If the target user is non-root then the -default principal name is target_user@local_realm. -Else, if the source cache exists the default -principal name is set to the default principal -of the source cache. If the source cache does not -exist, default principal name is set to -root@local_realm. -.TP 10 -\fB\-c \fIsource_cache_name -Specify source cache name (e.g. -.B \-c -FILE:/tmp/my_cache). -If -.B \-c -option is not used then the -name is obtained from KRB5CCNAME environment variable. -If KRB5CCNAME is not defined the source cache name -is set to krb5cc_<source uid>. -The target cache name is automatically -set to krb5cc_<target uid>.(gen_sym()), -where gen_sym generates a new number such that -the resulting cache does not already exist. -.br -For example: krb5cc_1984.2 -.TP 10 -\fB\-k -Do not delete the target cache upon termination of the -target shell or a command ( -.B \-e -command). -Without -.B \-k, -ksu deletes the target cache. -.TP 10 -\fB\-D -turn on debug mode. -.TP 10 -\fITicket granting ticket options: -l lifetime -r time -pf\fP -The ticket granting ticket options only apply to the -case where there are no appropriate tickets in -the cache to authenticate the source user. In this case -if ksu is configured to prompt users for a -Kerberos password (GET_TGT_VIA_PASSWD is defined), -the ticket granting -ticket options that are specified will be used -when getting a ticket granting ticket from the Kerberos -server. -.TP 10 -\fB\-l \fIlifetime -option specifies the lifetime to be -requested for the ticket; if this option is not -specified, the default ticket lifetime -(configured by each site) is used instead. -.TP 10 -\fB\-r \fItime -option specifies that the RENEWABLE option -should be requested for the ticket, and specifies -the desired total lifetime of the ticket. -.TP 10 -\fB\-p -option specifies that the PROXIABLE option should be -requested for the ticket. -.TP 10 -\fB\-f -option specifies that the FORWARDABLE option should -be requested for the ticket. -.TP 10 -\fB\-z -restrict the copy of tickets from the source cache -to the target cache to only the tickets where client == -the target principal name. Use the -.B \-n -option -if you want the tickets for other then the default -principal. Note that the -.B \-z -option is mutually -exclusive with the -Z option. -.TP 10 -\fB\-Z -Don't copy any tickets from the source cache to the -target cache. Just create a fresh target cache, -where the default principal name of the cache is -initialized to the target principal name. Note that -.B \-Z -option is mutually -exclusive with the -z option. -.TP 10 -\fB\-q -suppress the printing of status messages. -.TP 10 -\fB\-e \fIcommand [args ...] -ksu proceeds exactly the same as if it was invoked without the -.B \-e -option, -except instead of executing the target shell, ksu executes the -specified command (Example of usage: ksu bob -.B \-e -ls -.B \-lag). - -\fIThe authorization algorithm for -e is as follows:\fP - -If the source user is root or source user == target user, -no authorization takes place and -the command is executed. If source user id != 0, and ~target_user/.k5users -file does not exist, authorization fails. -Otherwise, ~target_user/.k5users file must have an -appropriate entry for target principal -to get authorized. - -\fIThe .k5users file format:\fP - -A single principal entry on each line -that may be followed by a list of commands that -the principal is authorized to execute. -A principal name followed by a '*' means -that the user is authorized to execute -any command. Thus, in the following example: - -jqpublic@USC.EDU ls mail /local/kerberos/klist -.br -jqpublic/secure@USC.EDU * -.br -jqpublic/admin@USC.EDU - -jqpublic@USC.EDU is only authorized to execute ls, mail -and klist commands. jqpublic/secure@USC.EDU is authorized -to execute any command. jqpublic/admin@USC.EDU is not -authorized to execute any command. Note, that -jqpublic/admin@USC.EDU is authorized to execute -the target shell (regular ksu, without the -.B \-e -option) but jqpublic@USC.EDU is not. - -The commands listed after the principal name must -be either a full path names or just the program name. -In the second case, CMD_PATH specifying the location -of authorized programs must be defined at the -compilation time of ksu. - -\fIWhich command gets executed ?\fP - -If the source user is root or -the target user is the source user or -the user -is authorized to execute any command ('*' entry) -then command can be either a full or a relative -path leading to the target program. -Otherwise, the user must specify either a full -path or just the program name. -.TP 10 -\fB\-a \fIargs -specify arguments to be passed to the target shell. -Note: that all flags and parameters following -a -will be passed to the shell, thus all options -intended for ksu must precede -.B \-a. -The -.B \-a -option can be used to simulate the -.B \-e -option if used as follows: -.B \-a -.B \-c -[command [arguments]]. -.B \-c -is interpreted by the c-shell to execute the command. -.PP -.SH INSTALLATION INSTRUCTIONS -ksu can be compiled with the following 4 flags (see the Imakefile): -.TP 10 -\fIGET_TGT_VIA_PASSWD\fP -in case no appropriate tickets are found in the source -cache, the user will be prompted for a Kerberos -password. The password is then used to get a -ticket granting ticket from the Kerberos server. -The danger of configuring ksu with this macro is -if the source user is logged in remotely and does not -have a secure channel, the password may get exposed. -.TP 10 -\fIPRINC_LOOK_AHEAD\fP -during the resolution of the default principal name, -PRINC_LOOK_AHEAD enables ksu to find principal names -in the .k5users file as described in the OPTIONS section -(see -n option). -.TP 10 -\fICMD_PATH\fP -specifies a list of directories containing programs -that users are authorized to execute (via .k5users file). -.TP 10 -\fIHAS_GETUSERSHELL\fP -If the source user is non-root, ksu insists that -the target user's shell to be invoked -is a "legal shell". getusershell(3) is called to obtain -the names of "legal shells". Note that the target user's -shell is obtained from the passwd file. -.TP 10 -SAMPLE CONFIGURATION: -KSU_OPTS = -DGET_TGT_VIA_PASSWD --DPRINC_LOOK_AHEAD -DCMD_PATH='"/bin /usr/ucb /local/bin" -.TP 10 -PERMISSIONS FOR KSU -ksu should be owned by root and have the set user id bit turned on. -.TP 10 -END-SERVER ENTRY - -ksu attempts to get a ticket for the end server just as Kerberized -telnet and rlogin. Thus, there must be an entry for the server in the -Kerberos database (e.g. host/nii.isi.edu@ISI.EDU). The keytab file must -be in an appropriate location. - -.SH SIDE EFFECTS -ksu deletes all expired tickets from the source cache. -.SH AUTHOR OF KSU: GENNADY (ARI) MEDVINSKY |