<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook V3.1-Based Variant V1.0//EN" [
  <!ENTITY kappname "&kdesu;" -- this only *seems* redundant -->
  <!ENTITY % addindex "IGNORE">
  <!ENTITY % English "INCLUDE">
  <!ENTITY % ents PUBLIC "-//KDE//ENTITIES Documentation V1.0//EN">
  %ents;
]>

<book lang="&language;">
<bookinfo>

<title>The &kdesu; handbook</title>

<authorgroup>
<author>
<firstname>Geert</firstname>
<surname>Jansen</surname>
<affiliation>
<address><email>g.t.jansen@stud.tue.nl</email></address>
</affiliation>
</author>

<othercredit role="reviewer">
<firstname>Lauri</firstname>
<surname>Watts</surname>
<affiliation>
<address><email>vampyr@atconnex.net</email></address>
</affiliation>
<contrib>Reviewer</contrib>
</othercredit>

</authorgroup>

<copyright>
<year>2000</year>
<holder>Geert Jansen</holder>
</copyright>

<legalnotice>&FDLNotice;</legalnotice>

<date>04/09/2000</date>
<releaseinfo>1.00.00</releaseinfo>


<abstract><para>&kdesu; is a graphical front end for the Unix
"<command>su</command>" command.</para></abstract>

<keywordset>
<keyword>KDE</keyword>
<keyword>su</keyword>
<keyword>password</keyword>
<keyword>root</keyword>
</keywordset>

</bookinfo>

<chapter id="Introduction">
<title>Introduction</title>

<para>Welcome to &kdesu;! &kdesu; is a graphical front end for the UNIX
"<command>su</command>" command for the K Desktop Environment. 
It allows you to run a program as different user by supplying the password for
that user. &kdesu; is an unprivileged program; it uses the system's
<command>su</command>.</para>

<para>KDE su has one additional feature: it can remember passwords for you. If
you are using this feature, you only need to enter the password once for each
command. See <xref linkend="sec-password-keeping"> for more information on this
and a security analysis.</para>

<para>This program is meant to be started from the command line or from
<filename>.desktop</filename> files. Although it asks for the root password
using a <abbrev>GUI</abbrev> dialog, I consider it to be more of a command line
&lt;-&gt; <abbrev>GUI</abbrev> glue instead of a pure <abbrev>GUI</abbrev>
program.</para>

</chapter>

<chapter id="installation">
<title>Installation</title>

<sect1 id="downloading">
<title>Downloading</title>

<para>&kdesu; is now in the KDE <abbrev>CVS</abbrev>, in kdebase. It should be
included in every (2.x) KDE distribution.  You can also obtain a KDE 1.x version
from my homepage at <ulink
url="ftp://skynet.stack.nl/pub/users/geertj/">ftp://skynet.stack.nl/pub/users/geertj/</ulink>.</para>

</sect1>

<sect1 id="compiling">
<title>Compiling</title>

<para>&kdesu; is in kdebase so either you already have it, or you'll get it when
you intall kdebase.</para>

<para>To compile the KDE 1.x version, use:</para>

<screen>
<prompt>$</prompt> <command>./configure</command>
<prompt>$</prompt> <command>make</command>
<prompt>$</prompt> <command>make <option>install</option></command>
</screen>

<para>You will have to execute the last step as root. The installation process
needs to be able to write to the system wide KDE directories.</para>

</sect1>
</chapter>

<chapter id="using-kdesu">
<title>Using &kdesu;</title>

<para>Usage of &kdesu; is easy. The syntax is like this:</para>

    <cmdsynopsis>
      <command>kdesu</command>
      <arg>USER</arg>
      <arg>-n</arg>
      <arg>-t</arg>
      <arg>-q</arg>
      <arg>-d</arg>
      <arg>-f <replaceable>FILE</replaceable></arg>
      <arg>-c <group>
	  <arg>
	  <replaceable>COMMAND</replaceable>
	  <arg><replaceable>ARG1</replaceable></arg>
	  <arg><replaceable>ARG2</replaceable></arg>
          <arg rep="repeat"><replaceable></replaceable></arg>
	 </arg>
	</group>
      </arg>
    </cmdsynopsis>

    <cmdsynopsis>
      <command>kdesu</command>
      <group>
	<arg>-v</arg>
	<arg>-h</arg>
	<arg>-s</arg>
      </group>
    </cmdsynopsis>

