# The &privacybrowser; Handbook

## Introduction

&privacybrowser; is currently in an early alpha state. Most of the features are not yet implemented, but I thought it would be useful to publish it so that users can track the progress and submit feedback.

To distinguish between the Android and the PC version, the website, issue tracker, and code base refer to this version as Privacy Browser PC.

The best place to discuss the development of Privacy Browser is on the forum. I also frequently post on my Mastodon account regarding the development status.

### Qt WebEngine

Privacy Browser uses Qt WebEngine to render websites. Qt WebEngine is based on the Chromium Blink source code. Because Privacy Browser is built on the KDE Framework, it currently uses the Qt 5 packages.

The current Qt 5 packages are in long-term support mode. From a feature perspective, Qt WebEngine 5.15.x is based on Chromium 87.0.4280.144. Security fixes are backported every few months with each release.

### Bugs and Missing Features

There is a list of feature requests and known bugs at redmine.stoutner.com. Users should anticipate that all the current features of Privacy Browser Android will also be implemented in Privacy Browser PC. There is no need at this point to create features requests for these as they will be added as I start working on each feature and have a better idea of how they will be implemented. However, each feature that has already been implemented should be bug free. If you discover a bug that is not already documented at redmine.stoutner.com please add it.

Below is a list of known prominent bugs or missing features in this alpha release.

- The page zoom is momentarily reset every time a new URL is loaded.

- If domain settings change the user agent, loading of the new URL is interrupted and the previous site is reloaded.

- Browser error messages are not displayed unless JavaScript is enabled.

## Using &privacybrowser;

Screenshot

### JavaScript

JavaScript allows web pages to run scripts (programs) on your device. It allows web pages to function more like apps, but it also allows web pages to spy on you. Most of the tracking on the internet does not work when JavaScript is disabled. JavaScript can be toggled by clicking on the privacy shield, which is blue if JavaScript is disabled and red when it is enabled. JavaScript

### Local Storage

Local storage in Privacy Browser encompasses cookies, DOM storage, IndexedDB, service workers, and the filesystem API. Local storage can be toggled through an action on the toolbar.

#### Cookies

Cookies allow websites to store small pieces of information for a specific host that are sent in the HTTP header every time the browser connects to that host. Privacy Browser allows a maximum of 180 cookies with a maximum size of 4096 bytes per cookie to be set per domain. Cookies are often used to track users across the web, particularly third-party cookies (which are completely blocked in Privacy Browser). They are also used as a security mechanism on websites where you log in to identify it is you as you browse from page to page on a site.

Cookies

The cookies dialog is opened from settings-cookies. Durable cookies are shared with all tabs that are opened after they are made durable and are preserved even when Privacy Browser is restarted. This allows users to stay logged in to sites of their choosing. No cookies are durable by default. Making a cookie durable requires specific user interaction.

All other cookies are specific to the tab where they are created and are destroyed when the tab is closed.

#### DOM storage

DOM (Document Object Model) storage, also knows as web storage, allows web pages to store information on a client device. The storage capacity is larger than for cookies and the data is not automatically sent in the headers with every HTTP request. In Privacy Browser, each website is allowed to store a 5 MB of data in DOM storage. DOM storage requires JavaScript to function, and, in addition, requires an extra toggle to be enabled. In Privacy Browser, DOM storage is limited to the tab where it is created and is destroyed when the tab is closed.

#### IndexedDB

IndexedDB provides web pages with a local database where they can store “significant amounts of structured data”. There is disagreement on the internet about the maximum size of an IndexedDB database, probably because the various rendering engines keep changing their mind. But it is usually listed at somewhere between 20% and 80% of your entire hard drive with each individual domain limited to some segment of that. IndexedDB requires JavaScript to function. In Privacy Browser, this database is limited to the tab where it is created and is destroyed when the tab is closed.

#### Service Workers

Service workers are offline JavaScript proxies of a website. They have their own cache that is usually hidden and hard to clear. They were designed by people who want the web browser to become the operating system and run full “apps”. In Privacy Browser, service workers are limited to the tab where they are created and are destroyed when the tab is closed.

#### Filesystem API

The filesystem API grants the browser direct access to the files on your system. Like service workers, the filesystem API is a summarily bad idea thought up by those who want the browser to become an operating system. Even when JavaScript and local storage are enabled, the filesystem API does not work in Privacy Browser.

### User Agent

