kloak(8) -- anti keystroke deanonymization tool
=============================================

<!--
# Copyright (C) 2016 - 2025 ENCRYPTED SUPPORT LLC adrelanos@whonix.org
# See the file COPYING for copying conditions.

# Not using angle brackets in copyright notice for e-mail address, because
# angle brackets would result in this file being non-deterministic. (There
# must be a bug in Debian wheezy in ruby-ronn.)

# Not using "##", because for some reason this comment would be visible in the
# resulting man page.
-->

## SYNOPSIS
`kloak` [options]

## OPTIONS
  * `-h`, `--help`:
    Print usage message and exit.
  * `-d`, `--delay` :
    Configure the maximum delay of released events. Default is 100.
  * `-s`, `--start-delay` :
    Configure the time to wait before starting. Default is 500.
  * `-c`, `--color` :
    Configure the color to use for the virtual mouse cursor. Expects a
    hexadecimal value in the format AARRGGBB (one byte for each of alpha, red,
    green, blue). Default is 00000000 (fully transparent black, i.e.
    invisible).
  * `-n`, `--natural-scrolling` :
    Enable reversed ("natural") scrolling. Expects the string 'true' or
    'false'. Default is 'false'.
  * `-k`, `--esc-key-combo` :
    Specify the key combination that will terminate kloak. Keys are separated
    by commas. Keys can be aliased to each other by separating them with a
    pipe (|) character. Defaults is KEY_RIGHTSHIFT,KEY_ESC.

## DESCRIPTION
kloak is an event-level online anonymization kernel for keyboards and mice.

kloak is a privacy tool that makes input biometrics less effective. For
keyboards, this is accomplished by obfuscating the time intervals between
input events. For mice, this is done by obfuscating the time intervals between
between mouse input events, the number of mouse input events, and the exact
path taken by the mouse pointer. This data can be used for identification if
not obfuscated.

## USAGE
On startup, `kloak` will grab all evdev input devices with libinput, and will
proxy the events from those devices to the running Wayland compositor via
emulated input protocols. There is no need to configure specific devices to be
grabbed; `kloak` autodetects devices and displays, even when hotplugged.

`kloak` requires the ability to exclusively grab input devices under
/dev/input, thus it usually needs to be run as root. Additionally, it needs
XDG_RUNTIME_DIR and WAYLAND_DISPLAY set in order to connect to the correct
Wayland compositor:

`sudo XDG_RUNTIME_DIR="$XDG_RUNTIME_DIR" WAYLAND_DISPLAY="$WAYLAND_DISPLAY" ./kloak`

Optionally start `kloak` by specifying the event and startup delay. A longer
startup delay (configured with `-s`) can be useful to avoid problems with
startup, while a longer event delay (configured with `-d`) will provide
possibly better anonymity at the cost of reducing usability. There is no need
to configure `kloak` so it can find your Wayland compositor, even on a system
with multiple graphically logged in users. `kloak` will automatically detect
the Wayland compositor running on the display and will connect to that
compositor.

Once `kloak` is started, your mouse movements will move a "virtual" mouse
cursor. This cursor is invisible by default (which provides a better
experience when using `kloak` inside most virtual machine software). When you
move the mouse, the virtual cursor will move first. The real mouse cursor will
then chase it in an erratic pattern. Websites and most applications can only
track the real mouse cursor, not the virtual one, thus this hides the rhythm
of your actual mouse movements from applications. Keystroke rhythms will be
obfuscated as well by inserting random delays into the usual stream of key
press and key release events.

If you want to see the virtual mouse cursor, use the `-c` option to set the
cursor's color. It will appear as a small crosshair.

Because `kloak` grabs all input devices for itself and only sends those events
to a single compositor, keyboard and mouse input to anything other than that
Wayland compositor will not work as long as `kloak` is running. This will
prevent use of TTYs and complicate switching between multiple graphically
logged-in users. In order to prevent this from causing a lock-out scenario,
`kloak` monitors all keystrokes to determine if an "escape combo" has been
pressed. This escape combo is `KEY_RIGHTSHIFT,KEY_ESC` by default; default; you
can configure it using the `-k` option. `kloak` will immediately exit when this
combo is received.

`kloak` interacts directly with all input devices, thus input device settings
that would usually be configured by the Wayland compositor need to be
configured in `kloak` instead. Currently the only special feature `kloak`
supports is reversed (a.k.a. "natural") scrolling, which can be enabled by
specifying `--natural-scrolling=true`.

Typically, if `kloak` cannot connect to a Wayland compositor, it will remain
running, but will do nothing other than swallowing all keyboard and mouse
input. It will wait for the user to press an escape key combo before exiting.
If you would like `kloak` to exit immediately if it cannot connect to Wayland,
set the `KLOAK_EXIT_ON_WL_CONNECT_FAILURE` environment variable to `1`.

## WWW
https://github.com/Whonix/kloak

## CREDITS
kloak was originally written by Vinnie Monaco. It was then rewritten by Aaron
Rainbolt to work with Wayland and provide better mouse obfuscation.

## AUTHOR
This man page has been written by Patrick Schleizer (adrelanos@whonix.org).
