diff options
author | Wojtek Kosior <koszko@koszko.org> | 2022-10-28 20:15:30 +0200 |
---|---|---|
committer | Wojtek Kosior <koszko@koszko.org> | 2022-10-28 20:15:30 +0200 |
commit | 43ed7392cdfc734a4304284906b9d0d503381841 (patch) | |
tree | 5d78662357507aac0820825a8ace0859c395779d /src/hydrilla/proxy/self_doc/en_US/script_blocking.html.jinja | |
parent | 2a622842c38f1f9df2aee6af28bf9932d05a2ef0 (diff) | |
download | haketilo-hydrilla-43ed7392cdfc734a4304284906b9d0d503381841.tar.gz haketilo-hydrilla-43ed7392cdfc734a4304284906b9d0d503381841.zip |
[proxy] make it possible to export embedded documentation as standalone .html files and include these in the binary release tarball
Diffstat (limited to 'src/hydrilla/proxy/self_doc/en_US/script_blocking.html.jinja')
-rw-r--r-- | src/hydrilla/proxy/self_doc/en_US/script_blocking.html.jinja | 125 |
1 files changed, 125 insertions, 0 deletions
diff --git a/src/hydrilla/proxy/self_doc/en_US/script_blocking.html.jinja b/src/hydrilla/proxy/self_doc/en_US/script_blocking.html.jinja new file mode 100644 index 0000000..c0a5275 --- /dev/null +++ b/src/hydrilla/proxy/self_doc/en_US/script_blocking.html.jinja @@ -0,0 +1,125 @@ +{# +SPDX-License-Identifier: GPL-3.0-or-later OR CC-BY-SA-4.0 + +Documentation page describing how Haketilo blocks scripts. + +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 %} Script blocking {% endblock %} + +{% block main %} + {{ big_heading('Script blocking in Haketilo') }} + + {% call section() %} + {% call paragraph() %} + Modern web browsers allow sites to execute software on users' + devices. This software is usually written in a language called JavaScript + and abbreviated as JS. It can serve various purposes - from small + enhancements to deployment of heavy applications inside the + browser. Because Haketilo aims to give users control over their web + browsing, one of its supported features is blocking of JavaScript + execution on per-page and per-site basis. + {% endcall %} + + {% call paragraph() %} + Besides the casual script-blocking discussed here, Haketilo also blocks + page's JavaScript when injecting the user-specified + {{ doc_page_link('script payloads', 'packages') }}. That functionality is + described on its own documentation page. + {% endcall %} + {% endcall %} + + {% call section() %} + {{ medium_heading('Configuring script blocking') }} + + {% call paragraph() %} + User can + {{ + hkt_link('define script-blocking and -allowing rules', 'rules.rules') + }} + using {{ doc_page_link('URL patterns', 'url_patterns') }}. Each such rule + tells Haketilo to either block or allow scripts on pages matched by its + pattern. Rules with more specific patterns can override those with less + specific ones as described on the + {{ doc_page_link('policy selection page', 'policy_selection') }}. + {% endcall %} + + {% call paragraph() %} + As an example, if we want all scripts on english Wikipedia pages to be + blocked, we can add a blocking rule with + pattern <code>https://en.wikipedia.org/***</code>. If we then wanted to + make an exception just for the "List of emoticons" page, we could create + an additional allowing rule with + <code>https://en.wikipedia.org/wiki/List_of_emoticons</code> as its + pattern. It would take effect on that page while all the other english + Wikipedia pages would still have their scripts blocked. + {% endcall %} + + {% call paragraph() %} + It is also possible to configure whether scripts should be blocked by + dafault on pages where no explicit rule and no payload is used. The + relevant option can be found on Haketilo + {{ hkt_link('settings page', 'home.home') }}. + {% endcall %} + {% endcall %} + + {% call section() %} + {{ medium_heading('Use with other script-blocking tools') }} + + {% call paragraph() %} + Various browsers and browser extension can also be configured to block + JavaScript. Haketilo works independently of those tools. If the user + desires to have scripts on certain page to execute normally, both Haketilo + and other tools must be configured to allow that. + {% endcall %} + + {% call paragraph() %} + Unlike most similar tools, Haketilo operates outside the web browser. As a + result, it is relatively unlikely for Haketilo to cause these to + malfunction. At the same time, it is relatively easy to have another + script blocker break some Haketilo functionality (e.g. its + {{ doc_page_link('popup', 'popup') }}). + {% endcall %} + {% endcall %} + + {% call section() %} + {{ medium_heading('Technical details') }} + + {% call paragraph() %} + From technical point of view, Haketilo, as of version 3.0, blocks + JavaScript by altering the Content-Security-Policy (abbreviated CSP) + headers in HTTP responses. The original CSP directives sent by site are + retained, with exception of those which would result in CSP violation + reports being sent. Haketilo's own script-blocking directives are then + added to produce the final CSP which user's web browser eventually sees. + {% endcall %} + + {% call paragraph() %} + The above means that neither the scripts that would be blocked by page's + own rules nor those that are blocked by Haketilo are going to cause CSP + reports to be sent. + {% endcall %} + + {% call paragraph() %} + In addition, even when a page has JavaScript nominally blocked, Haketilo + 3.0 may nevertheless inject into it its own script responsible for making + the popup available. The CSP is then modified appropriately to allow only + that script to run. + {% endcall %} + {% endcall %} +{% endblock main %} |