Provided by: krb5-user_1.10+dfsg~beta1-2_amd64 bug

NAME

       ksu - Kerberized super-user

SYNOPSIS

       ksu  [ target_user ] [ -n target_principal_name ] [ -c source_cache_name ] [ -k ] [ -D ] [
       -r time ] [ -pf ] [ -l lifetime ] [ -zZ ] [ -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.

       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.

       -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 -Z option is  mutually  exclusive  with
                 the -z option.

       -q        suppress the printing of status messages.

       -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 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).

       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

                                                                                           KSU(1)