Unl0kr
======

Unl0kr provides an extremely light weight on-screen keyboard for disk 
decryption. To do so, it relies on the following vendored libraries:
* LVGL: The Light and Versatile Graphics Library is a GUI toolkit for
  building embedded UIs, originally targeted at microcontrollers.
  Its [documentation](https://docs.lvgl.io/latest/en/html/porting/project.html)
  requires vendoring as the library is configured at build-time using a
  C header.

Additionally, the system relies on converting non-code files to C for use as LVGL
widgets and graphics:
* sq2lv_layouts.* are generated by upstream from 
  [squeekboard](https://packages.debian.org/sid/squeekboard) layouts.
* font_32.c is generated by upstream from the FontAwesome and OpenSans fonts 
  included in the source package.

For DFSG compliance, some upstream files have been removed:
* lvgl/src/font/*: Generated from (and thus derived works) built fonts that
  upstream LVGL don't document copyright for.
* lvgl/scripts/built_in_font/*: license is undocumented.
* lvgl/examples and lvgl/demos: These have been removed simply because they 
  are not required for Unl0kr.
* lvgl/env_support/cmsis-pack/*: Contains pre-built binaries not buildable without
  additional non-packaged software (CMSIS, Arm's Common Microcontroller Software 
  Interface Standard) and not required for Unl0kr.

Setting up Unl0kr
-----------------

Unl0kr is intended to prompt the user for their LUKS password during early
boot, but merely installing the package is not enough to make that happen.
In order for Unl0kr to actually show up, a couple additional steps are needed.

First, the /etc/crypttab file needs to be updated so that

  keyscript=/usr/share/initramfs-tools/scripts/unl0kr-keyscript

is included among the options for the various encrypted volumes. Multiple
options can be provided for each volume, and they must be separated with
commas. crypttab(5) fully documents the format of this file.

Next, it's necessary to regenerate the initramfs by running

  # update-initramfs -u

Assuming all the steps completed without errors, Unl0kr will be automatically
started for all subsequent boots.

F0rmz
=====

While the version of Buffybox packaged does contain F0rmz it has been excluded
from the Debian package for this release. A future release will include this
binary as a third binary package.