From: Zhanna Tsitkov Date: Mon, 1 Aug 2011 20:09:44 +0000 (+0000) Subject: Added ksu and kvno man pages documentation to Sphinx doc tree X-Git-Tag: krb5-1.10-alpha1~309 X-Git-Url: http://git.tremily.us/?a=commitdiff_plain;h=ee3821569c57a25885a4665d4443c5a6417f7550;p=krb5.git Added ksu and kvno man pages documentation to Sphinx doc tree git-svn-id: svn://anonsvn.mit.edu/krb5/trunk@25066 dc483132-0cff-0310-8789-dd5450dbe970 --- diff --git a/doc/rst_source/conf.py b/doc/rst_source/conf.py index 21c225a1b..1ccb481e4 100644 --- a/doc/rst_source/conf.py +++ b/doc/rst_source/conf.py @@ -222,4 +222,6 @@ man_pages = [ ('krb_users/user_commands/klist', 'klist', u'list cached Kerberos tickets', [u'MIT'], 1), ('krb_users/user_commands/kdestroy', 'kdestroy', u'destroy Kerberos tickets', [u'MIT'], 1), ('krb_users/user_commands/kpasswd', 'kpasswd', u'change a user\'s Kerberos password', [u'MIT'], 1), + ('krb_users/user_commands/kvno', 'kvno', u'print key version numbers of Kerberos principals', [u'MIT'], 1), + ('krb_users/user_commands/ksu', 'ksu', u'Kerberized super-user', [u'MIT'], 1), ] diff --git a/doc/rst_source/krb_users/user_commands/index.rst b/doc/rst_source/krb_users/user_commands/index.rst index 00ffedd82..e88f4ab09 100644 --- a/doc/rst_source/krb_users/user_commands/index.rst +++ b/doc/rst_source/krb_users/user_commands/index.rst @@ -11,6 +11,8 @@ User commands klist.rst kdestroy.rst kpasswd.rst + kvno.rst + ksu.rst ------------------ diff --git a/doc/rst_source/krb_users/user_commands/klist.rst b/doc/rst_source/krb_users/user_commands/klist.rst index 4986a6252..86a514c8e 100644 --- a/doc/rst_source/krb_users/user_commands/klist.rst +++ b/doc/rst_source/krb_users/user_commands/klist.rst @@ -5,10 +5,11 @@ klist - list cached Kerberos tickets SYNOPSIS ~~~~~~~~ -*klist* +**klist** [**-e**] [[**-c**] [**-f**] [**-s**] [**-a** [**-n**]]] [**-k** [**-t**] [**-K**]] + [**-V**] [*cache_name* | *keytab_name*] @@ -66,6 +67,9 @@ OPTIONS **-K** Display the value of the encryption key in each *keytab* entry in the *keytab* file. + **-V** + Display the Kerberos version number and exit. + If **cache_name** or **keytab_name** is not specified, *klist* will display the credentials in the default credentials cache or *keytab* file as appropriate. If the *KRB5CCNAME* environment variable is set, its value is used to name the default ticket cache. diff --git a/doc/rst_source/krb_users/user_commands/ksu.rst b/doc/rst_source/krb_users/user_commands/ksu.rst new file mode 100644 index 000000000..4c51a2b6f --- /dev/null +++ b/doc/rst_source/krb_users/user_commands/ksu.rst @@ -0,0 +1,284 @@ +ksu - Kerberized super-user +================================= + +SYNOPSIS +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**ksu** + [ *target_user* ] + [ **-n** *target_principal_name* ] + [ **-c** *source_cache_name* ] + [ **-k** ] + [ **-D** ] + [ **-r** time ] + [ **-pf** ] + [ **-l** *lifetime* ] + [ **-z | Z** ] + [ **-q** ] + [ **-e** *command* [ args ... ] ] [ **-a** [ args ... ] ] + + +REQUIREMENTS +~~~~~~~~~~~~~~~~~ + +Must have Kerberos version 5 installed to compile *ksu*. Must have a Kerberos version 5 server running to use *ksu*. + +DESCRIPTION +~~~~~~~~~~~~~~~ + +*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'. + +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 *-n* option (e.g. *-n jqpublic\@USC.EDU* ) or +a default principal name will be assigned using a heuristic described in the *OPTIONS* section (see *-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. + +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. + +AUTHORIZATION +~~~~~~~~~~~~~~~~~~ + +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. + +For example:: + + jqpublic@USC.EDU + 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). + +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). +Otherwise, authorization fails. + +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 *-k* option). +This is implemented by first doing a fork and then an exec, instead of just exec, as done by *su*. + +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). +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. + +*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_. + The target cache name is automatically set to krb5cc_.(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* + 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. + + **-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. + + **-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: + + 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: + + 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* 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 ? + + 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*. + + The *-a* option can be used to simulate the *-e* option if used as follows:: + + -a -c [command [arguments]]. + + *-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): + + **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 loged 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). + + **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. + + SAMPLE CONFIGURATION: + KSU_OPTS = -DGET_TGT_VIA_PASSWD -DPRINC_LOOK_AHEAD -DCMD_PATH='"/bin /usr/ucb /local/bin" + + 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 +~~~~~~~~~~~~~~~ + +*ksu* deletes all expired tickets from the source cache. + +AUTHOR OF KSU: +~~~~~~~~~~~~~~~ + +GENNADY (ARI) MEDVINSKY + diff --git a/doc/rst_source/krb_users/user_commands/kvno.rst b/doc/rst_source/krb_users/user_commands/kvno.rst new file mode 100644 index 000000000..d64c3d28f --- /dev/null +++ b/doc/rst_source/krb_users/user_commands/kvno.rst @@ -0,0 +1,63 @@ +kvno - print key version numbers of Kerberos principals +=========================================================== + +SYNOPSIS +~~~~~~~~~~~~~~~ + +**kvno** + [**-c** *ccache*] + [**-e** *etype*] + [**-q**] + [**-h**] + [**-P**] + [**-S** *sname*] + [**-U** *for_user*] + *service1 service2* ... + +DESCRIPTION +~~~~~~~~~~~~~~~ + +*kvno* acquires a service ticket for the specified Kerberos principals and prints out the key version numbers of each. + +OPTIONS +~~~~~~~~~~~~~~~ + + **-c** *ccache* + Specifies the name of a credentials cache to use (if not the default) + + **-e** *etype* + Specifies the enctype which will be requested for the session key of all the services named on the command line. This is useful in certain backward compatibility situations. + + **-q** + Suppress printing + + **-h** + Prints a usage statement and exits + + **-P** + Specifies that the *service1 service2* ... arguments are to be treated as services for which credentials should be acquired using constrained delegation. This option is only valid when used in conjunction with protocol transition. + + **-S** *sname* + Specifies that krb5_sname_to_principal() will be used to build principal names. If this flag is specified, the *service1 service2* ... arguments are interpreted as hostnames (rather than principal names), and sname is interpreted as the service name. + + **-U** *for_user* + Specifies that protocol transition (S4U2Self) is to be used to acquire a ticket on behalf of for_user. If constrained delegation is not requested, the service name must match the credentials cache client principal. + +ENVIRONMENT +~~~~~~~~~~~~~~~ + +*kvno* uses the following environment variable: + + **KRB5CCNAME** - Location of the credentials (ticket) cache. + +FILES +~~~~~~~~~~~~~~~ + +/tmp/krb5cc_[uid] default location of the credentials cache ([uid] is the decimal UID of the user). + +SEE ALSO +~~~~~~~~~~~~~~~ + +kinit(1), kdestroy(1), krb5(3) + +