In KDE3 a kiosk-framework gets introduced. 

One of the driving forces behind KDE is to put the user in control and
give him or her a large amount of possibilities to adjust KDE to his or her 
liking. However, in some situations it is required to reduce the possibilities
of KDE, e.g. because the system is to be used for one or more specific 
dedicated tasks only.

The kiosk-framework provides an easy way to disable certain features within
KDE to create a more controlled environment.

KDE's kiosk-framework builds on KDE's configuration framework and adds a
simple application API that applications can query to get authorisation
for certain operations.

The KDE kiosk-framework should be used IN ADDITION to the standard UNIX
security measures. 

The configuration framework in KDE3
===================================

Since the very beginning KDE makes use of file-hierarchy to store resources
for its applications. Resources range from icons, wallpapers, fonts to 
sounds, menu-descriptions and configuration files. 

In KDE1 there were two locations were resources could be located: the 
resources provided by the system where located under $KDEDIR and user-
specific resources where located under $HOME/.kde.

In KDE2 resource management has been largely abstracted by the introduction
of the KStandardDirs class and has become much more flexible. The user /
administrator can now specify a variable number of locations where resources
can be found. A list of locations can either be specified via $KDEDIRS
(notice the extra 'S'), via /etc/kderc and even via the kdeglobals config 
file. The location where user-specific resources can be found can be
set with $KDEHOME (The default is $HOME/.kde). Changes made by the user
are always written back to $KDEHOME.

Both KDE1 and KDE2 feature so called "cascading configuration files": There
can be multiple configuration files with the same name in the various 
locations for (config) resources, when that is the case, the information of 
all these configuration files is combined on a key by key basis. If the same
key (within a certain group) is defined in more than one place, the value
of the key for the config file that was read last will override any previously
read values. Configuration files under $KDEHOME are always read last. This
ensures that after a configuration entry is written, the same value wil be
read back.

In KDE3 two important changes have been made:

* Default values are no longer written.
When a configuration file in a location other than $KDEHOME defines a value 
for a key and the application subsequently writes out a new configuration file
to $KDEHOME, that configuration file will only contain an entry for the key
if its value differs from the value read from the other file.

This counters the problem that changing default configuration files under 
$KDEDIR would not take effect for users, since these users would most likely
have their own copy of these settings under $KDEHOME. KDE3 will make sure 
not to copy these settings so changes made under $KDEDIR will affect all users
that haven't explicitly changed the affected settings to something else.

* Configuration entries can be marked "immutable".
Starting with KDE3, configuration entries can be marked "immutable". When a
configuration entry is immutable it means that configurations files that are
read later will not be able to override its value. Immutable entries can not
be changed via KConfig and if the entry is present under $KDEHOME it will 
be ignored.

Entries can be marked immutable on 4 different levels:

- On an entry by entry basis by appending "[$i]" after the key.

Example:
[MyGroup]
someKey[$i]=42

- On a group by group basis by appending "[$i]" after the group. All entries
specified in the group will be marked immutable and no new entries can be
added to the group.

Example:
[MyGroup][$i]
someKey=42

- On a file by file basis by starting the file with [$i].

Example:
[$i]
[MyGroup]
someKey=42
[MyOtherGroup]
someOtherKey=11

- On a directory basis. [Not yet implemented]

- The filesystem can also be used to mark files immutable. If KDE does not 
have write-access to the user's version of a configuration file, the file
will be automatically considered immutable.

Example:
chown root.root /home/user/.kde/share/config/kickerrc
chmod 644 /home/user/.kde/share/config/kickerrc

Note that this example is not fool-proof, the user can potentially still 
rename either the root-owned kickerrc file or any of the directories in 
the path to another name and create a new kickerrc _with_ write-access.

KDE3 Kiosk Application API
==========================

Two new methods will be added to KApplication:

- bool authorize(QString action); // Generic actions
- bool authorizeKAction(QString action); // For KActions exclusively
- bool authorizeURLAction(QString, referringURL, destinationURL) // URL Handling

KDE3 Action Restrictions
========================

