KSU(1)

📦
version 1.22.1 · 3 versions
, in ubuntu resolute, ubuntu stonking

✨ ksu(1) — Kerberized super-user ✨

okay bestie, gather round, because we're about to talk about ksu from MIT Kerberos and honestly? it's giving main character energy 💅

🌸 SYNOPSIS 🌸

ksu [ target_user ] [ -n target_principal_name ] [ -c source_cache_name
] [ -k ] [ -r time ] [ -p | -P] [ -f | -F] [ -l lifetime ] [ -z | Z ] [
-q ] [ -e command [ args ...  ] ] [ -a [ args ...  ] ]

like. look at her. all those flags. a whole wardrobe 💖

🎀 REQUIREMENTS 🎀

okay so before you can even think about playing with her:

  • you literally must have Kerberos version 5 installed to compile ksu 🛠️
  • and you must have a Kerberos version 5 server running to use ksu 🔥

no Kerberos v5? no ksu. that's the vibe check and you did not pass it, sorry babe 😭

👑 DESCRIPTION 👑

so ksu is a Kerberized version of the su program, and she has two missions (iconic, honestly, a dual-threat queen):

  1. securely change the real and effective user ID to that of the target user 🪪
  2. create a new security context ✨
NOTE: for the sake of clarity, every single reference to and attribute of the user who's invoking the program starts with "source" (like "source user", "source cache", etc.). same energy for the target account — all references to and attributes of it start with "target". 🎯

🦋 AUTHENTICATION 🦋

to fulfill mission number one, ksu operates in two phases: authentication and authorization. periodt.

resolving the target principal name is the very first step in authentication. 🔍

so the user can either:

  • specify their 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 the -n option) — iykyk

the target user name must be the first argument to ksu; if it's not specified, root is the default. 👀

if . is specified then the target user will be the source user (e.g., ksu .). cute, self-love 🫶

if the source user is root or the target user is the source user, then no authentication or authorization takes place. none. zero. we're just vibing. otherwise, ksu goes looking for an appropriate Kerberos ticket in the source cache.

now here's where it gets juicy. 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. then the end-server ticket is 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. 🗝️

⚠️ bestie, listen. if the user is logged in remotely and does not have a secure channel, the password may be exposed. that's not a vibe. be careful. 😭

if neither ticket is in the cache and GET_TGT_VIA_PASSWD is not defined, authentication fails. full stop. 💀

🌈 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, bestie — we'll get there.) 📖

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
  • .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 the details 👀).

so, the flow is:

  • 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 exists 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
  • otherwise, authorization fails. 💀

🐚 EXECUTION OF THE TARGET SHELL 🐚

upon successful authentication and authorization, ksu proceeds in a similar fashion to su. slay, lineage. 👑

the environment is unmodified, with the exception of the 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. then the target user's shell is 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. nerdy detail but honestly? we love a fork-exec moment 🍴

💜 CREATING A NEW SECURITY CONTEXT 💜

ksu can be used to create a new security context for the target program — either the target shell, or a 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 the -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 ✂️
  • -Z provides the target user with a fresh target cache (no creds in the cache) 🧼
NOTE (and this one matters): for security reasons, when the source user is root and the target user is non-root, the -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 is 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 without providing a password are cached in the source cache. that's the rule. no notes. 💅

okay part one is done and there is literally more coming, don't go anywhere bestie 🫶✨

✨ OPTIONS ✨

okay bestie, buckle up, this is the flag buffet 💅 every single one, no skipping, i promise

  • -n target_principal_name — name your Kerberos target principal. this one gets used in the authentication and authorization phases of ksu. 🎯

if you run ksu without -n, a default principal name gets assigned by this whole heuristic, and yes we're doing both cases:

  • Case 1: source user is non-root.

if the target user is the source user, the default principal name = the default principal of the source cache. if that cache doesn't exist, the default principal name = target_user@local_realm. if source and target users are different and neither ~target_user/.k5users nor ~target_user/.k5login exist, the default principal name = target_user_login_name@local_realm. otherwise, starting with the first principal listed below, ksu checks whether the principal is authorized to access the target account, and whether there's a legit ticket for that principal in the source cache. both true? that principal becomes the default target principal. nope? next principal, keep it moving. 🚶‍♀️

  1. default principal of the source cache
  2. target_user@local_realm
  3. source_user@local_realm

if a–c fails, try any principal that has a ticket in the source cache and is authorized to access the target account. if that fails too, pick the first principal that's authorized to access the target account from the list above. if none are authorized and ksu was configured with PRINC_LOOK_AHEAD turned on, pick the default principal like this:

