Opencrypt(7)

NAME
opencrypt — automatically open crypted partitions during boot

DESCRIPTION

Opencrypt can use one or more keys, dispatched on different devices and/or servers on a network, to open automatically the crypted partitions during boot. Keys can be the same or different for each partition to open.

Opencrypt will try to open all crypted partitions found in /etc/crypttab, not only the root partition. For each partition to open, opencrypt will first try to find keys on unencrypted devices (USB stick, etc). Opencrypt will then search missing keys on network. If the partition could not be opened, opencrypt will ask a password on keyboard.

Opencrypt can search external keys on various locations. It will search them in the order of appearance in the configuration file.

It will search keys until all are found. Keys will then be concatenated to create the key actually used by cryptsetup. They will be concatenated in the order of appearance in the configuration file.

If all parameters are left empty, opencrypt will search unencrypted devices for some filenames and fallback asking a keyboard password.

FIRST TRY

The default configuration provided (actually it is fully commented out!) will let you enter a password with your keyboard. So for a first try, just let /etc/opencrypt/opencrypt.conf as it is, or perhaps set VERBOSE="1" to get more details, and reboot on the initrd freshly cooked during the package installation. You can then analyse logs in /run/initramfs/opencrypt.log.

CONFIGURATION

Using opencrypt in initrd presume that /boot is on a separate and not encrypted partition. If it is not the case opening /boot would be in the bootloader (e.g. grub).

All parameters are set in /etc/opencrypt/opencrypt.conf. This file is used when building initrd and during boot. See opencrypt.conf(5) for full details and examples.

Whatever you set in opencrypt.conf, opencrypt will not freeze during search and will fall back asking for a keyboard password. After rebooting you can check logs in /run/initramfs/opencrypt.log.

If you change opencrypt.conf you have to run update-initramfs to update your initrd with all that is needed:

    update-initramfs -u -k VERSION

update-initramfs provides a auto-completion on the version. So just use TAB to see installed versions.

INSTALL

  Warning

It is strongly advised to keep a separate slot with a keyboard key and to use KEYBOARDKEYSLOT parameter in opencrypt.conf. This way you can test opencrypt without risk to lock your partition.

  Install keys

To plainly use automatic opening, keys must be installed on external medium. You can put keys:

- on a device in the root directory in REMOTEDIR/REMOTEFILE

- on a SSH server reached with REMOTEIP:REMOTEDIR/REMOTEFILE

- on a web server reached with https://REMOTEIP/REMOTEDIR/REMOTEFILE

If the key filename is not configured with REMOTEFILE in opencrypt.conf, the key searched will depend on what is found in crypttab:

- with a device configured by UUID, LABEL, PARTUUID or PARTLABEL the file searched will be UUID|LABEL|PARTUUID|PARTLABEL.key (use blkid to find values)

- with a device configured by anme (/dev/sda1, etc) the file searched will be BASENAME.key (i.e. for /dev/sda1 opencrypt will search sda1.key)

When searching keys on devices, if REMOTEFILE and REMOTEDIR are left empty or have the same content, only the first key found will be used as the others would be the same on all devices. If you want to use 2 different keys on devices you have to set different REMOTEDIR. If REMOTEIP is empty only the first key will be used, without concatenate another key, to open the crypt partition.

  Other files

opencrypt will need some other files for particular configurations.

* Setup a firewall with nft:

    /etc/opencrypt/nftables.conf       ruleset for nft

A basic set of rules is provided in /usr/share/doc/opencrypt/examples/nftables.conf

You will also need to install nftables with:

    apt install nftables

* Setup a firewall with iptables:

    /etc/opencrypt/iptables.conf       ruleset for iptables-restore
    and/or
    /etc/opencrypt/ip6tables.conf      ruleset for ip6tables-restore

You will also need to install iptables with:

    apt install iptables