<para>The command line options are explained below.</para>

<variablelist>
<varlistentry>
<term><option>-c <replaceable>PROGRAM</replaceable></option></term>
<listitem><para>This specifies the program to run as root. It has to be passed
in one argument. So if, for example, you want to start a new file manager, you
would enter at the prompt: <userinput><command>kdesu <option>-c <replaceable>kfm
-sw</replaceable></option></command></userinput></para></listitem>
</varlistentry>
<varlistentry>
<term><option>-f <replaceable>FILE</replaceable></option></term>
<listitem><para>This option allow efficient use of &kdesu; in
<filename>.desktop</filename> files. It tells &kdesu; to examine the file
specified by <parameter>FILE</parameter>. If this file is writable by the
current user, &kdesu; will execute the command as the current user. If it is not
writable, the command is executed as user <parameter>USER</parameter> (defaults
to root).</para>
<para><parameter>FILE</parameter> is evaluated like this: if
<parameter>FILE</parameter> starts with a "/", it is taken as an absolute
filename. Otherwise, it is taken as the name of a global KDE configuration
file. For example: to configure the K display manager,
<application>kdm</application>, you could issue <command>kdesu <option>-c
kdmconfig -f kdmrc</option></command></para></listitem>
</varlistentry>
<varlistentry>
<term><option>-t</option></term>
<listitem><para>Enable terminal output. This disables password keeping. This is
largely for debugging purposes; if you want to run a console mode app, use the
standard "<command>su</command>" instead.</para> </listitem>
</varlistentry>
<varlistentry>
<term><option>-n</option></term>
<listitem><para>Do not keep the password. This disables the "<guilabel>keep
password</guilabel>" checkbox in the password dialog.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-q</option></term>
<listitem><para>Be quiet.</para></listitem>
<!-- Lauri: This could do with a little expansion.  quiet as in no screen -->
<!-- output, quiet as in no gui prompt for the password, or quiet as in no -->
<!-- beeping? -->
</varlistentry>

<varlistentry>
<term><option>-d</option></term>
<listitem><para>Show debug information.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-v</option></term>
<listitem><para>Print version information and exit.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-h</option></term>
<listitem><para>Print some help.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-s</option></term>
<listitem><para>Stop the kdesu daemon. See <xref
linkend="sec-password-keeping">.</para></listitem>
</varlistentry>
</variablelist>

</chapter>

<chapter id="Configuration">
<title>Configuration</title>

<para>&kdesu; comes with a control module named
<application>kcmkdesu</application>. You can find it in the <guimenu>K</guimenu>
menu under <menuchoice><guisubmenu>Settings</guisubmenu>
<guisubmenu>Applications</guisubmenu> <guimenuitem>KDE
su</guimenuitem></menuchoice>. You can change the following things:</para>

<variablelist>
<varlistentry>
<term><guilabel>Echo Mode</guilabel></term>
<listitem><para>This is how characters you type are echoed to the
screen. Possible choices are: one star per character, three stars or no echo at
all. The default is one star per character.</para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Keeping passwords</guilabel></term>
<listitem><para>You can instruct KDE su remember passwords you enter by checking
the "<guilabel>keep password</guilabel>" check box. If this checked, you can
enter a timeout value in the text field below it. This is the amount of time, in
minutes, that the password will be remembered. The default is not to remember
passwords.</para></listitem>
</varlistentry>
</variablelist>

</chapter>

<chapter id="Internals">
<title>Internals</title>

<sect1 id="x-authentication">
<title>X authentication</title>

<para>The program you execute will run under the root user id and will generally
have no authority to access your X display. KDE su gets around this by adding
an authentication cookie for your display to a temporary
<filename>.Xauthority</filename> file. After the command exits, this file is
removed. </para>

<para>If you don't use X cookies, you are on your own. &kdesu; will detect this
and will not add a cookie but you will have to make sure that root is allowed
to access to your display.</para>

</sect1>

<sect1 id="interface-to-su">
<title>Interface to <command>su</command></title>

