Update all documentation for 2.7.0

* Update INSTALL.md to align with Wiki * Add sections for new 2.7.0 features including Quick Unlock, Tags, Browser Integration settings, Auto-Type improvements, etc. * Update all documentation images to show new interface details * Expand documentation for database operations
quokka-toolbox · Mar 20, 2022 · 5c772ce · 5c772ce
1 parent 9569438
commit 5c772ce
Show file tree

Hide file tree

Showing 40 changed files with 229 additions and 120 deletions.
diff --git a/INSTALL.md b/INSTALL.md
@@ -14,18 +14,19 @@ The following tools must exist within your PATH:
 * make
 * cmake (>= 3.3.0)
 * g++ (>= 4.7) or clang++ (>= 6.0)
-* asciidoctor
+* asciidoctor (>= 2.0)
 
 The following libraries are required:
 
 * Qt 5 (>= 5.9.5): qtbase5, qtbase5-private, libqt5svg5, qttools5, qt5-image-formats-plugins
 * botan (>= 2.12)
+* libargon2
 * zlib
 * minizip
 * readline (for completion in cli)
-* libqt5x11extras5, libxi, and libxtst (for auto-type on X11)
+* qtx11extras, libxi, and libxtst (for auto-type on X11)
 * qrencode
-* libusb-1.0, pcsclite (optional to support YubiKey on Linux)
+* libusb-1.0, pcsc-lite (for Yubikey support on Linux)
 
 Prepare the Building Environment
 ================================
