File indexing completed on 2024-07-21 03:41:09

0001 /*
0002     This file is part of the KDE libraries
0003     SPDX-FileCopyrightText: 1997 Matthias Kalle Dalheimer <kalle@kde.org>
0004     SPDX-FileCopyrightText: 1998, 1999 Waldo Bastian <bastian@kde.org>
0005 
0006     SPDX-License-Identifier: LGPL-2.0-or-later
0007 */
0008 
0009 #ifndef KURLAUTHORIZED_H
0010 #define KURLAUTHORIZED_H
0011 
0012 #include "kiocore_export.h"
0013 
0014 #include <KAuthorized>
0015 
0016 class QUrl;
0017 class QString;
0018 
0019 /**
0020  * The functions in this namespace allow actions to be restricted based
0021  * on the URL they operate on (see the KAuthorized namespace in
0022  * KConfig).
0023  *
0024  * As with KAuthorized functions, the relevant settings are read from
0025  * the application's KSharedConfig instance, so actions can be disabled
0026  * on a per-application or global basis (by using the kdeglobals file).
0027  *
0028  * URLs can be matched based on protocol, host and path, and the
0029  * referring URL can be taken into account.
0030  *
0031  * URL-based restrictions are recorded using this syntax:
0032  * @verbatim
0033    [KDE URL Restrictions]
0034    rule_count=<N>
0035    rule_1=<action>,<referingURL_protocol>,<referingURL_host>,<referingURL_path>,<URL_protocol>,<URL_host>,<URL_path>,<enabled>
0036    ...
0037    rule_N=<action>,<referingURL_protocol>,<referingURL_host>,<referingURL_path>,<URL_protocol>,<URL_host>,<URL_path>,<enabled>
0038    @endverbatim
0039  *
0040  * The following standard actions are defined:
0041  *
0042  * - redirect: A common example is a web page redirecting to another web
0043  *             page.  By default, internet protocols are not permitted
0044  *             to redirect to the "file" protocol, but you could
0045  *             override this for a specific host, for example:
0046  *             @verbatim
0047                [KDE URL Restrictions]
0048                rule_count=1
0049                rule_1=redirect,http,myhost.example.com,,file,,,true
0050                @endverbatim
0051  * - list:     Determines whether a URL can be browsed, in an "open" or
0052  *             "save" dialog, for example.  If a user should only be
0053  *             able to browse files under home directory one could use:
0054  *             @verbatim
0055                [KDE URL Restrictions]
0056                rule_count=2
0057                rule_1=list,,,,file,,,false
0058                rule_2=list,,,,file,,$HOME,true
0059                @endverbatim
0060  *             The first rule disables browsing any directories on the
0061  *             local filesystem. The second rule then enables browsing
0062  *             the users home directory.
0063  * - open:     This controls which files can be opened by the user in
0064  *             applications. It also affects where users can save files.
0065  *             To only allow a user to open the files in his own home
0066  *             directory one could use:
0067  *             @verbatim
0068                [KDE URL Restrictions]
0069                rule_count=3
0070                  rule_1=open,,,,file,,,false
0071                  rule_2=open,,,,file,,$HOME,true
0072                  rule_3=open,,,,file,,$TMP,true
0073                @endverbatim
0074  *             Note that with the above, users would still be able to
0075  *             open files from the internet. Note also that the user is
0076  *             also given access to $TMP in order to ensure correct
0077  *             operation of KDE applications. $TMP is replaced with the
0078  *             temporary directory that KDE uses for this user.
0079  * - link:     Determines whether a URL can be linked to.
0080  *
0081  * Some remarks:
0082  * - empty entries match everything
0083  * - host names may start with a wildcard, e.g. "*.acme.com"
0084  * - a protocol also matches similar protocols that start with the same name,
0085  *   e.g. "http" matches both http and https. You can use "http!" if you only want to
0086  *   match http (and not https)
0087  * - specifying a path matches all URLs that start with the same path. For better results
0088  *   you should not include a trailing slash. If you want to specify one specific path, you can
0089  *   add an exclamation mark. E.g. "/srv" matches both "/srv" and "/srv/www" but "/srv!" only
0090  *   matches "/srv" and not "/srv/www".
0091 */
0092 namespace KUrlAuthorized
0093 {
0094 /**
0095  * Returns whether a certain URL related action is authorized.
0096  *
0097  * @param action   The name of the action, typically one of "list",
0098  *                 "link", "open" or "redirect".
0099  * @param baseUrl  The url where the action originates from.
0100  * @param destUrl  The object of the action.
0101  * @return         @c true if the action is authorized, @c false
0102  *                 otherwise.
0103  *
0104  * @see allowUrlAction()
0105  * @since 5.0
0106  */
0107 KIOCORE_EXPORT bool authorizeUrlAction(const QString &action, const QUrl &baseUrl, const QUrl &destUrl);
0108 
0109 /**
0110  * Override Kiosk restrictions to allow a given URL action.
0111  *
0112  * This can be useful if your application needs to ensure access to an
0113  * application-specific directory that may otherwise be subject to Kiosk
0114  * restrictions.
0115  *
0116  * @param action   The name of the action.
0117  * @param baseUrl  The url where the action originates from.
0118  * @param destUrl  The object of the action.
0119  *
0120  * @see authorizeUrlAction()
0121  * @since 5.0
0122  */
0123 KIOCORE_EXPORT void allowUrlAction(const QString &action, const QUrl &baseUrl, const QUrl &destUrl);
0124 
0125 }
0126 
0127 #endif