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





















































Man(1) output converted with man2html