update readme

COPYING

@@ -0,0 +1,32 @@
+Format: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
+
+Files: *
+Copyright: Copyright (c) 2016, Vinnie Monaco
+License: BSD-3-clause
+ Copyright (c) 2016, Vinnie Monaco
+ All rights reserved.
+ .
+ Redistribution and use in source and binary forms, with or without
+ modification, are permitted provided that the following conditions are met:
+ .
+ * Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+ .
+ * Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+ .
+ * Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+ .
+ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+ DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+ FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+ DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+ SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+ CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Makefile

@@ -1,12 +1,46 @@
 #!/usr/bin/make -f
 
+TARGETARCH=$(shell gcc -dumpmachine)
+
+# https://best.openssf.org/Compiler-Hardening-Guides/Compiler-Options-Hardening-Guide-for-C-and-C++.html
+#
+# Omitted the following flags:
+# -D_GLIBCXX_ASSERTIONS  # application is not written in C++
+# -fstrict-flex-arrays=3 # not supported in Debian Bookworm's GCC version (12)
+# -fPIC -shared          # not a shared library
+# -fexceptions           # not multithreaded
+# -fhardened             # not supported in Debian Bookworm's GCC version (12)
+#
+# Added the following flags:
+# -fsanitize=address,undefined # enable ASan/UBSan
+CFLAGS = -O2 -Wall -Wformat -Wformat=2 -Wconversion -Wimplicit-fallthrough \
+  -Werror=format-security -U_FORTIFY_SOURCE -D_FORTIFY_SOURCE=3 \
+	-fstack-clash-protection \
+	-fstack-protector-strong -Wl,-z,nodlopen -Wl,-z,noexecstack -Wl,-z,relro \
+	-Wl,-z,now -Wl,--as-needed -Wl,--no-copy-dt-needed-entries -Wtrampolines \
+	-Wbidi-chars=any -fPIE -pie -Werror=implicit \
+	-Werror=incompatible-pointer-types -Werror=int-conversion \
+	-fno-delete-null-pointer-checks -fno-strict-overflow -fno-strict-aliasing \
+	-fsanitize=undefined
+
+ifeq ($(TARGETARCH), x86_64-linux-gnu)
+CFLAGS += -fcf-protection=full # only supported on x86_64
+endif
+ifeq ($(TARGETARCH), aarch64-linux-gnu)
+CFLAGS += -mbranch-protection=standard # only supported on aarch64
+endif
+
+ifeq (, $(shell which pkg-config))
+$(error pkg-config not installed!)
+endif
+
 all : kloak eventcap
 
 kloak : src/main.c src/keycodes.c src/keycodes.h
-	gcc src/main.c src/keycodes.c -o kloak -lm $(shell pkg-config --cflags --libs libevdev) $(shell pkg-config --cflags --libs libsodium) $(CPPFLAGS) $(CFLAGS) $(LDFLAGS)
+	gcc -g src/main.c src/keycodes.c -o kloak -lm $(shell pkg-config --cflags --libs libevdev) $(shell pkg-config --cflags --libs libsodium) $(CPPFLAGS) $(CFLAGS) $(LDFLAGS)
 
 eventcap : src/eventcap.c
-	gcc src/eventcap.c -o eventcap $(CPPFLAGS) $(CFLAGS) $(LDFLAGS)
+	gcc -g src/eventcap.c -o eventcap $(CPPFLAGS) $(CFLAGS) $(LDFLAGS)
 
 clean :
 	rm -f kloak eventcap

README.md

@@ -1,4 +1,4 @@
-# anti keystroke deanonymization tool #
+# anti keystroke deanonymization tool
 
 kloak: *Keystroke-level online anonymization kernel*
 
@@ -23,8 +23,7 @@ Fedora:
 
 Debian:
 
-    $ sudo apt install devscripts
-    $ sudo mk-build-deps --remove --install
+    $ sudo apt install make pkg-config libsodium-dev libevdev-dev
 
 First, compile `kloak` and the event capture tool `eventcap`:
 
@@ -60,24 +59,24 @@ Notice that the lower bound on the random delay has to be raised when keys are p
 
 How to install `kloak` using apt-get
 
