svn rev #25066: trunk/doc/rst_source/ krb_users/user_commands/
tsitkova@MIT.EDU
tsitkova at MIT.EDU
Mon Aug 1 16:09:44 EDT 2011
http://src.mit.edu/fisheye/changelog/krb5/?cs=25066
Commit By: tsitkova
Log Message:
Added ksu and kvno man pages documentation to Sphinx doc tree.
Changed Files:
U trunk/doc/rst_source/conf.py
U trunk/doc/rst_source/krb_users/user_commands/index.rst
U trunk/doc/rst_source/krb_users/user_commands/klist.rst
A trunk/doc/rst_source/krb_users/user_commands/ksu.rst
A trunk/doc/rst_source/krb_users/user_commands/kvno.rst
Modified: trunk/doc/rst_source/conf.py
===================================================================
--- trunk/doc/rst_source/conf.py 2011-08-01 15:18:21 UTC (rev 25065)
+++ trunk/doc/rst_source/conf.py 2011-08-01 20:09:44 UTC (rev 25066)
@@ -222,4 +222,6 @@
('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),
]
Modified: trunk/doc/rst_source/krb_users/user_commands/index.rst
===================================================================
--- trunk/doc/rst_source/krb_users/user_commands/index.rst 2011-08-01 15:18:21 UTC (rev 25065)
+++ trunk/doc/rst_source/krb_users/user_commands/index.rst 2011-08-01 20:09:44 UTC (rev 25066)
@@ -11,6 +11,8 @@
klist.rst
kdestroy.rst
kpasswd.rst
+ kvno.rst
+ ksu.rst
------------------
Modified: trunk/doc/rst_source/krb_users/user_commands/klist.rst
===================================================================
--- trunk/doc/rst_source/krb_users/user_commands/klist.rst 2011-08-01 15:18:21 UTC (rev 25065)
+++ trunk/doc/rst_source/krb_users/user_commands/klist.rst 2011-08-01 20:09:44 UTC (rev 25066)
@@ -5,10 +5,11 @@
SYNOPSIS
~~~~~~~~
-*klist*
+**klist**
[**-e**]
[[**-c**] [**-f**] [**-s**] [**-a** [**-n**]]]
[**-k** [**-t**] [**-K**]]
+ [**-V**]
[*cache_name* | *keytab_name*]
@@ -66,6 +67,9 @@
**-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.
Added: trunk/doc/rst_source/krb_users/user_commands/ksu.rst
===================================================================
--- trunk/doc/rst_source/krb_users/user_commands/ksu.rst (rev 0)
+++ trunk/doc/rst_source/krb_users/user_commands/ksu.rst 2011-08-01 20:09:44 UTC (rev 25066)
@@ -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 at USC.EDU
+ jqpublic/secure at USC.EDU
+ jqpublic/admin at 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_<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*
+ 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 at USC.EDU ls mail /local/kerberos/klist
+ jqpublic/secure at USC.EDU *
+ jqpublic/admin at 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
+
Added: trunk/doc/rst_source/krb_users/user_commands/kvno.rst
===================================================================
--- trunk/doc/rst_source/krb_users/user_commands/kvno.rst (rev 0)
+++ trunk/doc/rst_source/krb_users/user_commands/kvno.rst 2011-08-01 20:09:44 UTC (rev 25066)
@@ -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)
+
+
More information about the cvs-krb5
mailing list