The user agent is a text string that is sent as part of every HTTP header that identifies the browser to the web server. Privacy Browser's default user agent is `PrivacyBrowser/1.0`. Qt WebEngine 5.15.15’s default user agent is `Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) QtWebEngine/5.15.15 Chrome/87.0.4280.144 Safari/537.36`.

Over the years user agents have become quite lengthy, partially because they tend to include a brief history of the internet. In the modern world they serve almost no good purpose, but some web developers still think they need them so they can send different version of their website to different browsers. Some servers refuse to function correctly if they don't like the user agent that is sent.

At some point in the future Privacy Browser will send no user agent by default. Not only is that currently impossible because the Qt WebEngine doesn't allow you to not send a user agent (I will probably have to fork it to enable that functionality), but even web servers that don't care what the user agent is often refuse to send an answer if there is no user agent at all. Getting rid of this relic of the internet is going to take some time and a retraining of common expectations.

### Domain Settings

Domain setting make it easy to automatically change JavaScript, local storage, user agent, and other settings when the domain changes. Domain settings for the current domain can be accessed through the domain settings button at the far right of the URL line edit. Domain settings for all domains can be accessed through settings-domain-settings. When domain settings are active, the URL line edit will have a green background.

### HTTP Pings

HTTP hyperlinks can have an extra ping attribute that sends a POST request to a different URL. These HTTP pings are commonly used for tracking. Most browsers send HTTP pings without informing the user in any way (despite what The Register article says, current versions of FireFox also happily send HTTP pings).

Privacy Browser blocks all HTTP pings and presents a dialog informing the user every time the current tab attempts to send one. Hopefully, as more people become aware of what HTTP pings are, web sites will become more embarrassed about using them. This is a classic example of how those who wrote the HTTP specs do not have the best interests of internet users at heart. I would like the day to come when this is removed from both the internet and the spec. Here is an example of me raising the issue with F-Droid.

### Spell Checking

Privacy Browser uses the binary `.bdic` Hunspell dictionary format utilized by Qt WebEngine which was created by Google for Chromium. Debian’s Hunspell dictionary language packages are slowly adding support for the `.bdic` format. Those which have are listed by Privacy Browser as suggested packages.

Once a `.bdic` dictionary is installed, it can be enabled in Privacy Browser’s settings.

## Command Reference

### Main Window

#### File

&Ctrl;T File New Tab

- Create a new tab.

&Ctrl;N File New Window

- Create a new window.

&Ctrl;A File Save Archive

- Save the webpage as an MHT (MIME encapsulation of aggregate HTML documents) archive.

&Ctrl;P File Print

- Print the document.

&Ctrl;&Shift;P File Print Preview

- Display the print preview dialog.

&Ctrl;Q File Quit

- Quit &privacybrowser;.

#### Edit

&Ctrl;F Edit Find

- Display the find toolbar and focus the find text line edit. If the toolbar is already displayed, the find text line edit is refocused and the text it contains is selected.

F3 Edit Find Next

- Find the next entry on the page that matches the specified text. This action is only displayed if the find toolbar is visible.

&Shift;F3 Edit Find Previous

- Find the previous entry on the page that matches the specified text. This action is only displayed if the find toolbar is visible.

#### View

&Ctrl;0 View Zoom Default

- Return to either the app or the domain default zoom factor.

&Ctrl;+ View Zoom In

- Increment the zoom factor by 0.25. Valid factors range from 0.25 to 5.00.

&Ctrl;- View Zoom Out

- Decrement the zoom factor by 0.25. Valid factors range from 0.25 to 5.00.

F5 View Refresh

- Reload the website in the current tab. When Refresh is visible, view-stop is hidden.

&Ctrl;F5 View Reload and Bypass Cache

- Reload the website in the current tab bypassing any information in the cache and loading everything from the webserver.

&Ctrl;&Shift;X View Stop

- Stop the loading of the website in the current tab. When Stop is visible, view-refresh is hidden.

&Ctrl;U View View Source

- Toggle between viewing the source and viewing the rendered website.

&Ctrl;&Shift;U View View Source in New Tab>

- Open a new tab displaying the source of the current tab, or a new tab displaying the rendered version if the source is already displayed. Note that right-clicking on the background of a rendered website will display a context menu with a "View page source" entry, which performs the first of these actions.

F12 View Developer Tools

- Display the developer tools, which are used to debug websites.

&Ctrl;&Shift;F View Full Screen Mode

- Toggle full screen mode. This performs the same action as f11.

#### Go

&Alt;Left Go Back

- Navigate back one step in the current tab’s history. The action is disabled if it is not possible to go back.

&Alt;Right Go Forward

