LKRG remote logging
===================

LKRG supports optional remote kernel message logging.  Once enabled, this logs
not only messages generated by LKRG, but also all other kernel messages.

The sending component is in the LKRG kernel module itself, whereas the
receiving and logging counterpart is in a userspace daemon.  There are also
additional userspace utilities.


Transport security
------------------

We currently use a one-way TCP stream, with transport security provided by our
usage of libhydrogen (bundled in here).  libhydrogen is "built using just two
cryptographic building blocks: the Curve25519 elliptic curve, and the Gimli
permutation."  It implements a number of Noise protocol handshake patterns, out
of which we currently use the most trivial one, "N".

As long as the server's secret key is not compromised, this protects
confidentiality and integrity of messages.  While our usage of a one-way TCP
stream (a write-only socket) is a great way to limit LKRG's remote attack
surface, it precludes implementation of forward secrecy, so a compromised
secret key can unfortunately be used to decrypt past sessions.

Replay protection is partial - messages from the middle of a (current or past)
TCP connection cannot be replayed on their own (won't be accepted by the
receiver even if the TCP layer is tricked to accept them), but an entire TCP
connection or its starting portion can be.

There's no explicit server authentication since the communication on top of TCP
is one-way, however security against a spoofed/MITM server is achieved through
the client only encrypting to the correct server's pre-configured public key.

There's currently no explicit client authentication (a major shortcoming to be
addressed), but only clients with knowledge of the server's public key can send
messages that would be accepted by the server.


How to use
----------

Please refer to the section "Remote logging configuration" in README for how to
enable remote logging in LKRG.

Please read below about the userspace tools to support LKRG remote logging.


Build requirements and building
-------------------------------

The build requirements for the userspace tools are a subset of what's needed to
build LKRG itself.  Currently, it's just GNU make and GCC.  You can build the
tools by simply running "make" in the "logger" directory, e.g. like this:

	make -C logger -j8

This will build three programs described below.


Installation
------------

To install the programs on the system globally, run:

	sudo make install

On systems with systemd, this also installs, but does not yet enable, a systemd
unit file for lkrg-logger.


Uninstalling
------------

Similarly to installation, you can uninstall these programs and the systemd
unit file with:

	sudo make uninstall


lkrg-keygen
-----------

Run this program once to obtain a public/secret keypair, which it prints as:

	LKRG_LOGGER_PK=64hexdigitshere
	LKRG_LOGGER_SK=64hexdigitshere

Use the 64 digits from LKRG_LOGGER_PK as value for LKRG's net_server_pk module
parameter.  Use the line LKRG_LOGGER_SK= including the 64 digits to set an
environment variable of this name for lkrg-logger.


lkrg-logger
-----------

This is the receiving and logging userspace daemon.  Currently, it is to be set
up and started via systemd like this:

	useradd -r lkrg-logger -d / -s /sbin/nologin
	mkdir /var/log/lkrg-logger
	chown lkrg-logger: /var/log/lkrg-logger

	umask 077
	lkrg-keygen > /etc/lkrg-logger.conf
	systemctl enable lkrg-logger
	systemctl start lkrg-logger

or instead of the last 4 commands above, started manually as root like this:

	LKRG_LOGGER_SK=64hexdigitshere lkrg-logger

Per-client log files will appear in the log directory once client connections
encrypting to the right public key arrive.  The filenames correspond to each
client's IPv4 address as seen by the server.


lkrg-logctl
-----------

A tool to process one lkrg-logger output file.  This program currently derives
each event's ISO timestamp from several recorded relative timestamps.
