## 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:  authentica-
           tion  and  authorization.   Resolving  the target principal name is the
           first step in authentication.  The user can either specify his  princi-
           pal  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  nei-
           ther   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 prin-
           without  any  trailing commands or followed only by '*' then the source
           user is authorized.  If either .k5login or .k5users exist but an appro-
           priate  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 excep-
           tion 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  ter-
           mination  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 princi-
           pal  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 Ker-
           beros password (unless -Z  specified  or  GET_TGT_VIA_PASSWD  is  unde-
           fined). 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
                     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  jqpub-
                     lic/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 prin-
                     cipal 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

           -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  exe-
                     cute.  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 exe-
                     cute any command. jqpublic/admin@USC.EDU is not authorized to
                     execute any command.  Note,  that  jqpublic/admin@USC.EDU  is
                     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 pass-
                     word 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".  getuser-
                     shell(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 Ker-
                     berized 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.