## 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  pro-
         gram  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 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, authen-
         tication 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  tar-
         get  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 princi-
         pal 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).  Other-
         wise, 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  vari-
         ables.  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 speci-
         fied 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  tick-
         ets  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 speci-
         fied  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 suc-
         cessful,  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 author-
                   ized 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 environ-
                   ment  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 speci-
                   fied 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  com-
                   mand (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 ==  tar-
                   get  user,  no  authorization  takes place and the
                   command is executed.  If source user id != 0,  and
                   ~target_user/.k5users file does not exist, author-
                   ization 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  fol-
                   lowed  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 exe-
                   cute      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 exe-
                   cute 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 fol-
                   lowing -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  com-
                   mand.

## 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 Ker-
                   beros 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 princi-
                   pal names in the .k5users file as described in the
                   OPTIONS section (see -n option).

         CMD_PATH  specifies a list of  directories  containing  pro-
                   grams  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