@@ -38,110 +39,119 @@ Build Steps
 ===========
 We recommend using the release tool to perform builds, please read up-to-date instructions [on our wiki](https://github.com/keepassxreboot/keepassxc/wiki/Building-KeePassXC#building-using-the-release-tool).
 
-To compile from source, open a **Terminal (on Linux/MacOS)** or a **MSYS2-MinGW shell (on Windows)**<br/>
-**Note:** on Windows you can also use MSVC to build natively, we recommend Visual Studio 2019
+To compile from source, open a **Terminal (Linux/MacOS)**, the **MSVC Tools Command Prompt (Windows)**, or **MSYS2-MinGW shell (Windows)**. For code development on Windows, you can use Visual Studio 2022, Visual Studio Code, or CLion.
 
-First, download the KeePassXC [source tarball](https://keepassxc.org/download#source)
-or check out the latest version from our [Git repository](https://github.com/keepassxreboot/keepassxc).
+1. Download the KeePassXC [source tarball](https://keepassxc.org/download#source) or check out the latest version from our [Git repository](https://github.com/keepassxreboot/keepassxc).
 
-To clone the project from Git, `cd` to a suitable location and run
+   To clone the project from Git, `cd` to a suitable location and run
 
-```bash
-git clone https://github.com/keepassxreboot/keepassxc.git
-```
+   ```
+   git clone https://github.com/keepassxreboot/keepassxc.git
+   ```
 
-This will clone the entire contents of the repository and check out the current `develop` branch.
+   This will clone the entire contents of the repository and check out the current `develop` branch.
 
-To update the project from within the project's folder, you can run the following command:
+   To update the project from within the project's folder, you can run the following command:
 
-```bash
-git pull
-```
+   ```
+   git pull
+   ```
 
-For a stable build, it is recommended to checkout the master branch.
+   For a stable build, it is recommended to check out the master branch.
 
-```bash
-git checkout master
-```
+   ```
+   git checkout master
+   ```
 
-NOTE: See the [Windows Build Instructions](https://github.com/keepassxreboot/keepassxc/wiki/Building-KeePassXC#windows) for building with MSVC.
+2. Navigate to the directory where you have downloaded KeePassXC and type these commands:
 
-Navigate to the directory where you have downloaded KeePassXC and type these commands:
+   ```
+   mkdir build
+   cd build
+   cmake -DWITH_XC_ALL=ON ..
+   make
+   ```
 
-```
-mkdir build
-cd build
-cmake -DWITH_XC_ALL=ON ..
-make
-```
+Note: These steps place the compiled KeePassXC binary inside the `./build/src/` directory.
 
-NOTE: If you are using MSYS2, you may have to add ```-G "MSYS Makefiles"``` to the beginning of the cmake command.
+## MacOS Build Notes
 
-These steps place the compiled KeePassXC binary inside the `./build/src/` directory.
-(Note the cmake notes/options below.)
+If you installed Qt5 via Homebrew, you should be able to compile KeePassXC without any changes. If CMake fails to find your Qt installation, you can specify it manually by adding the following parameter:
 
-**Cmake Notes:**
+`-DCMAKE_PREFIX_PATH=/usr/local/opt/qt/lib/cmake`
 
-* Common cmake parameters
+(or whatever your Qt installation path is)
 
-	```
-	-DCMAKE_INSTALL_PREFIX=/usr/local
-	-DCMAKE_VERBOSE_MAKEFILE=ON
-	-DCMAKE_BUILD_TYPE=<RelWithDebInfo/Debug/Release>
-	-DWITH_GUI_TESTS=ON
-	```
+When building with ASAN support on macOS, you need to use `export ASAN_OPTIONS=detect_leaks=0` before running the tests (LSAN is no supported on macOS).
 
-* cmake accepts the following options:
+## Windows Build Notes
 
-	```
-	  -DWITH_XC_AUTOTYPE=[ON|OFF] Enable/Disable Auto-Type (default: ON)
-	  -DWITH_XC_YUBIKEY=[ON|OFF] Enable/Disable YubiKey HMAC-SHA1 authentication support (default: OFF)
-	  -DWITH_XC_BROWSER=[ON|OFF] Enable/Disable KeePassXC-Browser extension support (default: OFF)
-	  -DWITH_XC_NETWORKING=[ON|OFF] Enable/Disable Networking support (e.g., favicon downloading) (default: OFF)
-	  -DWITH_XC_SSHAGENT=[ON|OFF] Enable/Disable SSHAgent support (default: OFF)
-	  -DWITH_XC_FDOSECRETS=[ON|OFF] (Linux Only) Enable/Disable Freedesktop.org Secrets Service support (default:OFF)
-	  -DWITH_XC_KEESHARE=[ON|OFF] Enable/Disable KeeShare group synchronization extension (default: OFF)
-	  -DWITH_XC_ALL=[ON|OFF] Enable/Disable compiling all plugins above (default: OFF)
+For detailed build steps see the [Windows Build Instructions](https://github.com/keepassxreboot/keepassxc/wiki/Building-KeePassXC#windows).
 
-	  -DWITH_XC_UPDATECHECK=[ON|OFF] Enable/Disable automatic updating checking (requires WITH_XC_NETWORKING) (default: ON)
+If you are using MSVC, you may have to specify your Vcpkg toolchain by adding the following CMake parameter: `-DCMAKE_TOOLCHAIN_FILE=C:\vcpkg\scripts\buildsystems\vcpkg.cmake`
 
-	  -DWITH_TESTS=[ON|OFF] Enable/Disable building of unit tests (default: ON)
-	  -DWITH_GUI_TESTS=[ON|OFF] Enable/Disable building of GUI tests (default: OFF)
-	  -DWITH_DEV_BUILD=[ON|OFF] Enable/Disable deprecated method warnings (default: OFF)
-	  -DWITH_ASAN=[ON|OFF] Enable/Disable address sanitizer checks (Linux / macOS only) (default: OFF)
-	  -DWITH_COVERAGE=[ON|OFF] Enable/Disable coverage tests (GCC only) (default: OFF)
-	  -DWITH_APP_BUNDLE=[ON|OFF] Enable Application Bundle for macOS (default: ON)
+If you are using MSYS2, you have to add ```-G "MSYS Makefiles"``` at the beginning of the cmake command.
+
+CMake Configuration Options
+==========================
+
+## Common Parameters
+
+```
+-DCMAKE_INSTALL_PREFIX=/usr/local
+-DCMAKE_VERBOSE_MAKEFILE=ON
+-DCMAKE_BUILD_TYPE=<RelWithDebInfo/Debug/Release>
+-DWITH_GUI_TESTS=ON
+```
 
-	  -DKEEPASSXC_BUILD_TYPE=[Snapshot|PreRelease|Release] Set the build type to show/hide stability warnings (default: "Snapshot")
-	  -DKEEPASSXC_DIST_TYPE=[Snap|AppImage|Other] Specify the distribution method (default: "Other")
-	  -DOVERRIDE_VERSION=[X.X.X] Specify a version number when building. Used with snapshot builds (default: "")
-	  -DGIT_HEAD_OVERRIDE=[XXXXXXX] Specify the 7 digit git commit ref for this build. Used with distribution builds (default: "")
-	```
+## KeePassXC Parameters
 
-* If you are on MacOS you must add this parameter to **Cmake**, with the Qt version you have installed<br/> `-DCMAKE_PREFIX_PATH=/usr/local/Cellar/qt5/5.6.2/lib/cmake/`
+KeePassXC comes with a variety of build options that can turn on/off features. Most notably, we allow you to build the application with all TCP/IP networking code disabled. Please note that we still require and link against Qt5's network library in order to use local named pipes on all operating systems. Each of these build options are supplied at the time of calling cmake:
 
-:exclamation: When building with ASan support on macOS, you need to use `export ASAN_OPTIONS=detect_leaks=0` before running the tests (no LSan support in macOS).
+```
+-DWITH_XC_AUTOTYPE=[ON|OFF] Enable/Disable Auto-Type (default: ON)
+-DWITH_XC_YUBIKEY=[ON|OFF] Enable/Disable YubiKey HMAC-SHA1 authentication support (default: OFF)
+-DWITH_XC_BROWSER=[ON|OFF] Enable/Disable KeePassXC-Browser extension support (default: OFF)
+-DWITH_XC_NETWORKING=[ON|OFF] Enable/Disable Networking support (e.g., favicon downloading) (default: OFF)
+-DWITH_XC_SSHAGENT=[ON|OFF] Enable/Disable SSHAgent support (default: OFF)
+-DWITH_XC_FDOSECRETS=[ON|OFF] (Linux Only) Enable/Disable Freedesktop.org Secrets Service support (default:OFF)
+-DWITH_XC_KEESHARE=[ON|OFF] Enable/Disable KeeShare group synchronization extension (default: OFF)
+-DWITH_XC_ALL=[ON|OFF] Enable/Disable compiling all plugins above (default: OFF)
+
+-DWITH_XC_UPDATECHECK=[ON|OFF] Enable/Disable automatic updating checking (requires WITH_XC_NETWORKING) (default: ON)
+
+-DWITH_TESTS=[ON|OFF] Enable/Disable building of unit tests (default: ON)
+-DWITH_GUI_TESTS=[ON|OFF] Enable/Disable building of GUI tests (default: OFF)
+-DWITH_DEV_BUILD=[ON|OFF] Enable/Disable deprecated method warnings (default: OFF)
+-DWITH_ASAN=[ON|OFF] Enable/Disable address sanitizer checks (Linux / macOS only) (default: OFF)
+-DWITH_COVERAGE=[ON|OFF] Enable/Disable coverage tests (GCC only) (default: OFF)
+-DWITH_APP_BUNDLE=[ON|OFF] Enable Application Bundle for macOS (default: ON)
+
+-DKEEPASSXC_BUILD_TYPE=[Snapshot|PreRelease|Release] Set the build type to show/hide stability warnings (default: "Snapshot")
+-DKEEPASSXC_DIST_TYPE=[Snap|AppImage|Other] Specify the distribution method (default: "Other")
+-DOVERRIDE_VERSION=[X.X.X] Specify a version number when building. Used with snapshot builds (default: "")
+-DGIT_HEAD_OVERRIDE=[XXXXXXX] Specify the 7 digit git commit ref for this build. Used with distribution builds (default: "")
+```
 
 Installation
 ============
 
 After you have successfully built KeePassXC, install the binary by executing the following:
 
-```bash
-sudo make install
-```
-
-You can specify the destination dir with
 ```
-DESTDIR=X
+sudo make install
 ```
 
-
 Packaging
 =========
 
-You can create a package to redistribute KeePassXC (zip, deb, rpm, dmg, etc..). Refer to [keepassxc-packaging](https://github.com/keepassxreboot/keepassxc-packaging)
+You can create a package to redistribute KeePassXC (zip, deb, rpm, dmg, etc..). Refer to [keepassxc-packaging](https://github.com/keepassxreboot/keepassxc-packaging) for packaging scripts.
+
+To package using CMake, run the following command using whichever [generators](https://cmake.org/cmake/help/latest/manual/cpack-generators.7.html) you would like to package with.
 
+```
+cpack -G "ZIP;WIX"
+```
 
 Testing
 =======
@@ -151,7 +161,7 @@ You can perform tests on the built executables with:
 make test ARGS+="--output-on-failure"
 ```
 
-If you are not currently running on an X Server or Wayland, run the tests as follows:
+On Linux, if you are not currently running on an X Server or Wayland, run the tests as follows:
 ```
 make test ARGS+="-E test\(cli\|gui\) --output-on-failure"
 xvfb-run -e errors -a --server-args="-screen 0 1024x768x24" make test ARGS+="-R test\(cli\|gui\) --output-on-failure"

diff --git a/docs/images/autotype_entry_sequences.png b/docs/images/autotype_entry_sequences.png
diff --git a/docs/images/autotype_settings.png b/docs/images/autotype_settings.png
diff --git a/docs/images/browser_database_settings.png b/docs/images/browser_database_settings.png
diff --git a/docs/images/browser_group_settings.png b/docs/images/browser_group_settings.png
diff --git a/docs/images/browser_settings.png b/docs/images/browser_settings.png
diff --git a/docs/images/browser_statistics.png b/docs/images/browser_statistics.png
diff --git a/docs/images/compact_mode_comparison.png b/docs/images/compact_mode_comparison.png
diff --git a/docs/images/csv_import.png b/docs/images/csv_import.png
diff --git a/docs/images/database_maintenance.png b/docs/images/database_maintenance.png
diff --git a/docs/images/database_settings.png b/docs/images/database_settings.png
diff --git a/docs/images/database_view.png b/docs/images/database_view.png
diff --git a/docs/images/edit_entry.png b/docs/images/edit_entry.png
diff --git a/docs/images/edit_entry_history.png b/docs/images/edit_entry_history.png
diff --git a/docs/images/edit_entry_icons.png b/docs/images/edit_entry_icons.png
diff --git a/docs/images/enable_copy_dc.png b/docs/images/enable_copy_dc.png
diff --git a/docs/images/keeshare_application_settings.png b/docs/images/keeshare_application_settings.png
diff --git a/docs/images/main_interface.png b/docs/images/main_interface.png
diff --git a/docs/images/open_database.png b/docs/images/open_database.png
diff --git a/docs/images/passphrase_generator.png b/docs/images/passphrase_generator.png
diff --git a/docs/images/password_generator.png b/docs/images/password_generator.png
diff --git a/docs/images/password_generator_advanced.png b/docs/images/password_generator_advanced.png
diff --git a/docs/images/quick_unlock.png b/docs/images/quick_unlock.png
diff --git a/docs/images/quick_unlock_windows_hello.png b/docs/images/quick_unlock_windows_hello.png
diff --git a/docs/images/save_options.png b/docs/images/save_options.png
diff --git a/docs/images/theme_selection.png b/docs/images/theme_selection.png
diff --git a/docs/images/toolbar.png b/docs/images/toolbar.png
diff --git a/docs/images/totp_code_example.png b/docs/images/totp_code_example.png
diff --git a/docs/images/totp_setup.png b/docs/images/totp_setup.png
diff --git a/docs/images/totp_usage_examples.png b/docs/images/totp_usage_examples.png
diff --git a/docs/images/welcome_screen.png b/docs/images/welcome_screen.png
diff --git a/docs/topics/AutoType.adoc b/docs/topics/AutoType.adoc
@@ -12,21 +12,27 @@ WARNING: Auto-Type will be disabled when run with a Wayland compositor on Linux.
 === Configure Global Auto-Type
 You can define a global Auto-Type hotkey that starts the Auto-Type process. To configure the hotkey, perform the following steps:
 
-1. Navigate to _Tools_ -> _Settings_ -> Auto-Type tab *(1)*. Click into the _Global Auto-Type shortcut_ box and press the desired key combination that will trigger the Auto-Type process *(2)*.
-+
+Navigate to _Tools_ -> _Settings_ -> Auto-Type tab *(1)*. Click into the _Global Auto-Type shortcut_ box and press the desired key combination that will trigger the Auto-Type process *(2)*.
+
 .Auto-Type settings
 image::autotype_settings.png[]
-+
+
 You can configure additional Auto-Type settings in this window such as start delay, inter-key typing delay, and matching options. If Auto-Type is not working well for you, try adjusting the default delays.
 
+You can also set the time to remember the last used entry between presses of the global Auto-Type hotkey. This is useful for typing parts of a sequence during complex login workflows without having to find the specific each time.
+
 === Configure Auto-Type Sequences
 Each entry in your database can have multiple Auto-Type sequences associated with various window titles. Simulated key presses can be sent to any other currently open window of your choice (web browser windows, login dialogs boxes, and so on). When the Global Auto-Type hotkey is pressed, KeePassXC will search your database for entries matching the current selected window title.
 
 NOTE: The default Auto-Type sequence is `{USERNAME}{TAB}{PASSWORD}{ENTER}`. This means that it first types the username of the selected entry, then presses the `Tab` key, then types the password of the entry and finally presses the `Enter` key.
 
+TIP: To change the default Auto-Type sequence for all entries of your database, edit the root (top-most) group of your database and set a specific sequence. Child groups and entries will inherit this sequence by default.
+
 To configure Auto-Type sequences for your entries, perform the following steps:
 
-1.	Navigate to the entries list and open the desired entry for editing. Click the _Auto-Type_ item from the left-hand menu bar *(1)*. Press the `+` button *(2)* to add a new sequence entry. Select the desired window using the drop-down menu, or simply type a window title in the box *(3)*. You can use wildcard `*` to match any value (e.g., when a window title contains a filename or website name).
+1.	Navigate to the entries list and open the desired entry for editing. Click the _Auto-Type_ item from the left-hand menu bar *(1)*. Press the `+` button *(2)* to add a new sequence entry. Select the desired window using the drop-down menu, or simply type a window title in the box *(3)*.
++
+TIP: You can use an asterisk (`\*`) to match any value (e.g., when a window title contains a dynamic filename or website name). Set the window title to `*` to match all windows. Leave the window title blank to offer additional default Auto-Type sequences, such as custom attributes.
 +
 .Auto-Type entry sequences
 image::autotype_entry_sequences.png[]
@@ -43,7 +49,7 @@ image::autotype_entry_sequences.png[]
 |{URL}      |URL
 |{NOTES}    |Notes
 |{TOTP}     |Current TOTP value (if configured)
-|{S:<ATTRIBUTE_NAME>}   |Value for the given attribute name
+|{S:ATTRIBUTE_NAME}   |Value for the given attribute name (e.g., {S:Address})
 |===
 +
 [grid=rows, frame=none, width=90%]
@@ -55,7 +61,7 @@ image::autotype_entry_sequences.png[]
 
 |{UP}, {DOWN}, {LEFT}, {RIGHT}  |Press the corresponding arrow key
 |{LEFTBRACE}, {RIGHTBRACE}      |Press `{` or `}`, respectively
-|{<KEY> X}     |Repeat <KEY> X times (e.g., {SPACE 5} inserts five spaces)
+|{&lt;KEY&gt; X}     |Repeat &lt;KEY&gt; X times (e.g., {SPACE 5} inserts five spaces)
 |{DELAY=X}     |Set delay between key presses to X milliseconds
 |{DELAY X}     |Pause typing for X milliseconds
 |{CLEARFIELD}  |Clear the input field
@@ -81,7 +87,9 @@ Search the unlocked databases by activating Search Database radio button. Use th
 .Additional Auto-Type choices
 image::autotype_selection_dialog_type_menu.png[,70%]
 
-The option to type just the username, password, or current TOTP value is available by right clicking the desired row or expanding the Type Sequence button options.
+The option to type just the username, password, or current TOTP value is available by right-clicking the desired row or expanding the Type Sequence button options. You can also copy these values to the clipboard.
+
+TIP: On Windows, you will see an option to use a virtual keyboard in this sub-menu. This is an experimental feature that allows you to type into virtual machines by simulating actual keyboard presses. Some international keyboards may be unsupported due to limitations in the Windows API.
 
 === Performing Entry-Level Auto-Type
 You can quickly activate the default Auto-Type sequence for a particular entry using Entry-Level Auto-Type. For this operation, the KeePassXC window will be minimized and the Auto-Type sequence occurs in the previously selected window. You can perform Entry-Level Auto-Type from the toolbar icon *(A)*, entry context menu *(B)*, or by pressing `Ctrl+Shift+V`.

diff --git a/docs/topics/BrowserPlugin.adoc b/docs/topics/BrowserPlugin.adoc
@@ -23,6 +23,8 @@ You can download the KeePassXC-Browser extension from your web browser. To downl
 
 2. Click the button to install/add the extension to the browser. Accept any confirmation dialogs.
 
+TIP: For the most up-to-date troubleshooting advice on all platforms, please read our https://github.com/keepassxreboot/keepassxc-browser/wiki/Troubleshooting-guide[Troubleshooting Guide].
+
 // tag::advanced[]
 NOTE: When Microsoft Edge is installed as a managed application, system administrators are required to deploy a custom native messaging configuration. Instructions for this are found in the advanced section below.
 // end::advanced[]
@@ -89,6 +91,12 @@ image::browser_confirm_access_dialog.png[,80%]
 image::browser_fill_credentials.png[,80%]
 
 // tag::advanced[]
+=== Browser statistics
+You can see a cross-section of all browser-related settings applied to entries within a database through the Browser Statistics report. To access these, use the _Database_ -> _Database reports..._ menu option then click on _Browser Statistics_ on the left-hand menu. From here you can see all entries with URLs applied to them, explicitly allowed and denied URLs, and any entries with custom browser settings.
+
+.Browser statistics
+image::browser_statistics.png[]
+
 === Advanced Usage
 You can configure unique browser integration behavior for each entry. This allows you to add multiple URLs to an entry, hide an entry from the browser integration, and more. To access these settings, open an entry for editing then click on _Browser Integration_ option in the left-hand menu *(1)*.
 
@@ -97,6 +105,11 @@ After opening the settings you can add any number of additional URLs by clicking
 .Entry browser settings
 image::browser_entry_settings.png[]
 
+To set options for all entries within a group, edit the group and go to the browser integration section *(1)*. Here you can explicitly disable access to all entries under a group hierarchy to the browser extension. You can set other useful options for groups of entries as well.
+
+.Group browser settings
+image::browser_group_settings.png[]
+
 Database-wide operations are available in the database settings. To access these use the _Database_ -> _Database settings..._ menu option. Click on _Browser Integration_ on the left-hand menu. From here you can disconnect all browsers, convert legacy KeePass-HTTP settings, reset all entry-level settings, and refresh the database root group ID (useful when making copies of your database file).
 
 .Database browser settings