.desktop files can have an additional field "X-KDE-AuthorizeAction". If this
field is present the .desktop file is only considered if the action(s) 
mentioned in this field get(s) authorized. If multiple actions are listed
they should be seperated by commas (','). 

To restrict access to function the kdeglobals file should contain the 
group "[KDE Action Restrictions]", each action can then restricted by 
adding "<action>=false". E.g. to disable the action "shell_access" one 
would add:
[KDE Action Restrictions][$i]
shell_access=false

Actions that refer to menu and toolbar actions are prefixed with action/' the
following standard actions are defined:

action/file_new
action/file_open
action/file_open_recent
action/file_save
action/file_save_as
action/file_revert
action/file_close
action/file_print
action/file_print_preview
action/file_mail
action/file_quit
action/edit_undo
action/edit_redo
action/edit_cut
action/edit_copy
action/edit_paste
action/edit_select_all
action/edit_deselect
action/edit_find
action/edit_find_next
action/edit_find_last
action/edit_replace
action/view_actual_size
action/view_fit_to_page
action/view_fit_to_width
action/view_fit_to_height
action/view_zoom_in
action/view_zoom_out
action/view_zoom
action/view_redisplay
action/go_up
action/go_back
action/go_forward
action/go_home
action/go_previous
action/go_next
action/go_goto
action/go_goto_page
action/go_goto_line
action/go_first
action/go_last
action/bookmark_add
action/bookmark_edit
action/tools_spelling
action/options_show_menubar
action/options_show_toolbar
action/options_show_statusbar
action/options_save_options
action/options_configure_keybinding
action/options_configure_notifications
action/options_configure_toolbars
action/options_configure
action/help_contents
action/help_whats_this
action/help_report_bug
action/help_about_app
action/help_about_kde
action/fullscreen

Konqueror & KDesktop related:
action/editfiletype
action/properties
action/openwith
action/openintab
action/openintabfront

Kicker related:
action/kicker_rmb // RMB menu
action/menuedit

Konsole related:
action/konsole_rmb // RMB context menu

action/settings // Entire settings menu
action/show_menubar
action/show_toolbar
action/scrollbar
action/fullscreen
action/bell
action/font
action/keyboard
action/schema
action/size
action/history
action/save_default
action/save_sessions_profile
action/options_configure_notifications
action/options_configure_keybinding
action/options_configure

action/send_signal 
action/bookmarks
action/add_bookmark
action/edit_bookmarks
action/clear_terminal
action/reset_clear_terminal
action/find_history
action/find_next
action/find_previous
action/save_history
action/clear_history
action/clear_all_histories
action/detach_session
action/rename_session
action/monitor_activity
action/monitor_silence
action/send_input_to_all_sessions
action/close_session
action/new_session
action/activate_menu
action/list_sessions
action/move_session_left
action/move_session_right
action/previous_session
action/next_session
action/switch_to_session_1
action/switch_to_session_2
action/switch_to_session_3
action/switch_to_session_4
action/switch_to_session_5
action/switch_to_session_6
action/switch_to_session_7
action/switch_to_session_8
action/switch_to_session_9
action/switch_to_session_10
action/switch_to_session_11
action/switch_to_session_12
action/bigger_font
action/smaller_font



Notes:
* action/options_show_toolbar will also disable the "Toolbars" submenu
  if present.

Applications may use additional actions that they defined themselves.
You can get a list of the actions used by a certain applications by using the
following dcop command:

dcop <dcopid> qt objects | grep KActionCollection/ | cut -d '/' -f 3

or with

dcop <dcopid> <maindwindowid> actions


Actions that refer to applications that need to be run as a different user
are prefixed by user/ and identified by the username. For example:

user/root=false

will disables all application entries that require root access. 


The most important task is to define a managable number of actions that can be 
disabled. Actions should be defined in a generic way, "open konsole" would be
too specific, a better definition of an action would be "shell_access". 
It should be noted that such an action might affect KDE features which aren't
directly associated with "shell_access". There are various locations in the 
file system where creating a .desktop file would effectively allow the user to 
execute arbitrary commands. This raises the question whether such features 
should be disabled as part of the "shell_access" action or whether it should 
get its own action definition, e.g. "custom .desktop files".