- Navigate forward one step in the current tab’s history. The action is disabled if it is not possible to go forward.

&Alt;Home Go Home

- Load the home page in the current tab.

#### On-The-Fly Settings

&Ctrl;J On-The-Fly Settings JavaScript

- Toggle JavaScript in the current tab.

&Ctrl;L On-The-Fly Settings Local Storage

- Toggle local storage in the current tab.

&Ctrl;D On-The-Fly Settings DOM Storage

- Toggle DOM storage in the current tab.

##### User Agent

&Ctrl;&Alt;P On-The-Fly Settings User Agent Privacy Browser

- Use the Privacy Browser user agent for the current tab.

&Ctrl;&Alt;W On-The-Fly Settings User Agent WebEngine Default

- Use the WebEngine Default user agent for the current tab.

&Ctrl;&Alt;F On-The-Fly Settings User Agent Firefox on Linux

- Use the Firefox on Linux user agent for the current tab.

&Ctrl;&Alt;C On-The-Fly Settings User Agent Chromium on Linux

- Use the Chromium on Linux user agent for the current tab.

&Ctrl;&Alt;&Shift;F On-The-Fly Settings User Agent Firefox on Windows

- Use the Firefox on Windows user agent for the current tab.

&Ctrl;&Alt;&Shift;C On-The-Fly Settings User Agent Chrome on Windows

- Use the Chrome on Windows user agent for the current tab.

&Ctrl;&Alt;E On-The-Fly Settings User Agent Edge on Windows

- Use the Edge on Windows user agent for the current tab.

&Ctrl;&Alt;S On-The-Fly Settings User Agent Safari on macOS

- Use the Safari on macOS user agent for the current tab.

&Alt;&Shift;C On-The-Fly Settings User Agent Custom

- Use the custom user agent for the current tab. This action is only active if a custom user agent is set in the settings.

##### Zoom

&Ctrl;&Alt;Z On-The-Fly Settings Zoom Factor

- Display the zoom factor dialog.

##### Search Engine

&Ctrl;&Shift;M On-The-Fly Settings Search Engine Mojeek

- Use Mojeek as the search engine.

&Ctrl;&Shift;O On-The-Fly Settings Search Engine Monocles

- Use Mojeek as the search engine.

&Ctrl;&Shift;E On-The-Fly Settings Search Engine MetaGer

- Use MetaGer as the search engine.

&Ctrl;&Shift;G On-The-Fly Settings Search Engine Google

- Use Google as the search engine.

&Ctrl;&Shift;B On-The-Fly Settings Search Engine Bing

- Use Bing as the search engine.

&Ctrl;&Shift;Y On-The-Fly Settings Search Engine Yahoo

- Use Yahoo as the search engine.

&Ctrl;&Shift;C On-The-Fly Settings Search Engine Custom

- Use the custom search engine. This action is only active if a custom search engine is set in the settings.

#### Filter Lists

&Ctrl;R Filter Lists Requests

- Open the requests dialog.

&Ctrl;&Shift;L Filter Lists View Filter Lists

- View the filter lists dialog.

#### Bookmarks

&Ctrl;&Alt;&Shift;B Bookmarks Edit Bookamrks

- Open the bookmark editing dialog.

&Ctrl;&Alt;B Bookmarks View Bookmarks Toolbar

- Toggle the visibility of the bookmarks toolbar.

&Ctrl;B Bookmarks Add Bookmark

- Add a new bookmark.

&Meta;F Bookmarks Add Folder

- Add a bookmark folder. The meta key on most keyboards is the Windows key.

#### Settings

&Ctrl;&Shift;D Settings Domain Settings

- Display the domain settings dialog.

&Ctrl;; Settings Cookies

- Display the cookies dialog.

#### Common Settings and Help Entries

&privacybrowser; has many common &kde; Settings and Help menu items. For more information read the sections about the Settings Menu and Help Menu.

#### Other Commands

`&Ctrl;+S`

- Toggle find case sensitive if the find toolbar is visible.

`&Ctrl;+&Shift;+Click`

- Open link in new tab. This performs the same action as right-clicking on the link and selecting “Open link in new tab”.

`&Ctrl;+Click`

- Open link in new background tab. This performs the same action as right-clicking on the link and selecting “Open link in new background tab”.

`&Shift;+Click`

- Open link in new window. This performs the same action as right-clicking on the link and selecting “Open link in new window”.

`&Alt;+Click`

- Save link. This performs the same action as right-clicking on the link and selecting “Save link”.

`F11`