<para>&kdesu; uses the sytem's "<command>su</command>" for acquiring
priviliges. In this section, I explain the details of how &kdesu; does
this. </para>

<para>Because some <command>su</command> implementations (<abbrev>i.e.</abbrev>
the one from Redhat) don't want to read the password from
<literal>stdin</literal>, &kdesu; creates a pty/tty pair and executes
"<command>su</command>" with it's standard filedescriptors connected to the
tty.</para>

<para>To execute the command the user selected, rather than an interactive
shell, &kdesu; uses the "<option>-c</option>" argument with
<command>su</command>. This argument is understood by every shell that I know of
so it should work portably. <command>Su</command> passes this
"<option>-c</option>" argument to the target user's shell, and the shell
executes the program. Example command: "<command>su <option>root -c
<replaceable>the_program</replaceable></option></command>".</para>

<para>Instead of executing the user command directly with <command>su</command>,
&kdesu; executes a little stub program called
<application>kdesu_stub</application>. This stub (running as the target user),
requests some information from &kdesu; over the pty/tty channel (the stub's stdin
and stdout) and then executes the user's program. The information passed over
is: the X display, an X authentication cookie (if available), the
<envar>PATH</envar> and the command to run. The reason why a stub program is
used is that the X cookie is private information and therefore cannot be passed
on the command line.</para>

</sect1>

<sect1 id="password-checking">
<title>Password Checking</title>

<para>&kdesu; will check the password you entered and gives an error message if it
is not correct. The checking is done by executing a test program:
<filename>/bin/true</filename>. If this succeeds, the password is assumed to be
correct.</para>

</sect1>

<sect1 id="sec-password-keeping">
<title>Password Keeping</title>

<para>For your comfort, &kdesu; implements a "keep password" feature. If you are
interested in security, you should read this paragraph.</para>

<para>Allowing &kdesu; to remember passwords opens up a (small) security hole
in your system. Obviously, KDE su does not allow anybody but your user id to
use the passwords, but, if done without caution, this would lowers root's security
level to that of a normal user (you). A hacker who breaks into your account,
would get root access. &kdesu; tries to prevent this. The security scheme it
uses is, in my opinion at least, reasonably safe and is explained here.</para>

<para>&kdesu; uses a daemon, called <application>kdesud</application>. The daemon
listens to a UNIX socket in <filename>/tmp</filename> for commands. The mode of
the socket is 0600 so that only your user id can connect to it. If password
keeping is enabled, &kdesu; executes commands through this daemon. It writes the
command and root's password to the socket and the daemon executes the command
using "<command>su</command>", as describe before. After this, the command and
the password are not thrown away. Instead, they are kept for a specified amount
of time. This is the timeout value from in the control module.  If another
request for the same command is coming within this time period, the client does
not have to supply the password. To keep hackers who broke into your account
from stealing passwords from the daemon (for example, by attaching a debugger),
the daemon is installed set-group-id nogroup. This should prevent all normal
users (including you) from getting passwords from the
<application>kdesud</application> process. Also, the daemon sets the
<envar>DISPLAY</envar> environment variable to the value it had when it was
started. The only thing a hacker can do is execute an application on your
display.</para>

<para>One weak spot in this scheme is that the programs you execute are probably
not written with security in mind (like setuid root programs). This means that
they might have buffer overruns or other problems and a hacker could exploit
those.</para>

<para>The use of the password keeping feature is a tradeoff between security and
comfort. I encourage you to think it over and decide for yourself if you want to
use it or not.</para>

</sect1>
</chapter>

<chapter id="Author">
<title>Author</title>

<para>&kdesu;</para>

<para>Copyright 2000 Geert Jansen</para>

<para>&kdesu; is written by Geert Jansen. It is somewhat based on Pietro Iglio's
&kdesu;, version 0.3. Pietro and I agreed that I will maintain this program in
the future.</para>

<para>The author can be reached through email at
<email>g.t.jansen@stud.tue.nl</email>.  Please report any bugs you find to me so
that I can fix them. If you have a suggestion, feel free to contact me.</para>

&underFDL;
&underArtisticLicense;

</chapter>
</book>
<!--
Local Variables:
mode: sgml
sgml-omittag: nil
sgml-shorttag: t
End:
-->
