[[!meta title="A Keylock Security Model for kauth(9)"]]

Recently, generic support for electro-mechanical multi-position keylocks
in the kernel has been added to NetBSD.  Such locks can be turned into
various positions, usually up to three or four position.  They come with
a set of keys that are different in so far as not all positions can be
reached with all keys (which key can go up to which position is called
the "locking program").  With the new keylock support, such locks can be
used to tinker with the kernel security, much like the traditional
securelevel variable...

The number of keylock positions, the current keylock position, and the
overall keylock state can be read within the kernel using a set of
functions defined in
[keylock.h](http://cvsweb.de.netbsd.org/cgi-bin/cvsweb.cgi/src/sys/dev/keylock.h?rev=HEAD)
and userland
can access them through the <b>hw.keylock</b> sysctl hierarchy.

The following components have been added:

* <b>[[!template id=man name="gpiolock" section="4"]]</b>
a driver for GPIO attached keylocks.
 The driver registers with the in-kernel keylock "subsystem". See
[gpiolock.c](http://cvsweb.de.netbsd.org/cgi-bin/cvsweb.cgi/src/sys/dev/gpio/gpiolock.c?rev=HEAD).

* <b>secmodel_keylock</b>, a
[[!template id=man name="kauth" section="9"]]
security model that
authorizes based on the keylock "closedness".  Wheter the rightmost
(default) or leftmost position of the keylock means open can be
controlled using the <b>hw.keylock.order</b> sysctl variable. This
variable can only be changed if the keylock state is OPEN. See
[secmodel_keylock.c](http://cvsweb.de.netbsd.org/cgi-bin/cvsweb.cgi/src/sys/secmodel/keylock/secmodel_keylock.c?rev=HEAD).

The security model is started when a keylock driver registers and
stopped when there is no more keylock driver.  The keylock security
model is optional, keylock support can be used without the security
model as well (e.g. to provide keylock state to a userland applications.
Useful e.g. for POS applications).

The keylock state interpretation is done in
[keylock.c](http://cvsweb.de.netbsd.org/cgi-bin/cvsweb.cgi/src/sys/dev/keylock.c?rev=HEAD)
and not in the driver itself.  This
allows for adding support for multiple keylocks in the future.  The
hw.keylock.pos and hw.keylock.npos sysctl variable have debugging
character, the hw.keylock.state variable reflects the state and should
be used.

Currently, the keylock positions are interpreted as follows:  There are
maximum four positions, OPEN, SEMIOPEN, SEMICLOSE, CLOSE.  What exactly
that means leaves room for interpretation right now.... (experience will
show what makes sense in the end).

To enable the keylock support, the keylock security model, and the
[[!template id=man name="gpiolock" section="4"]]
driver, add the following lines to your
kernel configuration file:

	options KEYLOCK
	options secmodel_keylock
	gpiolock* at gpio?

Of course you must have at least one GPIO device in your system for the
[[!template id=man name="gpiolock" section="4"]]
driver to work and the lock must be
connected properly.

<b>Please keep in mind that this is an experimental feature...</b>