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