* Using wget/wget2/curl :

    /etc/opencrypt/opencrypt-ca.pem    CA certificates for validating servers certificates
    /etc/opencrypt/opencrypt-cert.pem  private key and certificate sent to servers

You need to do:

    chmod 600 /etc/opencrypt/opencrypt-cert.pem

You will also need to install wget (ou wget2 ou curl) with:

    apt install wget

* Using ssh :

    /etc/opencrypt/known_hosts         known_hosts to validate servers
    /etc/opencrypt/opencrypt-ssh       private key which must be without password
    /etc/opencrypt/opencrypt-ssh.pub   public key

You need to do:

    chmod 600 /etc/opencrypt/known_hosts /etc/opencrypt/opencrypt-ssh

You will also need to install openssh-client with:

    apt install openssh-client

Renanming crypt mapping

If you rename mappings, update-initramfs will not correctly add crypt devices in the initrd crypttab and fstab.

opencrypt makes a copy of your current /etc/crypttab when creating initrd and will use it during boot for additional mapping if needed. This means that you can simply change names in /etc/crypttab and /etc/fstab, and redo you initrd.

Useful commands

Here are some useful commands. Do not use them as is, you have to adjust them to your system.

* format a crypt partition

First create a partition with GPT table using fdisk

    cryptsetup --verbose luksFormat --verify-passphrase /dev/sda1

A password will be asked and set into slot 0

* Open a crypt partition and install a filesystem

    cryptsetup luksOpen /dev/sda1 TMP
    mkfs.xfs /dev/mapper/TMP

* Close a crypt partition

    cryptsetup close TMP

* Add keys

Asking an existing password:

    cryptsetup luksAddKey --new-keyfile sda1.key --new-key-slot=1 /dev/sda1

Using another key (in sda1.key) already installed:

    cryptsetup luksAddKey --key-file sda1.key --new-keyfile sda1.key2 --new-key-slot=2 /dev/sda1

* Backup the header

A backup could be needed if a problem occurs.

    cryptsetup luksHeaderBackup /dev/sda1 --header-backup-file sda1.backup

* Update your initrd

(update-initramfs has auto-completion for installed versions after typing -k)

    update-initramfs -u -k VERSION

* Parse initrd

    mkdir ramfs
    unmkinitramfs /boot/initrd.img-VERSION ramfs

* List partitions with UUID

    blkid

* Create random key with 64 chars

    dd if=/dev/urandom bs=1 count=64 of=filename.key conv=excl,fsync

* Test access to a web server

The web server is supposed to have an index.html that could be accessed as the keys. If not you should replace index.html in the commands below with the path to your keys as setup in opencrypt.conf.

openssl needs to split /etc/opencrypt/opencrypt-cert.pem into a private key and a certificate. openssl should answer "SSL_connect:SSL negotiation finished successfully".

    openssl s_client -connect 192.168.1.34:443 -key private key -cert certificate -CAfile /etc/opencrypt/opencrypt-ca.pem -state

wget should answer "WARNING: Could not save SSL session data" as we do not send certificate.

    wget --no-check-certificate https://192.168.1.34/index.html

wget should get index.html without error.

    wget --ca-certificate /etc/opencrypt/opencrypt-ca.pem --certificate /etc/opencrypt/opencrypt-cert.pem  https://192.168.1.34/index.html
    curl -vvv --cacert /etc/opencrypt/opencrypt-ca.pem --cert /etc/opencrypt/opencrypt-cert.pem https://192.168.1.34/index.html

SEE ALSO

opencrypt.conf(5), cryptsetup(8), crypttab(5), update-initramfs(8), more documentation in /usr/share/doc/opencrypt.

AUTHOR

This manual page was written by Michel Verdier <michel@verdier.net> for the Debian system (and may be used by others). Permission is granted to copy, distribute and/or modify this document under the terms of the GNU General Public License, version 3 or any later version published by the Free Software Foundation.

On Debian systems, the complete text of the GNU General Public License can be found in /usr/share/common-licenses/GPL-3.