*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'.
+
+.. note::
+ 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'.
AUTHENTICATION
~~~~~~~~~~~~~~~~~~~~~
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 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.
This section describes authorization of the source user when *ksu* is invoked without the *-e* option.
For a description of the -e option, see the OPTIONS section.
-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.
+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.
For example::
jqpublic/secure@USC.EDU
jqpublic/admin@USC.EDU
-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 *-e* option in the *OPTIONS* section for details).
+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 *-e* option in the *OPTIONS* section for details).
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 krb5_anadd(8) for more details).
+If neither file exists then the principal will be granted access to the account according to the aname->lname mapping rules.
Otherwise, authorization fails.
EXECUTION OF THE TARGET SHELL
CREATING A NEW SECURITY CONTEXT
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-*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).
+*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.
+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.
+*-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.
+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.
+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 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.
-*Side Note*: during authentication, only the tickets that could be obtained without providing a password are cached in in the source cache.
+*Side Note*: during authentication, only the tickets that could be obtained without
+providing a password are cached in in the source cache.
OPTIONS
~~~~~~~~~~~~~~~
- **-n** *target_principal_name*
- Specify a Kerberos target principal name. Used in authentication and authorization phases of *ksu*.
-
- If *ksu* is invoked without *-n*, a default principal name is assigned via the following heuristic:
-
- *Case 1: source user is non-root.*
- 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
- b) target_user\@local_realm
- 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*.
-
- *Case 2: source user is root.*
- 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*.
-
- **-c** *source_cache_name*
- Specify source cache name (e.g. -c FILE:/tmp/my_cache).
- If *-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.
- For example::
-
- krb5cc_1984.2
-
- **-k**
- Do not delete the target cache upon termination of the target shell or a command ( *-e* command).
- Without *-k*, *ksu* deletes the target cache.
-
- **-D**
- Turn on debug mode.
-
- **-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 *-n* option if you want the tickets for other then the default principal.
- Note that the *-z* option is mutually exclusive with the *-Z* option.
-
- **-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 the *-Z* option is mutually exclusive with the *-z* option.
-
- **-q**
- Suppress the printing of status messages.
+ **-n** *target_principal_name*
+ Specify a Kerberos target principal name. Used in authentication and authorization phases of *ksu*.
+
+ If *ksu* is invoked without *-n*, a default principal name is assigned via the following heuristic:
+
+ *Case 1: source user is non-root.*
+ 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
+ b) target_user\@local_realm
+ 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*.
+
+ *Case 2: source user is root.*
+ 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*.
+
+ **-c** *source_cache_name*
+ Specify source cache name (e.g. -c FILE\:/tmp/my_cache).
+ If *-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.
+ For example::
+
+ krb5cc_1984.2
+
+ **-k**
+ Do not delete the target cache upon termination of the target shell or a command ( *-e* command).
+ Without *-k*, *ksu* deletes the target cache.
+
+ **-D**
+ Turn on debug mode.
+
+ **-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 *-n* option if you want the tickets for other then the default principal.
+ Note that the *-z* option is mutually exclusive with the *-Z* option.
+
+ **-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 the *-Z* option is mutually exclusive with the *-z* option.
+
+ **-q**
+ Suppress the printing of status messages.
Ticket granting ticket options
- **-l lifetime -r time -pf**
- 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.
+ **-l** *lifetime* **-r** *time* **-pf**
+ 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.
- **-l** *lifetime*
- 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.
+ **-l** *lifetime*
+ 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.
- **-r** *time*
- option specifies that the *RENEWABLE* option should be requested for the ticket, and specifies the desired total lifetime of the ticket.
+ **-r** *time*
+ option specifies that the *RENEWABLE* option should be requested for the ticket, and specifies the desired total lifetime of the ticket.
- **-p**
- option specifies that the PROXIABLE option should be requested for the ticket.
+ **-p**
+ option specifies that the PROXIABLE option should be requested for the ticket.
- **-f**
- option specifies that the FORWARDABLE option should be requested for the ticket.
+ **-f**
+ option specifies that the FORWARDABLE option should be requested for the ticket.
- **-e** *command* [args ...]
- *ksu* proceeds exactly the same as if it was invoked without the *-e* option,
- except instead of executing the target shell, *ksu* executes the specified command
- Example of usage::
-
- ksu bob -e ls -lag
+ **-e** *command* [args ...]
+ *ksu* proceeds exactly the same as if it was invoked without the *-e* option,
+ except instead of executing the target shell, *ksu* executes the specified command
+ Example of usage::
+
+ ksu bob -e ls -lag
- The authorization algorithm for *-e* is as follows:
+ The authorization algorithm for *-e* is as follows:
- 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.
+ 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.
- The *.k5users* file format:
+ The *.k5users* file format:
- 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::
+ 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
- jqpublic/secure@USC.EDU *
- jqpublic/admin@USC.EDU
+ jqpublic@USC.EDU ls mail /local/kerberos/klist
+ jqpublic/secure@USC.EDU *
+ 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 *-e* option)
- but *jqpublic\@USC.EDU* is not.
+ *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 *-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*.
- Which command gets executed ?
+ 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*.
+ Which command gets executed ?
- 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.
+ 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.
- **-a** *args*
- 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 *-a*.
+ **-a** *args*
+ 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 *-a*.
- The *-a* option can be used to simulate the *-e* option if used as follows::
+ The *-a* option can be used to simulate the *-e* option if used as follows::
- -a -c [command [arguments]].
+ -a -c [command [arguments]].
- *-c* is interpreted by the c-shell to execute the command.
+ *-c* is interpreted by the c-shell to execute the command.
INSTALLATION INSTRUCTIONS
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-*ksu* can be compiled with the following 4 flags (see the Imakefile):
+*ksu* can be compiled with the following four flags:
- **GET_TGT_VIA_PASSWD**
- 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.
+ **GET_TGT_VIA_PASSWD**
+ 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.
- **PRINC_LOOK_AHEAD**
- 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).
+ **PRINC_LOOK_AHEAD**
+ 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).
- **CMD_PATH**
- Specifies a list of directories containing programs that users are authorized to execute (via *.k5users* file).
+ **CMD_PATH**
+ Specifies a list of directories containing programs that users are authorized to execute (via *.k5users* file).
- **HAS_GETUSERSHELL**
- 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.
+ **HAVE_GETUSERSHELL**
+ 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.
- SAMPLE CONFIGURATION:
- KSU_OPTS = -DGET_TGT_VIA_PASSWD -DPRINC_LOOK_AHEAD -DCMD_PATH='"/bin /usr/ucb /local/bin"
+SAMPLE CONFIGURATION
- PERMISSIONS FOR KSU
- *ksu* should be owned by root and have the set user id bit turned on.
+ KSU_OPTS = -DGET_TGT_VIA_PASSWD -DPRINC_LOOK_AHEAD -DCMD_PATH='"/bin /usr/ucb /local/bin"
- 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.
+PERMISSIONS FOR KSU
+ *ksu* should be owned by root and have the *set user id* bit turned on.
+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.
+
SIDE EFFECTS
~~~~~~~~~~~~~~~
projects / krb5.git / commitdiff