These steps have been checked on a Debian install, other distributions should be similar but may differ on some of the details (specially on the [Configuring crypttab] section).
serveris the hostname of the server.
clientis the hostname of the client.
sda2is the encrypted drive.
First of all, install kxd on the server, usually via your distribution packages, or directly from source.
create-kxd-config, which will create the configuration
directories, and generate a self-signed key/cert pair for the server (valid
for 10 years).
Everything is in
Install kxc on the client machine, usually via your distribution packages, or directly from source.
kxc-add-key server sda2, which will create the configuration
directories, generate the client key/cert pair (valid for 10 years), and also
create an entry for an
client/sda2 key to be fetched from the server.
Everything is in
Finally, copy the server public certificate over, using
scp server:/etc/kxd/cert.pem /etc/kxc/sda2.server_cert.pem (or something
Adding the key to the server
On the server, run
kxd-add-client-key client sda2 to generate the basic
configuration for that client's key, including the key itself (generated
Then, copy the client public certificate over, using
scp client:/etc/kxc/cert.pem /etc/kxd/data/client/sda2/allowed_clients
(or something equivalent).
That allows the client to fetch the key.
Updating the drive's key
On the client, run
kxc-cryptsetup sda2 | wc -c to double-check that the
output length is as expected (you could also compare it by running sha256 or
Assuming that goes well, all you need is to add that key to your drives' key ring so it can be decrypted with it:
# Note we copy to /dev/shm which should not be written to disk. kxc-cryptsetup sda2 > /dev/shm/key cryptsetup luksAddKey /dev/sda2 /dev/shm/key rm /dev/shm/key
Note this adds a new key, but your existing ones are still valid. Always have more than one key, so if something goes wrong with kxd, you can still unlock the drive manually.
In order to get kxc to be run automatically to fetch the key, we need to edit
/etc/crypttab and tell it to use a keyscript:
sda2_crypt UUID=blah-blah-blah sda2 luks,keyscript=/usr/bin/kxc-cryptsetup ^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
sda2 field corresponds to the name we've been passing around in
previous sections. The
keyscript=/usr/bin/kxc-cryptsetup option is our way
of telling the cryptsetup infrastructure to use our script to fetch the key
for this target.
You can test that this works by using:
cryptdisks_stop sda2_crypt cryptdisks_start sda2_crypt
The second command should issue a request to your server to get the key.
update-initramfs -u if your device is the root device, or
it is needed very early in the boot process.