Skip to content

Trusted Personal Computers

The Hydra Suite was made with the Trusted Personal Computer (TPC) (portuguese translation) paradigm as it's starting point.

This guide documents the lifecycle of a TPC storage device, or a "TPS Cartridge":

Cartridge = TPS = Trusted Personal Storage

A TPS can usually be whatever removable block device like an SSD, microSD, M.2 etc.

The idea is that a number of TPCs can have interchangeable cartridges, as long as each cartridge has an unique name.

Parameters

Start by running the following commands in your terminal, adjusting to your case:

export HYDRA="hydra-name"
export DISK="disk-name"
export DEVICE="/dev/sdb"
export DOMAIN="`facter domain`"
export USER="`whoami`"
export DEST="/media/$DISK"
export CONFIG_FOLDER="`hydra $HYDRA folder`"

if [ "$USER" != "root" ]; then
  export SUDO="sudo"
fi

Provisioning a new cartridge

Random data

If you want to pre-fill your disk with random data, proceed as follows:

$SUDO dcfldd if=/dev/urandom of=$DEVICE

This can be done in a NAS as it may take days to finish, and the rest of the procedures from this document can be done from another TPC.

Configuration

If non-existing, create entries and keys:

hydra $HYDRA newnode $DISK tpc

Customize:

vim $CONFIG_FOLDER/config/provision/$DISK.conf
vim $CONFIG_FOLDER/puppet/config/node/$DISK.$DOMAIN.yaml
vim $CONFIG_FOLDER/puppet/config/secrets/node/$DISK.$DOMAIN.yaml

Secrets

Proceed adding other passwords and secrets at $CONFIG_FOLDER/puppet/config/secrets/node/$DISK.$DOMAIN, make sure to encode them with hiera-yaml:

hydra $HYDRA eyaml $DISK encrypt -q -o block -p -l some::password

If you already have the secret somewhere, you can use a construction like this which already adds the eyaml block into the hiera config file:

keyringer $HYDA decrypt /path/to/some/secret | \
  tr -d '\n' | \
  hydra $HYDRA eyaml $DISK encrypt -q -o block --stdin -l some::password >> \
  $CONFIG_FOLDER/puppet/config/secrets/node/$DISK.$DOMAIN.yaml

You can also ensure a fresh random passphrase is used, using your favourite generator like this:

head -c ${1:-20} /dev/urandom | base64 | \
  tr -d '\n' | \
  hydra $HYDRA eyaml $DISK encrypt -q -o block --stdin -l some::random::password >> \
  $CONFIG_FOLDER/puppet/config/secrets/node/$DISK.$DOMAIN.yaml

For passwd(5) and shadow(5) hashed passphrases, use something like this:

mkpasswd -m sha-512 | \
  tr -d '\n' | \
  hydra $HYDRA eyaml $DISK encrypt -q -o block --stdin -l some::random::password >> \
  $CONFIG_FOLDER/puppet/config/secrets/node/$DISK.$DOMAIN.yaml

Or this, for a random passphrase:

head -c ${1:-20} /dev/urandom | base64 | \
  mkpasswd -m sha-512 --stdin | \
  tr -d '\n' | \
  hydra $HYDRA eyaml $DISK encrypt -q -o block --stdin -l some::random::password >> \
  $CONFIG_FOLDER/puppet/config/secrets/node/$DISK.$DOMAIN.yaml

Installation

The proceed with the system installation, which should create all volumes in the TPS and setup the base Operating System:

hydra $HYDRA provision $DISK

Metadata

After installation, make sure to save metadata from the disk layout and LUKS headers, which can be useful during recovery procedures.

  1. Turn off the cartridge, and then plug it again in the TPC you're using. This will make sure device information is properly refreshed.

  2. Write down UUIDS, models and serials from the new disk. Examples:

    lsblk $DEVICE -n -o +UUID | keyringer $HYDRA encrypt nodes/$DISK.$DOMAIN/lsblk
udevadm info --query=all --name=$DEVICE | keyringer $HYDRA encrypt nodes/$DISK.$DOMAIN/udevadm

# For non-USB and non-microSD disks only
$SUDO hdparm -I $DEVICE   | keyringer $HYDRA encrypt nodes/$DISK.$DOMAIN/hdparm
$SUDO smartctl -i $DEVICE | keyringer $HYDRA encrypt nodes/$DISK.$DOMAIN/smartctl

  3. Save partition tables, the LUKS header and other relevant information:

    $SUDO LC_ALL=C sfdisk -d $DEVICE | keyringer $HYDRA encrypt nodes/$DISK.$DOMAIN/sfdisk

$SUDO cryptsetup luksDump /dev/mapper/$DISK-root | keyringer $HYDRA encrypt nodes/houdini.fluxo.info/luksDump-root
$SUDO cryptsetup luksDump /dev/mapper/$DISK-swap | keyringer $HYDRA encrypt nodes/houdini.fluxo.info/luksDump-swap