Printing related action restrictions:

print/system
        - disables the option to select the printing system (backend). It is 
          recommended to  disable this option once the correct printing 
          system has been configured.

print/options
        - disables the button to select additional print options.

print/copies
        - disables the panel that allows users to make more than one copy.

print/selection
        - disables the options that allows selecting a (pseudo) printer or 
          change any of the printer properties. Make sure that a proper
          default printer has been selected before disabling this option.
          Disabling this option also disables print/system and print/options.

print/dialog
        - disables the complete print dialog. Selecting the print option will
          immediate print the selected document using default settings.
          Make sure that a system wide default printer has been selected.
          No application specific settings are honoured.

Other defined actions:

shell_access 
        - defines whether a shell suitable for entering random commands 
          may be started. This also determines whether the "Run Command"
          option (Alt-F2) can be used to run shell-commands and arbitrary  
          executables. Likewise, executables placed in the user's
          Autostart folder will no longer be executed. Applications can
          still be autostarted by placing .desktop files in the $KDEHOME/Autostart
          or $KDEDIR/share/autostart directory.
          See also run_desktop_files.

custom_config 
        - defines whether the --config command line option should be honored.
          The --config command line option can be used to circumvent 
          locked-down configuration files.

logout
        - defines whether the user will be able to logout from KDE.

lock_screen
        - defines whether the user will be able to lock the screen.

run_command
        - defines whether the "Run Command" (Alt-F2) option is available.

movable_toolbars
        - define whether toolbars may be moved around by the user.
          See also action/options_show_toolbar.

editable_desktop_icons
        - define whether icons on the desktop can be moved, renamed, 
          deleted or added. You might want to set the path for
          the Desktop to some read-only directory as well.
          (Instead of $HOME/Desktop)

run_desktop_files
        - defines whether users may execute desktop files that are not
          part of the default desktop, KDE menu, registered services and
          autostarting services.
          * The default desktop includes the files under 
            $KDEDIR/share/kdesktop/Desktop but _NOT_ the files under
            $HOME/Desktop. 
          * The KDE menu includes all files under $KDEDIR/share/applnk. 
          * Registered services includes all files under $KDEDIR/share/services. 
          * Autostarting services include all files under $KDEDIR/share/autostart 
            but _NOT_ the files under $KDEHOME/Autostart

          You probably also want to activate the following resource
          restictions:
          "appdata_kdesktop" - To restrict the default desktop.
          "applnk" - To restrict the KDE menu.
          "services" - To restrict registered services.
          "autostart" - To restrict autostarting services.
          Otherwise users can still execute .desktop files by placing them
          in e.g. $KDEHOME/share/kdesktop/Desktop

lineedit_text_completion
        - defines whether input lines should have the potential to remember 
          any previously entered data and make suggestions based on this 
          when typing. When a single account is shared by multiple people you
          may wish to disable this out of privacy concerns.

Another interesting question is what the exact scope of a certain action should
be. Looking at the "custom .desktop files" action there are two ways to prevent
the user from executing "custom .desktop files". The first way would be to
make use of unix file permissions to make it impossible for the user to
create .desktop files at e.g. the desktop. The second way would be to ignore,
at the KDE level, any .desktop files that are found under the users home
directory.


In addition KConfigBase (the baseclass of KConfig) has functions to query whether 
config options/groups or files are immutable. This can be used in applications to
disable configuration options when such options can't be changed anyway.


The following applications currently have support for this:


* kicker - By marking the kickerrc config file as immutable, the panel will be 
"locked down" and it will not be possible to make any changes to it.

* kdesktop - By marking the kdesktoprc config file as immutable, the desktop
will be "locked down" and it will no longer be possible to select
"Configure Desktop" from its menus.


IMPORTANT NOTE:
Changing restrictions may influence the data that is cached in the ksycoca
database. Since changes to .../share/config/kdeglobals do not trigger an
automatic ksycoca update you need to force an update manually.
To force an update of the ksycoca database touch the file 
.../share/services/update_ksycoca. This will force a user's sycoca database
to be rebuild the next time the user logs in.

