diff options
| -rw-r--r-- | README.md | 13 | ||||
| -rw-r--r-- | docs/README.kiosk | 817 | ||||
| -rw-r--r-- | docs/options.md | 93 | ||||
| -rw-r--r-- | src/core/kauthorized.cpp | 10 | ||||
| -rw-r--r-- | src/core/kauthorized.h | 99 |
5 files changed, 190 insertions, 842 deletions
@@ -9,10 +9,13 @@ KConfigCore and KConfigGui. KConfigCore provides access to the configuration files themselves. It features: -- centralized definition: define your configuration in an XML file and use -`kconfig_compiler` to generate classes to read and write configuration entries. - -- lock-down (kiosk) support. +- Code generation: describe your configuration in an XML file, and use + `kconfig_compiler to generate classes that read and write configuration + entries. +- Cascading configuration files (global settings overridden by local settings). +- Optional shell expansion support (see [docs/options.md](@ref options)). +- The ability to lock down configuration options (see + [docs/options.md](@ref options)). KConfigGui provides a way to hook widgets to the configuration so that they are automatically initialized from the configuration and automatically propagate @@ -22,5 +25,5 @@ their changes to their respective configuration files. - Home page: <https://projects.kde.org/projects/frameworks/kconfig> - Mailing list: <https://mail.kde.org/mailman/listinfo/kde-frameworks-devel> -- IRC channel: #kde-devel on Freenode +- IRC channel: \#kde-devel on Freenode - Git repository: <https://projects.kde.org/projects/frameworks/kconfig/repository> diff --git a/docs/README.kiosk b/docs/README.kiosk deleted file mode 100644 index b89f731c..00000000 --- a/docs/README.kiosk +++ /dev/null @@ -1,817 +0,0 @@ -In KDE-3 a kiosk-framework has been 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 KDE -================================== - -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 were located under $KDEDIR and user- -specific resources were 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/kde5rc 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. KDE 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 KDE-3, configuration entries can be marked "immutable". When a -configuration entry is immutable it means that configuration files that are -read later will not be able to override its value. Immutable entries cannot -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. - -To make the configuration file of Dolphin immutable one could for -example use the commands below. - -Example: -chown root.root /home/user/.kde/share/config/dolphinrc -chmod 644 /home/user/.kde/share/config/dolphinrc - -If you do this, the user will be warned that the configuration file is not -writable. Since you will normally not want that, you can add the following -two lines to the application's configuration file (or to kdeglobals to -disable the warning for all applications): - -[KDE Action Restrictions] -warn_unwritable_config=true - -Note that the above example is not fool-proof, the user can potentially still -rename either the root-owned dolphinrc file or any of the directories in -the path to another name and create a new dolphinrc _with_ write-access. - -KDE Action Restrictions -======================= - -Most functionality within KDE is coupled to so called actions. For example when a user -selects the File->Open option in the menubar of a KDE application, the "file_open" -action is activated. Likewise, toolbar icons are usually also coupled to actions. KDE -makes it possible to disable functionality by restricting specific actions. By restricting the -"file_open" action for example, the corresponding entry in the menubar and the corresponding icon on -the toolbar, if any, will disappear. - -To restrict access to function the kdeglobals file should contain the -group "[KDE Action Restrictions]", each action can then be 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/bookmarks // See note below -action/bookmark_add -action/bookmark_edit -action/tools_spelling -action/options_show_menubar -action/options_show_toolbar // See note below -action/options_show_statusbar -action/options_save_options -action/options_configure -action/options_configure_keybinding -action/options_configure_toolbars -action/options_configure_notifications -action/help // See note below -action/help_contents -action/help_whats_this -action/help_report_bug -action/help_about_app -action/help_about_kde -action/fullscreen - -Actions in the KDE File Dialog: -action/home // Go to home directory -action/up // Go to parent directory -action/back // Go to previous directory -action/forward // Go to next directory -action/reload // Reload directory -action/mkdir // Create new directory -action/toggleSpeedbar // Show/hide sidebar -action/sorting menu // Sorting options -action/short view // Select short view -action/detailed view // Select detailed view -action/show hidden // Show/hide hidden files -action/preview // Show/hide preview -action/separate dirs // Show/hide separate directories - - -Konqueror & KDesktop related: -action/editfiletype -action/properties -action/openwith -action/openintab -action/kdesktop_rmb // RMB menu, see note below -action/iconview_preview -action/sharefile // File sharing, see note below -action/sendURL // Send Link Address -action/sendPage // Send File -action/devnew // Create New -> Device -action/incIconSize // Increase icon size -action/decIconSize // Decrease icon size -action/go // Entire go menu -action/configdesktop // Configure desktop in RMB menu, see also Control Module Restrictions -action/executeshellcommand // In Konqueror Tools menu, see also shell_access -action/show_dot // Show Hidden Files, see note below - - -Kicker related: -action/kicker_rmb // RMB menu -action/menuedit - - -KWin related: -action/kwin_rmb // RMB window context menu - -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/zmodem_upload -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 -action/toggle_bidi - - - -Notes: -* action/options_show_toolbar will also disable the "Toolbars" submenu - if present. -* action/bookmarks also disables action/bookmark_add and action/bookmark_edit -* action/help is not yet fully implemented -* action/kdesktop_rmb disables the RMB menu but some actions may still be accesible - via keyboard shortcuts: cut/copy/rename/trash/delete -* action/iconview_preview disables the option to toggle previews on or off - in icon mode but the actual preview settings remains unaffected. - To disable previews you also need to add the following lines to - konqiconviewrc: - [Settings] - PreviewsEnabled[$i]=false -* action/show_dot disables the option to toggle showing hidden files, the actual - setting remains unaffected. - To disable showing hidden files, add the following lines to konqiconviewrc: - [Settings] - ShowDotFiles[$i]=false -* action/sharefile disables file sharing from the UI, but you may also want - to disable filesharing altogether. - - -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 qdbus command: - -qdbus org.kde.myapp-id | grep actions | cut -d '/' -f 4,5 - -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 disable all application entries that require root access. - - -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/properties - - disables the button to change printer properties or to add a new printer. - -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, print/options - and print/properties. - -print/dialog - - disables the complete print dialog. Selecting the print option will - immediately print the selected document using default settings. - Make sure that a system wide default printer has been selected. - No application specific settings are honored. - -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 and - $XDGDIR/applications - * 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. - "apps" - To restrict the KDE menu. - "xdgdata-apps" - 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. - -start_new_session - - defines whether the user may start a second X session. - See also the kdm configuration. - -switch_user - - defines whether user switching via kdm is allowed - -skip_drm - - defines if the user may omit DRM checking. - Currently only used by kpdf - -Screensaver related: -opengl_screensavers - - defines whether OpenGL screensavers are allowed to be used. - -manipulatescreen_screensavers - - defines whether screensavers that manipulate an image of the screen - (e.g. moving chunks of the screen around) are allowed to be used. - -When configuration files are marked immutable in whole or in part the user will no -longer be able to make permanent changes to the settings that have been marked -immutable. Ideally the application will recognize this and will no longer offer the -user the possibility to change these settings. Unfortunately not all applications -support this at the moment. It's therefor possible that the user will still be -presented with an option in the user interface to change a setting that is -immutable, changes made this way will not be saved though. In some cases the -user may be able to use the changed setting till the application terminates, in -other cases the changed setting will simply be ignored and the application will -continue to work with the immutable setting. - -The following applications currently detect when their configuration files have been -marked immutable and adjust their user interface accordingly: - -* 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. - -* kcalc - By marking the kcalcrc config file as immutable, the "Configure" button -will not be shown - -Application .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 has been authorized. If multiple actions are listed -they should be separated by commas (','). So if the .desktop file of an application -lists one or more actions this way and the user has no authorization for one -of these actions then the application will not appear in the KDE menu and will not -be used by KDE for opening files. - -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. - -KDE 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: -redirect - e.g. a html-page obtained via HTTP could redirect itself to file:/path/some-file. This - is disabled by default but could be explicitly enabled for a specific HTTP host. - This also applies to links contained in html documents. - Example: rule_1=redirect,http,myhost.acme.com,,file,,,true - -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. - -open - This controls which files can be opened by the user in applications. It also - affects where users can save files. To only allow a user to open the files - in his own home directory one could use: - rule_1=open,,,,file,,,false - rule_2=open,,,,file,,$HOME,true - rule_3=open,,,,file,,$TMP,true - Note that with the above, users would still be able to open files from - the internet. Note that the user is also given access to $TMP in order to - ensure correct operation of KDE applications. $TMP is replaced with the - temporary directory that KDE uses for this user. - -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". - - -KDE 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/konsole and users can add additional profiles by -installing files in $KDEHOME/share/konsole. - -KDE Resource Restrictions make it possible to restrict the lookup of files -to directories outside of $KDEHOME only. - -The following resources are defined: - -autostart - share/autostart -data - share -html - share/doc/HTML -icon - share/icon -config - share/config -pixmap - share/pixmaps -apps - share/applnk -xdgdata-apps - share/applications -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 - -See http://api.kde.org/4.x-api/kdelibs-apidocs/kdecore/html/classKStandardDirs.html -for a more up-to-date list of resources. - -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 - - -Control Module Restrictions -=========================== - -It is possible to restrict access to particular control modules. -Although it is possible to remove control modules from the Control -Center by editing the menu structure, such modules will then still -be available to applications. A better way is to use the control -module restrictions offered by KIOSK: - -[KDE Control Module Restrictions][$i] -<menu-id>=false - -Some example menu-ids are: - -kde-display.desktop -kde-proxy.desktop -kde-screensaver.desktop - -See also kcmshell --list for a list of all the base names. - -Expansion of environment variables in KDE config files. -======================================================= - -Since KDE-3.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. -=================================== - -Since KDE-3.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) - - -KDE Kiosk Application API -========================== - -Three new methods have been added to KApplication: - -- bool authorize(QString action); // Generic actions -- bool authorizeKAction(QString action); // For KActions exclusively -- bool authorizeURLAction(QString, referringURL, destinationURL) // URL Handling - -Automatic Logout -================ - -Since KDE 3.4 it is possible to automatically logout users that have been idle -for a certain period of time. - -WARNING: Be careful with this option, logging out a user may result in dataloss! - -In kdesktoprc you can use the following entry to enable automatic logout: - -[ScreenSaver] -AutoLogout=true -AutoLogoutTimeout=600 - -The AutoLogoutTimeout is the time in seconds that the user has to be idle before -his session is logged out. - - -Users can be associated with Profile(s) -======================================= - -A user can be associated with one or more profiles. A profile indicates a -configuration set that applies to a group of users. Each profile has a name -to identify it. If a user is associated with more than one profile then the -order of the two profiles is important. Settings associated with one profile -could override the settings in the other profile, depending on the order. - - -Mapping profiles to users -========================= - -A mapping file determines which profile(s) should be used for which user. -The mapping file can be configured in /etc/kde5rc in the [Directories] group: - - [Directories] - userProfileMapFile=/etc/kde-user-profile - -Profiles can be mapped to individual users based on username, or profiles can -be mapped to groups of users based on the UNIX group(s) the users are part of. -(See man 1 groups) - - -Mapping profiles to individual users -==================================== - -The mapping file can contain a [Users] section for mapping profiles to -an individual user. The [Users] section contains the user's account name -followed by one or more profiles as follow: - - [Users] - bastian=developer - adrians=developer,packager - -The above example assigns to user "bastian" the profile "developer". To user -"adrians" it assigns the two profiles "developer" and "packager". The order -in which the profiles are listed makes a difference, settings in earlier -profiles overrule settings in profiles that are listed after it. In the above -case of user "adrians", wherever the "developer" and "packager" profiles contain -conflicting settings, the settings of the "developer" profile will take precedent. - -If a user has an entry under the [Users] section, this entry will determine all -profiles that are applicable to the user. The user will not be assigned any -additional profiles based on the groups the user is part of. - -Mapping profiles to user groups -=============================== - -If a user has no entry under the [Users] section in the mapping file, the profiles -that are applicable to the user will be based on the UNIX group(s) the user is -part of. - -The groups and the order in which the groups are considered is determined by -the following entry in the [General] section of the mapping file: - - [General] - groups=pkgs,devel,bofh - -Each of these groups should have an entry under the [Groups] section that defines -which profile(s) belongs to that group. This looks as follows: - - [Groups] - pkgs=packager - devel=developer - bofh=admin,packager,developer - -For each group that a user is part of, the corresponding profile(s) are used. The -order in which the groups are listed in the "groups" entry, determines the resulting -order of all the applicable profiles. If multiple profiles are applicable to a -particular user and a profile contains settings that conflict with settings in -another profile then the settings in the earlier listed profile take precedent. - -So if, based on the example above, a user is part of the "pkgs" group then the -"packager" profile will be used for that user. If the user is part of the "devel" -group then the "developer" profile will be used. Users that are part of the "bofh" -group will use the "admin", "packager" as well as the "developer" profile. In case -of conflict, settings in the "admin" profile will take precedent over settings -in the "packager" or "developer" profiles. - -If the user is part of both the "pkgs" and "devel" groups, then both the "packager" -and "developer" profiles will be used. In case of conflicting settings between the -two profiles, the "packager" profile will take precedent because the "pkgs" group -associated with the profile was listed before the "devel" group. - -The "groups" command can be used to see to which groups a user belongs: - - > groups coolo - coolo : users uucp dialout audio video cdrecording devel - -Note that in general only a few groups will have profiles associated with them. -In the example above only the "devel" group has a profile associated with it, -the other groups do not and will be ignored. - -If there is no profile defined for any of the groups that the user is in, the -user will be assigned the "default" profile. - - -The Profile determines the directory prefixes -============================================= - -The global KDE configuration file (e.g. kdeglobals or /etc/kde5rc) can -contain config-groups that are associated with a certain user profile. -Such a config-group is treated similar as the [Directories] config-group. - -The name of a such config-group is [Directories-<ProfileName>] - - -Integration with KIOSK Admin Tool -================================= - -The KIOSK Admin Tool uses /etc/kde5rc as source for all its profile -information. For this it uses the following keys in the -[Directories-<ProfileName>] config-group: - - # Short text describing this profile - ProfileDescription= - - # Files will be installed with the uid of this user - ProfileInstallUser= - -The KIOSK Admin Tool uses the first directory from the prefixes= entry -as default installation directory for this profile. - - -Default setting as example -========================== - -The following snipped could be added to /etc/kde5rc to define a "default" profile: - - [Directories-default] - ProfileDescription=Default profile - ProfileDescription[de]=Defaultprofiel - ProfileInstallUser=root - prefixes=/var/run/kde-profile/default - diff --git a/docs/options.md b/docs/options.md new file mode 100644 index 00000000..c7a6c061 --- /dev/null +++ b/docs/options.md @@ -0,0 +1,93 @@ +KConfig Entry Options {#options} +===================== + +KConfig provides various options that can alter how it interprets configuration +entries on a per-entry, per-group or per-file basis. Note that these are not +supported by other configuration frameworks, and so should not be used in files +that are intended to be used by applications that do not use KConfig (such as +application desktop files). + + +Immutable Entries +----------------- + +KConfig's cadcading configuration mechanism usually causes values from earlier, +"global" configuration files to be overridden by later, "local" ones. +Typically, the system administrator might set global defaults, and a user might +override them in their local configuration files. + +However, KConfig provides a way to lock down configuration values, so that the +global settings override the local ones. This allows system administrators to +restrict the values a user can set for an entry, group of entries or an entire +configuration file. + +This is important for Kiosk authorization (see the KAuthorized namespace), +which allows parts of the user interface to be locked down. + +Configuration entries can be marked as immutable with the `$i` option. This can +be done on a per-entry basis: + + [MyGroup] + someKey[$i]=42 + +on a per-group basis (which will prevent any attempts to modify entries in the +group at all in later files): + + [MyGroup][$i] + someKey=42 + +or for an entire file by putting `[$i]` at the start of the file: + + [$i] + [MyGroup] + someKey=42 + [MyOtherGroup] + someOtherKey=11 + +Once this is done, the immutable entries or groups cannot be overridden by later +files of the same name (and, if the file is immutable, later files will be +ignored entirely). + +Note that a similar effect to file immutability can be acheived by using file +system permissions to prevent the user from writing to their local versions of +the configuration file, although (since this is normally a setup error), the +user will be warned that the configuration file is not writable. This warning +can be supressed by adding the following setting to either the relevant +configuration file or the `kdeglobals` file: + + [General] + warn_unwritable_config=true + +However, using file system permissions like this can potentially be circumvented +by the user if they have write access to the containing directory or can modify +environment variables (and `XDG_CONFIG_HOME` in particular). + + + +Shell Expansion +--------------- + +If an entry is marked with `$e`, environment variables and shell commands will +be expanded. + + Name[$e]=$USER + Host[$e]=$(hostname) + +When the "Name" entry is read `$USER` will be replaced with the value of the +`$USER` environment variable, and `$(hostname)` will be replaced with the output +of the `hostname` command. + +Note that the application will replace `$USER` and `$(hostname)` with their +respective expanded values after saving. To prevent this combine the `$e` option +with `$i` (immmutable) option. For example: + + Name[$ei]=$USER + +This 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 for environment variables is also supported: + + Name[$ei]=${USER} + + diff --git a/src/core/kauthorized.cpp b/src/core/kauthorized.cpp index c9b14f50..4280524d 100644 --- a/src/core/kauthorized.cpp +++ b/src/core/kauthorized.cpp @@ -340,7 +340,10 @@ static void initUrlActionRestrictions() namespace KAuthorized { -// Called by KAuthorized::allowUrlAction in KIO +/** + * Helper for KAuthorized::allowUrlAction in KIO + * @private + */ KCONFIGCORE_EXPORT void allowUrlActionInternal(const QString &action, const QUrl &_baseURL, const QUrl &_destURL) { MY_D @@ -359,7 +362,10 @@ KCONFIGCORE_EXPORT void allowUrlActionInternal(const QString &action, const QUrl _destURL.scheme(), _destURL.host(), destPath, true)); } -// Called by KAuthorized::authorizeUrlAction in KIO +/** + * Helper for KAuthorized::authorizeUrlAction in KIO + * @private + */ KCONFIGCORE_EXPORT bool authorizeUrlActionInternal(const QString &action, const QUrl &_baseURL, const QUrl &_destURL, const QString &baseClass, const QString &destClass) { MY_D diff --git a/src/core/kauthorized.h b/src/core/kauthorized.h index 45dd8284..d0988234 100644 --- a/src/core/kauthorized.h +++ b/src/core/kauthorized.h @@ -28,43 +28,106 @@ class QString; class QStringList; /** -* Kiosk authorization framework +* The functions in this namespace provide the core of the Kiosk action +* restriction system; the KIO and KXMLGui frameworks build on this. * -* Core functionality, see kauthorized.h for authorizeUrlAction. +* The relevant settings are read from the application's KSharedConfig +* instance, so actions can be disabled on a per-application or global +* basis (by using the kdeglobals file). */ namespace KAuthorized { /** - * Returns whether a certain action is authorized - * @param genericAction The name of a generic action - * @return true if the action is authorized - * @todo what are the generic actions? + * Returns whether the user is permitted to perform a certain action. + * + * All settings are read from the "[KDE Action Restrictions]" group. + * For example, if kdeglobals contains + * @verbatim + [KDE Action Restrictions][$i] + shell_access=false + @endverbatim + * then + * @code + * KAuthorized::authorize("shell_access"); + * @endcode + * will return @c false. + * + * This method is intended for actions that do not necessarily have a + * one-to-one correspondence with a menu or toolbar item (ie: a KAction + * in a KXMLGui application). "shell_access" is an example of such a + * "generic" action. + * + * The convention for actions like "File->New" is to prepend the action + * name with "action/", for example "action/file_new". This is what + * authorizeKAction() does. + * + * @param action The name of the action. + * @return @c true if the action is authorized, @c false + * otherwise. + * + * @see authorizeKAction() */ -KCONFIGCORE_EXPORT bool authorize(const QString &genericAction); +KCONFIGCORE_EXPORT bool authorize(const QString &action); /** - * Returns whether a certain KAction is authorized. + * Returns whether the user is permitted to perform a certain action. + * + * This behaves like authorize(), except that "action/" is prepended to + * @p action. So if kdeglobals contains + * @verbatim + [KDE Action Restrictions][$i] + action/file_new=false + @endverbatim + * then + * @code + * KAuthorized::authorizeKAction("file_new"); + * @endcode + * will return @c false. * - * @param action The name of a KAction action. The name is prepended - * with "action/" before being passed to authorize() - * @return true if the KAction is authorized + * KXMLGui-based applications should not normally need to call this + * function, as KActionCollection will do it automatically. + * + * @param action The name of a KAction action. + * @return @c true if the KAction is authorized, @c false + * otherwise. + * + * @see authorize() */ KCONFIGCORE_EXPORT bool authorizeKAction(const QString &action); /** - * Returns whether access to a certain control module is authorized. + * Returns whether the user is permitted to use a certain control + * module. + * + * All settings are read from the "[KDE Control Module Restrictions]" + * group. For example, if kdeglobals contains + * @verbatim + [KDE Control Module Restrictions][$i] + desktop-settings.desktop=false + @endverbatim + * then + * @code + * KAuthorized::authorizeControlModule("desktop-settings.desktop"); + * @endcode + * will return @c false. * - * @param menuId identifying the control module, e.g. kde-mouse.desktop - * @return true if access to the module is authorized, false otherwise. + * @param menuId The desktop menu ID for the control module. + * @return @c true if access to the module is authorized, + * @c false otherwise. + * + * @see authorizeControlModules() */ KCONFIGCORE_EXPORT bool authorizeControlModule(const QString &menuId); /** - * Returns which control modules from a given list are authorized for access. + * Determines which control modules from a list the user is permitted to + * use. + * + * @param menuIds A list of desktop menu IDs for control modules. + * @return The entries in @p menuIds for which + * authorizeControlModule() returns @c true. * - * @param menuIds list of menu-ids of control modules; - * an example of a menu-id is kde-mouse.desktop. - * @return Those control modules for which access has been authorized. + * @see authorizeControlModule() */ KCONFIGCORE_EXPORT QStringList authorizeControlModules(const QStringList &menuIds); |