b8659ae8fc
Mixing terminal output and lists isn't apparently well supported (or I cannot figure out how to do it). Change text a bit as a workaround.
134 lines
6.5 KiB
Markdown
134 lines
6.5 KiB
Markdown
Disclaimer
|
|
==========
|
|
**Warning** luksrku is currently *highly* experimental software. It is not
|
|
intended for production use yet. It is released following the "release early,
|
|
release often" philosophy in the hope to get valuable feedback for possible
|
|
areas of improvement. Please only use it when you're pretty certain that you
|
|
know what you're doing. Better yet, only use it after code review. If you've
|
|
reviewed my code, please let me know. I'm very interested in any and all
|
|
feedback. Drop it at joe@johannes-bauer.com, please. Thanks!
|
|
|
|
luksrku
|
|
=======
|
|
luksrku is a tool that allows you to remotely unlock LUKS disks during bootup.
|
|
The intention is to have headless systems running and you should be able to
|
|
remotely unlock their LUKS cryptographic file systems when you know they have
|
|
been (legitimately) rebooted. This works as follows: The *TLS server* runs on
|
|
the computer which needs unlocking. This computer broadcasts a UDP packet onto
|
|
the network indicating that it needs unlocking. The *TLS client* which knows
|
|
the LUKS passphrase then catches that packet, connect to the server and sends
|
|
the passphrase. The TLS configuration that is used ensures mutual
|
|
authentication and perfect forward secrecy. Concretely, TLS v1.2 is used with a
|
|
ECDHE handshake on Curve25519 and using the ECDHE-PSK-CHACHA20-POLY1305 cipher
|
|
suite. For authentication, a 256 bit long random PSK is used. The passphrase
|
|
for unlocking should be in a own keyslot (i.e., do not use a passphrase which
|
|
you remember).
|
|
|
|
Configuration
|
|
=============
|
|
Clients and servers use a configuration file. This is originally a text file
|
|
that is then converted to encrypted binary format using the luksrku-config
|
|
tool. This binary configuration file is encrypted using AES256-GCM, uses a 128
|
|
bit randomized initialization vector and authenticated with a 128 bit
|
|
authentication tag. The key derivation function which is used to derive the 256
|
|
bit AES key from the passphrase is scrypt with N = 131072, r = 8, p = 1.
|
|
|
|
Storing in a binary format serves two purposes:
|
|
1. Error-prone parsing of human-modifiable text is done in a separate
|
|
application. These chunks of code are not linked into the luksrku binary.
|
|
2. It allows for easy encryption.
|
|
|
|
The server key database contains no secrets, yet it is encrypted nevertheless.
|
|
The sole purpose is to keep the number of alternative code paths minimal. There
|
|
is no technical reason to encrypt the server configuration file, but again: it
|
|
contains *no* secrets. Using the same storage for server and client was maybe
|
|
an awkward design choice, but this is something that is ugly, but not
|
|
security-critical.
|
|
|
|
The client key database contains the LUKS keys, therefore it is advisable to
|
|
keep it encrypted with a passphrase. Only if this passphrase is correctly
|
|
entered on the client, the password can be decrypted on the client and
|
|
transmitted to the server. Note that care is taken to ensure no
|
|
length-of-message side channels reveal information about the underlying LUKS
|
|
passphrase. Therefore the transmitted messages are always of the same length.
|
|
|
|
The PSK that is used to communicate between client and server ensures mutual
|
|
authentication. If the PSK is stolen by an adversary, that adversary can simply
|
|
pose as a server and ask the client for the LUKS key. Therefore it is integral
|
|
that this PSK is kept safe. Passive attacks (i.e., where the adversary is only
|
|
eavesdropping on communication), however, are not compromised because the TLS
|
|
channel provides PFS.
|
|
|
|
Prerequisites
|
|
=============
|
|
Since the used cryptography (such as ECDH on Curve25519 and the
|
|
ECDHE-PSK-CHACHA20-POLY1305 cipher suite) are fairly new, support for at least
|
|
OpenSSL-1.1.0 is essential.
|
|
|
|
|
|
Example
|
|
=======
|
|
This is a very crude example. Feel free to improve it and send a PR. Let's say
|
|
we want to unlock the crypt-root of a headless system. I.e., only one LUKS
|
|
partition that should be unlocked. That LUKS partition has the UUID of
|
|
952ebed9-5256-4b4c-9de5-7f8829b4a74a (use blkid to find out). This is what we
|
|
can do:
|
|
|
|
1. Build >=OpenSSL-1.1.0 (e.g., using the provided ./build_openssl command)
|
|
2. Build and install luksrku: make && sudo make install
|
|
3. Generate the keyfiles. For this we use the provided gen_config script:
|
|
|
|
```
|
|
Disk UUID : 952ebed9-5256-4b4c-9de5-7f8829b4a74a
|
|
Disk name : crypt-root
|
|
Suggestion: TDFV6Z6XyDQ52ASswVFSEl8mrVfnH9F5b
|
|
Passphrase:
|
|
|
|
Disk UUID :
|
|
# server.txt
|
|
# Host UUID Host PSK Disk UUIDs
|
|
d66f96fc-7056-46e1-aea6-0f3d705cd3bc d94f3fc6c3507123bda4034dd8c865a1b4cf9870bda50e9ed9f861621d581017 952ebed9-5256-4b4c-9de5-7f8829b4a74a=crypt-root
|
|
|
|
# client.txt
|
|
# Host UUID Host PSK Disk UUIDs
|
|
d66f96fc-7056-46e1-aea6-0f3d705cd3bc d94f3fc6c3507123bda4034dd8c865a1b4cf9870bda50e9ed9f861621d581017 952ebed9-5256-4b4c-9de5-7f8829b4a74a=54444656365a3658794451353241537377564653456c386d7256666e4839463562
|
|
```
|
|
|
|
4. We want to use the suggested passphrase, which should contain 192 bits of
|
|
entropy. For this, ee use cryptsetup luksAddKey to add the suggested
|
|
passphrase to the LUKS keyring on the server.
|
|
5. The config script has given suggestions for server.txt and client.txt. We
|
|
copy the respective contents into the files.
|
|
6. Then we create the client and server binary configuration files:
|
|
|
|
```
|
|
$ luksrku-config server server.txt server.bin
|
|
Successfully read key file with 1 entries.
|
|
$ luksrku-config client client.txt client.bin
|
|
Successfully read key file with 1 entries.
|
|
Passphrase to encrypt keyfile:
|
|
```
|
|
|
|
7. Now we'll have a server.bin and password-protected client.bin. On the
|
|
server machine (i.e., the one with the LUKS disk) we copy server.bin to
|
|
/etc/luksrku-server.bin.
|
|
8. On the server, we modify the luksrku-script in the initramfs/ subdirectory
|
|
to fit the NIC of the server and the IP address we want (this is really
|
|
ugly at the moment and needs to be fixed ASAP, but it is what it is now).
|
|
9. On the server, then run the "./install" script as root which will install
|
|
initramfs hooks.
|
|
10. On the server, update the initramfs (update-initramfs -u). Previously make
|
|
a copy of your initramfs so that you can boot your system in case things
|
|
go wrong (which they will, trust me).
|
|
11. Boot the server. If everything went fine (it won't at the first run), it
|
|
will now broadcast UDP packets onto the network indicating its presence.
|
|
These packets will be sent to UDP port 23170.
|
|
12. On the client, start the client to unlock the server's key:
|
|
|
|
```
|
|
$ luksrku --client-mode -k client.bin
|
|
Keyfile password:
|
|
```
|
|
|
|
|