1/*
2 This file is part of the KDE libraries
3 SPDX-FileCopyrightText: 1997 Matthias Kalle Dalheimer <kalle@kde.org>
4 SPDX-FileCopyrightText: 1998, 1999 Waldo Bastian <bastian@kde.org>
5
6 SPDX-License-Identifier: LGPL-2.0-or-later
7*/
8
9#ifndef KURLAUTHORIZED_H
10#define KURLAUTHORIZED_H
11
12#include "kiocore_export.h"
13
14#include <KAuthorized>
15
16class QUrl;
17class QString;
18
19/**
20 * The functions in this namespace allow actions to be restricted based
21 * on the URL they operate on (see the KAuthorized namespace in
22 * KConfig).
23 *
24 * As with KAuthorized functions, the relevant settings are read from
25 * the application's KSharedConfig instance, so actions can be disabled
26 * on a per-application or global basis (by using the kdeglobals file).
27 *
28 * URLs can be matched based on protocol, host and path, and the
29 * referring URL can be taken into account.
30 *
31 * URL-based restrictions are recorded using this syntax:
32 * @verbatim
33 [KDE URL Restrictions]
34 rule_count=<N>
35 rule_1=<action>,<referingURL_protocol>,<referingURL_host>,<referingURL_path>,<URL_protocol>,<URL_host>,<URL_path>,<enabled>
36 ...
37 rule_N=<action>,<referingURL_protocol>,<referingURL_host>,<referingURL_path>,<URL_protocol>,<URL_host>,<URL_path>,<enabled>
38 @endverbatim
39 *
40 * The following standard actions are defined:
41 *
42 * - redirect: A common example is a web page redirecting to another web
43 * page. By default, internet protocols are not permitted
44 * to redirect to the "file" protocol, but you could
45 * override this for a specific host, for example:
46 * @verbatim
47 [KDE URL Restrictions]
48 rule_count=1
49 rule_1=redirect,http,myhost.example.com,,file,,,true
50 @endverbatim
51 * - list: Determines whether a URL can be browsed, in an "open" or
52 * "save" dialog, for example. If a user should only be
53 * able to browse files under home directory one could use:
54 * @verbatim
55 [KDE URL Restrictions]
56 rule_count=2
57 rule_1=list,,,,file,,,false
58 rule_2=list,,,,file,,$HOME,true
59 @endverbatim
60 * The first rule disables browsing any directories on the
61 * local filesystem. The second rule then enables browsing
62 * the users home directory.
63 * - open: This controls which files can be opened by the user in
64 * applications. It also affects where users can save files.
65 * To only allow a user to open the files in his own home
66 * directory one could use:
67 * @verbatim
68 [KDE URL Restrictions]
69 rule_count=3
70 rule_1=open,,,,file,,,false
71 rule_2=open,,,,file,,$HOME,true
72 rule_3=open,,,,file,,$TMP,true
73 @endverbatim
74 * Note that with the above, users would still be able to
75 * open files from the internet. Note also that the user is
76 * also given access to $TMP in order to ensure correct
77 * operation of KDE applications. $TMP is replaced with the
78 * temporary directory that KDE uses for this user.
79 * - link: Determines whether a URL can be linked to.
80 *
81 * Some remarks:
82 * - empty entries match everything
83 * - host names may start with a wildcard, e.g. "*.acme.com"
84 * - a protocol also matches similar protocols that start with the same name,
85 * e.g. "http" matches both http and https. You can use "http!" if you only want to
86 * match http (and not https)
87 * - specifying a path matches all URLs that start with the same path. For better results
88 * you should not include a trailing slash. If you want to specify one specific path, you can
89 * add an exclamation mark. E.g. "/srv" matches both "/srv" and "/srv/www" but "/srv!" only
90 * matches "/srv" and not "/srv/www".
91*/
92namespace KUrlAuthorized
93{
94/**
95 * Returns whether a certain URL related action is authorized.
96 *
97 * @param action The name of the action, typically one of "list",
98 * "link", "open" or "redirect".
99 * @param baseUrl The url where the action originates from.
100 * @param destUrl The object of the action.
101 * @return @c true if the action is authorized, @c false
102 * otherwise.
103 *
104 * @see allowUrlAction()
105 * @since 5.0
106 */
107KIOCORE_EXPORT bool authorizeUrlAction(const QString &action, const QUrl &baseUrl, const QUrl &destUrl);
108
109/**
110 * Override Kiosk restrictions to allow a given URL action.
111 *
112 * This can be useful if your application needs to ensure access to an
113 * application-specific directory that may otherwise be subject to Kiosk
114 * restrictions.
115 *
116 * @param action The name of the action.
117 * @param baseUrl The url where the action originates from.
118 * @param destUrl The object of the action.
119 *
120 * @see authorizeUrlAction()
121 * @since 5.0
122 */
123KIOCORE_EXPORT void allowUrlAction(const QString &action, const QUrl &baseUrl, const QUrl &destUrl);
124
125}
126
127#endif
128

source code of kio/src/core/kurlauthorized.h