From 43ed7392cdfc734a4304284906b9d0d503381841 Mon Sep 17 00:00:00 2001 From: Wojtek Kosior Date: Fri, 28 Oct 2022 20:15:30 +0200 Subject: [proxy] make it possible to export embedded documentation as standalone .html files and include these in the binary release tarball --- src/hydrilla/proxy/self_doc/en_US/popup.html.jinja | 157 +++++++++++++++++++++ 1 file changed, 157 insertions(+) create mode 100644 src/hydrilla/proxy/self_doc/en_US/popup.html.jinja (limited to 'src/hydrilla/proxy/self_doc/en_US/popup.html.jinja') diff --git a/src/hydrilla/proxy/self_doc/en_US/popup.html.jinja b/src/hydrilla/proxy/self_doc/en_US/popup.html.jinja new file mode 100644 index 0000000..a5ad909 --- /dev/null +++ b/src/hydrilla/proxy/self_doc/en_US/popup.html.jinja @@ -0,0 +1,157 @@ +{# +SPDX-License-Identifier: GPL-3.0-or-later OR CC-BY-SA-4.0 + +Documentation page describing Haketilo popup. + +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 %} Popup {% endblock %} + +{% block main %} + {{ big_heading('Haketilo popup') }} + + {% call section() %} + {% call paragraph() %} + Taking inspiration from user interface features of browser extensions, + Haketilo also offers a popup window for quick interaction with the + user. For technical reasons, the popup is presented as part of the web + page and behaves slightly differently from those some users might have + found in similar tools. + {% endcall %} + {% endcall %} + + {% call section() %} + {{ medium_heading('Operating') }} + + {% call paragraph() %} + The popup dialog can be opened by typing big letters "HKT" anywhere on the + page. It then presents some basic information about the handling of + current URL. It also allows the user quickly define new + {{ doc_page_link('rules', 'script_blocking') }} or + {{ doc_page_link('payloads', 'packages') }} for it. As of Haketilo 3.0, + however, the actual configuration is not performed from the popup itself + but rather a relevant Haketilo rule/payload definition page is opened in a + new tab. + {% endcall %} + + {% call paragraph() %} + The dialog can be closed by clicking anywhere on the darker area around + it. It can then be reopened by typing "HKT" again. + {% endcall %} + {% endcall %} + + {% call section() %} + {{ medium_heading('Enabling/disabling') }} + + {% call paragraph() %} + Popup is unavailable by default on Haketilo special sites including + https://hkt.mitm.it. It can also be disabled independently on + {% endcall %} + + {% call unordered_list() %} + {% call list_entry() %} + pages with JS allowed, + {% endcall %} + {% call list_entry() %} + pages with JS blocked and + {% endcall %} + {% call list_entry() %} + pages with script payload injected. + {% endcall %} + {% endcall %} + + {% call paragraph() %} + This can be configured on the {{ hkt_link('setings page', 'home.home') }} + and might be useful to users who are careful about fingerprinting. + {% endcall %} + {% endcall %} + + {% call section() %} + {{ medium_heading('Fingerprinting considerations') }} + + {% call paragraph() %} + To make the popup available, Haketilo has to inject an additional script + to all pages. That makes it easy for pages to determine with certainty + that given user is running Haketilo. This has implications for privacy and + may also be used by a hostile site to selectively cause annoyance to + Haketilo users. + {% endcall %} + + {% call paragraph() %} + The above problems would be present regardless on pages with + Haketilo-injected payloads. I.e. in many cases a site could theoretically + find out the user is not accessing it in a normal way. However, the popup + also increases fingerprintability when no payload is in use and especially + on pages with JavaScript allowed. For this reason, the presence of popup + on pages has been made configurable. + {% endcall %} + + {% call paragraph() %} + It is also worth noting that as of version 3.0 Haketilo does not make + guarantees about the browser fingerprint. Despite best efforts, there are + still other aspects that might make a Haketilo user distinguishable to a + website even when popup is disabled. + {% endcall %} + {% endcall %} + + {% call section() %} + {{ medium_heading('Other caveats') }} + + {% call paragraph() %} + Some other potential issues related to the popup are described below. + {% endcall %} + {% endcall %} + + {% call section() %} + {{ small_heading('Interference with the site') }} + + {% call paragraph() %} + The popup gets injected by Haketilo into the actual web page. Although + care was taken to make accidental breakage unlikely, it might still happen + under some specific conditions. + {% endcall %} + {% endcall %} + + {% call section() %} + {{ small_heading('Interference with other script-blocking tools') }} + + {% call paragraph() %} + The popup is driven by a piece of JavaScript code injected by Haketilo to + pages. Haketilo by itself makes sure neither the policies specified by the + page nor its own script-blocking mechanisms interfere with this particular + piece. In spite of that, a browser extension or web browser's own settings + might prevent the popup script from executing, making the dialog + unavailable. + {% endcall %} + {% endcall %} + + {% call section() %} + {{ small_heading('URL mismatch') }} + + {% call paragraph() %} + Sometimes a page might change parts of its address visible in browser's + URL bar. E.g. after opening https://entraide.chatons.org/ in + the browser we might see https://entraide.chatons.org/en/ as + the current address even though no reload happened. In addition, some + browsers hide URL's traling dash ("/") from the user. Regardless of that, + Haketilo's popup always presents the original URL under which the current + page was served. Although this the intended behavior, it might cause + confusion and therefore has been documented here. + {% endcall %} + {% endcall %} +{% endblock main %} -- cgit v1.2.3