diff options
Diffstat (limited to 'src/hydrilla/proxy/self_doc/en_US/policy_selection.html.jinja')
| -rw-r--r-- | src/hydrilla/proxy/self_doc/en_US/policy_selection.html.jinja | 109 |
1 files changed, 109 insertions, 0 deletions
diff --git a/src/hydrilla/proxy/self_doc/en_US/policy_selection.html.jinja b/src/hydrilla/proxy/self_doc/en_US/policy_selection.html.jinja new file mode 100644 index 0000000..687d2bd --- /dev/null +++ b/src/hydrilla/proxy/self_doc/en_US/policy_selection.html.jinja @@ -0,0 +1,109 @@ +{# +SPDX-License-Identifier: GPL-3.0-or-later OR CC-BY-SA-4.0 + +Documentation page describing how Haketilo selects policy to apply to a page. + +This file is part of Hydrilla&Haketilo. + +Copyright (C) 2022 Wojtek Kosior + +Dual licensed under +* GNU General Public License v3.0 or later and +* Creative Commons Attribution Share Alike 4.0 International. + +You can choose to use either of these licenses or both. + + +I, Wojtek Kosior, thereby promise not to sue for violation of this +file's licenses. Although I request that you do not make use of this +code in a proprietary work, I am not going to enforce this in court. +#} +{% extends "doc_base.html.jinja" %} + +{% block title %} Policy selection {% endblock %} + +{% block main %} + {{ big_heading('Page policy selection') }} + + {% call section() %} + {% call paragraph() %} + When a web page is opened, Haketilo is capable of either + {% call unordered_list() %} + {% call list_entry() %} + blocking page's own scripts and + {{ doc_page_link('injecting payload', 'packages') }} + configured by the user, + {% endcall %} + {% call list_entry() %} + blocking page's own scripts and injecting an automatically-chosen + payload that is usable with the page, + {% endcall %} + {% call list_entry() %} + presenting a dialog asking whether to enable an automatically-chosen + payload that is usable with the page, + {% endcall %} + {% call list_entry() %} + {{ doc_page_link('blocking', 'script_blocking') }} page's own scripts + or + {% endcall %} + {% call list_entry() %} + allowing page's own scripts to execute normally (i.e. not modifying + the page in any meaningful way). + {% endcall %} + {% endcall %} + {% endcall %} + {% endcall %} + + {% call section() %} + {{ medium_heading('Policy precedence') }} + + {% call paragraph() %} + User configures Haketilo's behavior by defining script-blocking and + -allowing rules and by adding and enabling packages. Each rule and each + package payload has a {{ doc_page_link('URL pattern', 'url_patterns') }}. + This pattern determines which pages the policy is compatible with. + Patterns also have well-defined specificity. When multiple rules and + packages are combatible with given page's URL, the one with the most + specific pattern "wins". In case of a tie, payload injection is assumed to + take precedence over rule application. + {% endcall %} + + {% call paragraph() %} + In the absence of suitable rules and enabled packages, Haketilo may + consider non-enabled packages that are suitable for use on the + currently-visited site. It will either inject package payload + automatically, ask the user whether to enable the package or ignore it + completely. The user can switch between these 3 behaviors on the Haketilo + {{ hkt_link('settings page', 'home.home') }}. Packages that were + explicitly marked as disabled will always be ignored. Pattern specificity + is also taken into account in case of multiple packages. + {% endcall %} + + {% call paragraph() %} + When absolutely no explicit policy appears suitable for given page, + Haketilo will apply its default script handling behavrior. Whether + JavaScript is blocked or allowed by default is also determined by user's + choice on the {{ hkt_link('settings page', 'home.home') }}. + {% endcall %} + {% endcall %} + + {% call section() %} + {{ medium_heading('Special cases') }} + + {% call paragraph() %} + The sites served by Haketilo itself are exempt from all policies. These + are <code>http://hkt.mitm.it</code>, <code>https://hkt.mitm.it</code> + and <code>http://mitm.it</code>. Additionally, if Haketilo experiences an + internal error (e.g. because it could not parse current URL as sent in by + the browser), it will try to block page's JavaScript as a security + measure. + {% endcall %} + + {% call paragraph() %} + Internally, Haketilo also has a special high-priority policy for serving + files used by payloads and for making its APIs accessible to payload + scripts. This is, however, an implementation detail and casual users need + not care about it nor understand these nuances. + {% endcall %} + {% endcall %} +{% endblock main %} |