Skip site navigation (1)Skip section navigation (2)

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
KSU(1)				 MIT Kerberos				KSU(1)

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

       NOTE:
	  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
       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(5)
       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 exe-
       cute (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	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.
       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  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.

       NOTE:
	  During authentication, only the tickets that could be	obtained with-
	  out providing	a password are cached in in the	source cache.

OPTIONS
       -n target_principal_name
	      Specify  a  Kerberos target principal name.  Used	in authentica-
	      tion and authorization phases of ksu.

	      If ksu is	invoked	 without  -n,  a  default  principal  name  is
	      assigned via the following heuristic:

	      o	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	jqpub-
		lic/secure@ISI.EDU is authorized to access the target  account
		then  the default principal is set to jqpublic/secure@ISI.EDU.

	      o	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 envi-
	  ronment variable.  If	KRB5CCNAME is not  defined  the	 source	 cache
	  name	is set to krb5cc_<source uid>.	The target cache name is auto-
	  matically set	to krb5cc_<target uid>.(gen_sym()), where gen_sym gen-
	  erates  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 princi-
	      pal  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
	      (duration	string.)  Specifies the	lifetime to be	requested  for
	      the  ticket; if this option is not specified, the	default	ticket
	      lifetime (12 hours) is used instead.

       -r time
	      (duration	string.)  Specifies that the renewable	option	should
	      be  requested  for  the  ticket, and specifies the desired total
	      lifetime of the ticket.

       -p     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 exe-
	      cute 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 exe-
	      cuted?

	      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 four flags:

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

       HAVE_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"

       ksu should be owned by root and have the	set user id bit	turned on.

       ksu attempts to get a ticket for	the end	server just as Kerberized tel-
       net  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

AUTHOR
       MIT

COPYRIGHT
       1985-2015, MIT

1.11.6									KSU(1)

NAME | SYNOPSIS | REQUIREMENTS | DESCRIPTION | AUTHENTICATION | AUTHORIZATION | EXECUTION OF THE TARGET SHELL | CREATING A NEW SECURITY CONTEXT | OPTIONS | INSTALLATION INSTRUCTIONS | SIDE EFFECTS | AUTHOR OF KSU | AUTHOR | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=ksu&sektion=1&manpath=FreeBSD+10.2-RELEASE+and+Ports>

home | help