-1\. Download [Whonix's Signing Key]().
+1\. Download the APT Signing Key.
 
 ```
-wget https://www.whonix.org/patrick.asc
+wget https://www.whonix.org/keys/derivative.asc
 ```
 
-Users can [check Whonix Signing Key](https://www.whonix.org/wiki/Whonix_Signing_Key) for better security.
+Users can [check the Signing Key](https://www.whonix.org/wiki/Signing_Key) for better security.
 
-2\. Add Whonix's signing key.
+2\. Add the APT Signing Key.
 
 ```
-sudo apt-key --keyring /etc/apt/trusted.gpg.d/whonix.gpg add ~/patrick.asc
+sudo cp ~/derivative.asc /usr/share/keyrings/derivative.asc
 ```
 
-3\. Add Whonix's APT repository.
+3\. Add the derivative repository.
 
 ```
-echo "deb https://deb.whonix.org bullseye main contrib non-free" | sudo tee /etc/apt/sources.list.d/whonix.list
+echo "deb [signed-by=/usr/share/keyrings/derivative.asc] https://deb.whonix.org bookworm main contrib non-free" | sudo tee /etc/apt/sources.list.d/derivative.list
 ```
 
 4\. Update your package lists.
@@ -94,7 +93,7 @@ sudo apt-get install kloak
 
 ### How to build deb package
 
-Replace `apparmor-profile-torbrowser` with the actual name of this package with `kloak` and see [instructions](https://www.whonix.org/wiki/Dev/Build_Documentation/apparmor-profile-torbrowser).
+See the [Whonix package build documentation](https://www.whonix.org/wiki/Dev/Build_Documentation/security-misc). Replace the sample package name `security-misc` with `kloak` to download, build, and install kloak.
 
 ### Whonix contact and support
 
@@ -105,30 +104,8 @@ Replace `apparmor-profile-torbrowser` with the actual name of this package with
 
 `kloak` requires [donations](https://www.whonix.org/wiki/Donate) to stay alive!
 
-
 ### Troubleshooting
 
-#### Can't open input/output device
-
-`kloak` will attempt to find your keyboard device to read events from and the location of `uinput` to write events to. If `kloak` cannot find either the input device or output device, these must be specified with the `-r` and `-w` options, respectively.
-
-To find the keyboard device for reading events: determine which device file corresponds to the physical keyboard. Use `eventcap` (or some other event capture tool) and look for the device that generates events when keys are pressed. This will typically be one of `/dev/input/event[0-7]`. In this example, it's `/dev/input/event4`:
-
-    $ sudo ./eventcap /dev/input/event4
-    Reading From : /dev/input/event4 (AT Translated Set 2 keyboard)
-    Type:   4    Code:   4    Value:  15
-    Type:   1    Code:  15    Value:   0
-    Type:   0    Code:   0    Value:   0
-    Type:   4    Code:   4    Value:  56
-    Type:   1    Code:  56    Value:   0
-    Type:   0    Code:   0    Value:   0
-
-`uinput` is the [kernel module](http://thiemonge.org/getting-started-with-uinput) that allows user-land applications to create input devices. This is typically located at either `/dev/uinput` or `/dev/input/uinput`.
-
-Start `kloak` by specifying the input and output device files:
-
-    $ sudo ./kloak -r /dev/input/event4 -w /dev/uinput
-
 #### My keyboard seems very slow
 
 `kloak` works by introducing a random delay to each key press and release event. This requires temporarily buffering the event before it reaches the application (e.g., a text editor).
@@ -150,38 +127,17 @@ The full usage and options are:
       -s startup_timeout: time to wait (milliseconds) before startup. Default 100.
       -k csv_string: csv list of rescue key names to exit kloak in case the
          keyboard becomes unresponsive. Default is 'KEY_LEFTSHIFT,KEY_RIGHTSHIFT,KEY_ESC'.
+      -p: persistent mode (disable rescue key sequence)
       -v: verbose mode
 
 ## Try it out
 
-Consider these three different scenarios:
-* Train normal, test normal
-* Train normal, test kloak
-* Train `kloak`, test `kloak`
-
-*Train normal* means to train with normal typing behavior, i.e., without `kloak` running. At the enrollment page on the KeyTrac demo (demo no longer available), enter a username and password without `kloak` running, and then on the authenticate page, try authenticating. For example, the train normal/test normal result is:
-
-<div align="center">
-  <img src="figures/train-normal_test-normal.png"><br><br>
-</div>
-
-Start `kloak` and then try authenticating again. These results were obtained using a maximum delay of 200 ms (`-d 200`). The train normal/test `kloak` result is:
-
-<div align="center">
-  <img src="figures/train-normal_test-kloak.png"><br><br>
-</div>
-
-Enroll With `kloak` running and then try authenticating with `kloak` still running. Again, this is with a 200 ms maximum delay. The train `kloak`/test `kloak` result is:
-
-<div align="center">
-  <img src="figures/train-kloak_test-kloak.png"><br><br>
-</div>
-
-Your results may differ, especially in the train `kloak`/test `kloak` scenario. The train `kloak`/test `kloak` scenario is more difficult to anonymize than the train normal/test `kloak` scenario. This is because *kloak obfuscates your typing behavior, but does not make your typing behavior similar to other users*. This dilemma relates to the problem of user cooperation. It's easy to make your typing behavior look like something that it's not, but what should that be? If it's too unique, then the change does more harm then good, allowing you to be easily identified. Without the cooperation of other users, it's difficult to choose a behavior that's hard to distinguish.
+See the [kloak defense testing](https://www.whonix.org/wiki/Keystroke_Deanonymization#Kloak) instructions.
 
 ## Background
 
 `kloak` has two goals in mind:
+
 * Make it difficult for an adversary to identify a user
 * Make it difficult for an adversary to replicate a user's typing behavior
 

build.sh

@@ -0,0 +1,11 @@
+#!/bin/bash
+
+## For CodeQL autobuild
+
+set -x
+set -e
+
+sudo --non-interactive apt-get update --error-on=any
+sudo --non-interactive apt-get install --yes libevdev2 libevdev-dev libsodium23 libsodium-dev pkg-config
+
+make