- Toggle full screen mode. This performs the same action as view-full-screen-mode.

`&Esc;`

- Escape runs the first command that applies from the following list.

  - Exit full screen browsing.

  - Clear the find text line edit and the find text highlights.

  - Hide the find text toolbar.

### Cookies Dialog

The cookies dialog is accessed through settings-cookies (see cookies).

#### Commands

`A`

- Open the add cookie dialog.

`E`

- Open the edit cookie dialog. This command is only valid if a cookie is currently selected.

`D or ∇`

- Delete the currently selected cookies. A dialog will confirm the deletion before it is processed.

`L`

- Delete all the cookies. A dialog will confirm the deletion before it is processed.

`C or &Ctrl;Q`

- Close the cookies dialog.

### Save Dialog

The save dialog pops up when a download is initiated.

#### Commands

`S`

- Save the file.

`C or &Ctrl;Q`

- Close the save dialog without saving the file.

## Changelog

### 0.6.1 - 21 August 2024

- Fix the domain settings dialog not fitting on small screens.

- Apply domain settings even when the main URL is explicitly allowed by the filter lists.

### 0.6 - 15 July 2024

- Add filter lists.

- Add URL syntax highlighting.

- Add a DevTools interface.

- Implement opening and saving of MHT web archives.

- Handle HTTP authentication.

- Remember the download directory.

- Update bookmarks in all windows when modified.

- Display Unicode URLs in Punycode.

- Multiple small improvements to the code and the user experience.

### 0.5 - 12 October 2023

- Add bookmarks.

- Add zoom controls to the status bar and a default zoom shortcut.

- Add keyboard shortcuts for the URL toolbar actions.

- Add an action to view page source.

- Change the domain settings combo boxes to list `enabled` above `disabled`.

- File downloads can now show the size before the download begins.

- Add PIE (Position Independent Executable) compiler flags.

- Fix a bug that sometimes allowed multiple domain settings to be created.

- Fix the download notification not being cleared on Xfce.

### 0.4 - 13 June 2023

- Add a setting to control spatial navigation.

- Add an action to reload and bypass cache.

- Fix a crash if one Privacy Browser window is closed while a tab within it is loading.

- Add keyboard+click commands to the Handbook.

### 0.3 - 8 May 2023

- Add the changelog to the Handbook.

- Add the missing current domain settings icon on Gnome and Xfce.

- Make changes to build on Guix.

### 0.2 - 17 April 2023

- Fix a crash on GNOME when downloading a file with local storage disabled.

- Fix problems with missing icons on GNOME.

- Display an animated favorite icon while a webpage is loading.

- Fix the Handbook on non-KDE systems.

- Change the order of entries in the WebEngine context menu.

- Make spellcheck languages easier to click on.

- Only generate a HTTP ping dialog if the request is made by the current tab.

- Add a section to the Handbook about HTTP pings.

### 0.1 - 11 March 2023

- Initial release.

## Questions and Answers

Why are there no questions?

Because Privacy Browser is so perfectly designed that none have ever been asked. Also, because this is an alpha release and nobody has had a chance to ask them yet. ;)

## Credits and License

Privacy Browser PC copyright 2016-2017, 2021-2024 Soren Stoutner soren@stoutner.com.

### Program

The source code is available at gitweb.stoutner.com or by running `git clone https://git.stoutner.com/PrivacyBrowserPC.git`.

Translators:

- Translations will be added in a future release.

&underGPL;

### Filter Lists

UltraPrivacy and UltraList are developed by Stoutner. They are released under the GPLv3+.

EasyPrivacy, EasyList, and Fanboy’s Annoyance List are dual licensed under the GPLv3+ and the Creative Commons Attribution-ShareAlike 3.0+ Unported licenses. Privacy Browser PC incorporates them using the GPLv3+ option. More information about these filter lists can be found on the EasyList website.

### Documentation

`doc/index.docbook` and `src/com.stoutner.privacybrowser.appdata.xml` are released under the GFDL-1.3 license with no Front-Cover or Back-Cover Texts or Invariant Sections. All other documentation is released under the GPLv3+ license.

&underFDL;

### Icons

Privacy Browser JavaScript Privacy Browser Monochrome are derived from `security` and `language`, which are part of the Android Material icon set and are released under the Apache License 2.0. Modifications copyright 2016-2017,2021-2023 Soren Stoutner. The resulting images are released under the GPLv3+ license.

Loading comes from FlutterLoadingGIFs where it is named `cupertino_activity_indicator_selective.gif`. It is released under the Zero-Clause BSD License.