$SUDO cryptsetup luksHeaderBackup /dev/mapper/$DISK-root --header-backup-file luksHeaderBackup-root
$SUDO chown $(whoami) luksHeaderBackup-root
keyringer $HYDRA encrypt nodes/$DISK.$DOMAIN/luksHeaderBackup-root luksHeaderBackup-root
chmod +w luksHeaderBackup-root
wipe luksHeaderBackup-root

Other security measures

  • Optionally, configure ATA passphrases for the new disk. If so, make sure to save the passphrase in the keyring:
    keyringer $HYDRA encrypt nodes/$DISK.$DOMAIN/ata

Mounting

Use the following whenever you need to mount the cartridge in another system:

hydractl mount-media $DISK

This will make the volume available at /media/$DISK.

Initial user

These steps are needed to setup the encrypted home folder (the second level of encryption) before continuing the provisioning.

Setting up home encryption

If you're running this in an existing hydra-compatible TPC but you don't have your home folder encrypted, backup your data and then proceed running

hydractl ecryptfs-home

Syncing the user and encrypted home in the new cartridge

Then, with the new TPS cartridge mounted (hydractl mount-media $DISK), do the following to replicate your user and homedir there:

$SUDO chroot $DEST adduser $USER
$SUDO chroot $DEST usermod -a -G sudo $USER
$SUDO chroot $DEST apt install ecryptfs-utils -y

$SUDO mkdir -p $DEST/mnt/crypt/home
$SUDO mv       $DEST/home/$USER           $DEST/mnt/crypt/home/$USER
$SUDO ln -s -t $DEST/home                 /mnt/crypt/home/$USER/
$SUDO ln -s -t $DEST/mnt/crypt/home/$USER /home/.ecryptfs/$USER/.ecryptfs
$SUDO ln -s -t $DEST/mnt/crypt/home/$USER /home/.ecryptfs/$USER/.Private

$SUDO chroot $DEST chown -R $USER: /mnt/crypt/home/$USER

The procedure may be adapted if you're already running the system from the new TPS and is logged in there as root.

Syncing data

From another system, and with the cartridge mounted:

hydractl sync-tpc $DISK

This might involve a lot of data being transmitted. If you want sync-tpc to ignore all your QEMU virtual machine images hosted at /var/cache/quemu, setup a .sync-tpc-ignore like the following:

$SUDO mkdir -p $DEST/var/cache/qemu
$SUDO chown $USER: $DEST/var/cache/qemu
touch $DEST/var/cache/qemu/.sync-tpc-ignore

Check the backups for additional information.

Unmounting

Now that basic provisioning is completed, you can unmount the cartridge.

From another system, and with the cartridge mounted:

hydractl umount-media $DISK

Booting

The current provisioning procedure (as of 2024-02) may yield into a partially bootable system, and may need some additional manual steps right after installation:

hydractl mount-media $DISK
sudo chroot $DEST
update-initramfs -v -u
hydractl umount-media $DISK

During boot, at the (initramfs) prompt, type this to successfully unlock the encrypted volumes:

cryptsetup luksOpen /dev/mapper/${DISK}-root root
cryptsetup luksOpen /dev/mapper/${DISK}-swap swap
^Ctrl-D

Then, in the running system, do:

sudo update-initramfs -v -u

With these steps, the system's boot procedure was fixed.

But there are fixes be done at hydractl provision to produce fully working installations.

Deploy

Now it's time to boot the new system, log in with your user and deploy the complete configuration.

The following command will take care of the deployment:

hydra $HYDRA deploy localhost

Archives and backups

You can use a hydra-compatible archive/backup disk to setup working copies for existing archives:

export                 MEDIA=backup-disk-name
hydractl mount-media  $MEDIA
hydractl sync-backups $MEDIA
hydractl sync-media   $MEDIA

hydractl sync-media-initremotes localhost boxes hostname-nas1 hostname-nas2

Then add manually other archive remotes.

Compile

Make sure other nodes have some information on your cartridge by compiling collected data:

hydra $HYDRA compile

Adding a new hardware in the TPC pool

  • Proceed with homologating a new unit.
  • Provision, deploy, sync-media, sync-vms etc.
  • Add the devices' network MAC Addresses at 70-persistent-net.rules, then make sure to sync this in the other cartridges.

Decommissioning

To be documented.

Additional references

Implementation

These are implementation-specific references, especially issues, fixes and workarounds found while developing procedures for TPCs.

UEFI

Overview:

Coreboot versus UEFI:

UEFI versus Legacy:

Lenovo:

Issues:

Boot loader

Geral:

(Re)installation:

Full Disk Encryption (FDE) support:

Recovery:

Issues:

SecureBoot

Evil Maid Attack

Howtos

TRIM

Swap

Cryptsetup

Certification