for each candidate in the list above, select an authorized principal that has the same realm name and whose first part of the principal name equals the prefix of the candidate. example: if candidate a) is jqpublic@ISI.EDU and jqpublic/secure@ISI.EDU is authorized to access the target account, then the default principal becomes jqpublic/secure@ISI.EDU. iconic, honestly. ✨

  • Case 2: source user is root.

if the target user is non-root, the default principal name = target_user@local_realm. else, if the source cache exists, the default principal name = the default principal of the source cache. if the source cache does not exist, the default principal name = root@local_realm.

  • -c source_cache_name — tell it your source cache name (like, e.g., -c FILE:/tmp/my_cache). skip -c and the name comes from the KRB5CCNAME environment variable. if KRB5CCNAME isn't defined either, the source cache name defaults to krb5cc_<source uid>. the target cache name sets itself automatically to krb5cc_<target uid>.(gen_sym()), where gen_sym makes a fresh number so the resulting cache doesn't already exist. for example:
krb5cc_1984.2
  • -k — do not delete the target cache when the target shell or a command (-e command) terminates. without -k, ksu deletes the target cache. so like, -k is the "keep the receipts" flag 🧾
  • -z — restrict the ticket copy from source cache → target cache to only the tickets where client == the target principal name. want tickets for something other than the default principal? use -n. heads up: -z and -Z are mutually exclusive, you cannot have both. 🚫
  • -Z — don't copy any tickets from the source cache to the target cache. just make a fresh target cache, where the cache's default principal name is initialized to the target principal name. and yes: -Z and -z are mutually exclusive too. 🚫
  • -q — suppress the printing of status messages. quiet mode, stealth mode, no yapping 🤫

🎟️ Ticket granting ticket options

  • -l lifetime -r time -p -P -f -F — these TGT options only apply to the case where there are no appropriate tickets in the cache to authenticate the source user. in that case, if ksu is configured to prompt users for a Kerberos password (GET_TGT_VIA_PASSWD is defined), the ticket granting ticket options you specified get used when getting a TGT from the Kerberos server. 🔑
  • -l lifetime — (time duration string) specifies the lifetime to request for the ticket. don't specify it and the default ticket lifetime (12 hours) is used instead.
  • -r time — (time duration string) says the renewable option should be requested for the ticket, and sets the desired total lifetime of the ticket.
  • -p — says the proxiable option should be requested for the ticket.
  • -P — says the proxiable option should not be requested for the ticket, even if the default config is to ask for proxiable tickets.
  • -f — says the forwardable option should be requested for the ticket.
  • -F — says the forwardable option should not be requested for the ticket, even if the default config is to ask for forwardable tickets.
  • -e command [args ...] — ksu proceeds exactly the same as if it was invoked without -e, 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

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 does not exist, authorization fails. otherwise, ~target_user/.k5users must have an appropriate entry for the target principal to get authorized.

📄 the .k5users file format

a single principal entry on each line, which may be followed by a list of commands that the principal is authorized to execute. a principal name followed by a * means that user is authorized to execute any command. so 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 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 (the * entry), then the 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 get passed to the shell, so all options intended for ksu must come before -a. order matters bestie 🫶

the -a option can be used to simulate the -e option if used like this:

-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 gets prompted for a Kerberos password. that password is then used to get a ticket granting ticket from the Kerberos server. the danger of configuring ksu with this macro is that if the source user is logged in remotely and does not have a secure channel, the password may get exposed. ⚠️ like, fr, read that twice.
  • PRINC_LOOK_AHEAD — during resolution of the default principal name, PRINC_LOOK_AHEAD lets ksu find principal names in the .k5users file as described in the OPTIONS section (see the -n option).
  • CMD_PATH — specifies a list of directories containing programs that users are authorized to execute (via the .k5users file).
  • HAVE_GETUSERSHELL — if the source user is non-root, ksu insists that the target user's shell being 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 like 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. bye bye expired tickets 🧹

👑 AUTHOR OF KSU

GENNADY (ARI) MEDVINSKY

🌍 ENVIRONMENT

see kerberos for a description of Kerberos environment variables.

👀 SEE ALSO

kerberos, kinit

✍️ AUTHOR

MIT

1985-2025, MIT

and that's the whole page bestie, you ate it 🎀 this was MIT Kerberos version 1.22.1, page KSU(1) — go forth and authenticate responsibly, mwah 💖✨

📦 where this page comes from