Added ksu and kvno man pages documentation to Sphinx doc tree
authorZhanna Tsitkov <tsitkova@mit.edu>
Mon, 1 Aug 2011 20:09:44 +0000 (20:09 +0000)
committerZhanna Tsitkov <tsitkova@mit.edu>
Mon, 1 Aug 2011 20:09:44 +0000 (20:09 +0000)
git-svn-id: svn://anonsvn.mit.edu/krb5/trunk@25066 dc483132-0cff-0310-8789-dd5450dbe970

doc/rst_source/conf.py
doc/rst_source/krb_users/user_commands/index.rst
doc/rst_source/krb_users/user_commands/klist.rst
doc/rst_source/krb_users/user_commands/ksu.rst [new file with mode: 0644]
doc/rst_source/krb_users/user_commands/kvno.rst [new file with mode: 0644]

index 21c225a1bfce08f480b0a0bbd1358dd6f7d91147..1ccb481e47f1c59dd567ad7ea9b6b4b1bb29d877 100644 (file)
@@ -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),
 ]
index 00ffedd829421c61b74fd35c76469b1edc6d58d8..e88f4ab0954251bc88f674de6a90c1c73f6caff1 100644 (file)
@@ -11,6 +11,8 @@ User commands
    klist.rst
    kdestroy.rst
    kpasswd.rst
+   kvno.rst
+   ksu.rst
 
 
 ------------------
index 4986a6252d65197de7334c2e7a68d93a49c54781..86a514c8edd3eac0de93e7b9df7668e67293adaa 100644 (file)
@@ -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 (file)
index 0000000..4c51a2b
--- /dev/null
@@ -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_<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@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 (file)
index 0000000..d64c3d2
--- /dev/null
@@ -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)
+
+