KDE3 URL Restrictions
=====================

It is also possible to restrict URL related actions. The restriction framework 
can disable URL actions based on the action, the URL in question and in some cases 
the referring URL. URLs can be matched based on protocol, host and path.

The syntax for adding URL action restrictions to kdeglobals is as follows:

[KDE URL Restrictions]
rule_count=<N>
rule_1=<action>,<referingURL_protocol>,<referingURL_host>,<referingURL_path>,<URL_protocol>,<URL_host>,<URL_path>,<enabled>
...
rule_N=<action>,<referingURL_protocol>,<referingURL_host>,<referingURL_path>,<URL_protocol>,<URL_host>,<URL_path>,<enabled>

The following actions are supported:
list     - This controls which directories can be browsed with KDE's file-dialogs. If a user
           should only be able to browse files under home directory one could use:
              rule_1=list,,,,file,,,false
              rule_2=list,,,,file,,$HOME,true
           The first rule disables browing any directories on the local filesystem. The second rule
           then enables browsing the users home directory.

Some remarks:
* empty entries match everything
* host names may start with a wildcard, e.g. "*.acme.com"
* a protocol also matches similar protocols that start with the same name, 
  e.g. "http" matches both http and https. You can use "http!" if you only want to
  match http (and not https)
* specifying a path matches all URLs that start with the same path. For better results
  you should not include a trailing slash. If you want to specify one specific path, you can 
  add an exclamation mark. E.g. "/srv" matches both "/srv" and "/srv/www" but "/srv!" only
  matches "/srv" and not "/srv/www".


KDE3 Resource Restrictions
==========================
Most KDE applications make use of additional resource files that are typically
located in directories under $KDEDIR/share. By default KDE allows users to
override any of these resources by placing files in the same location 
under $KDEHOME/share. For example, Konsole stores profiles under 
$KDEDIR/share/apps/konsole and users can add additional profiles by 
installing files in $KDEHOME/share/apps/konsole.

KDE3 Resource Restrictions makes it possible to restrict the lookup of files
to directories outside of $KDEHOME only.

The following resources are defined:

data - share/apps
html - share/doc/HTML
icon - share/icon
config - share/config
pixmap - share/pixmaps
apps - share/applnk
sound - share/sounds
locale - share/locale
services - share/services
servicetypes - share/servicetypes
mime - share/mimelnk
wallpaper - share/wallpapers
templates - share/templates
exe - bin
lib - lib

For the purpose of resource restrictions there are two special resources:
all - covers all resources
data_<appname> - covers the sub section for <appname> in the data resource.

To restrict resources the kdeglobals file should contain the
group "[KDE Resource Restrictions]", each resource can then be restricted by
adding "<resource>=false". E.g. to restrict the "wallpaper" resource to 
$KDEDIR/share/wallpapers one would add:
[KDE Resource Restrictions][$i]
wallpaper=false

And to prevent a user from adding additional konsole profiles, one would add:
[KDE Resource Restrictions][$i]
data_konsole=false


Expansion of environment variables in KDE config files.
=======================================================

In KDE3.1 arbitrary entries in configuration files can contain environment
variables. In order to use this the entry must be marked with [$e]. 

Example:
Name[$e]=$USER

When the "Name" entry is read $USER will be replaced with the value of the
$USER environment variable. Note that the application will replace $USER
with the value of the environment variable after saving. To prevent this
combine the $e option with $i (immmutable) option.

Example:
Name[$ei]=$USER

The above will make that the "Name" entry will always return the value of
the $USER environment variable. The user will not be able to change this entry.

The following syntax is also supported:
Name[$ei]=${USER}


Shell Commands in KDE config files.
===================================

In KDE3.1 arbitrary entries in configuration files can contain shell 
commands. This way the value of a configuration entry can be determined
dynamically at runtime. In order to use this the entry must be marked 
with [$e]. 

Example:
Host[$e]=$(hostname)




