Dropbear-initramfs for LUKS Remote Unlocking

This repository documents the setup and configuration of dropbear-initramfs to enable remote SSH access during early boot for unlocking LUKS-encrypted root filesystems. The configuration ensures that dropbear uses the same SSH host keys as the main OpenSSH server to prevent SSH key warnings.

Overview

When a Linux system uses LUKS (Linux Unified Key Setup) encryption for the root filesystem, the encryption passphrase must be entered during the boot process before the system can fully boot. This setup allows you to:

• Remotely unlock your LUKS-encrypted system via SSH during early boot
• Use the same SSH host keys as your main OpenSSH server to avoid key mismatch warnings
• Securely access the system before the main SSH daemon starts

Prerequisites

• A Linux system with LUKS-encrypted root filesystem
• OpenSSH server installed and configured
• Root access to the system
• Dropbear-initramfs package available (Debian/Ubuntu)

Installation

1. Install dropbear-initramfs

apt install dropbear-initramfs

2. Configure Dropbear Options

Navigate to the dropbear configuration directory:

cd /etc/dropbear/initramfs

Edit the configuration file:

nano dropbear.conf

Configure the DROPBEAR_OPTIONS variable. Example configuration:

DROPBEAR_OPTIONS="-I 180 -j -k -c cryptroot-unlock"

Option explanations:

• -I 180: Disconnect idle sessions after 180 seconds of inactivity
• -j: Disable local port forwarding
• -k: Disable remote port forwarding
• -c cryptroot-unlock: Force execution of the cryptroot-unlock command (used to unlock LUKS)

For a complete list of available options, refer to the dropbear(8) manual page.

3. Convert and Copy SSH Host Keys

To prevent SSH key warnings, we'll use the same host keys as your OpenSSH server. Dropbear requires keys in its own format, so we need to convert them using dropbearconvert.

Convert private keys:

dropbearconvert openssh dropbear /etc/ssh/ssh_host_ecdsa_key dropbear_ecdsa_host_key
dropbearconvert openssh dropbear /etc/ssh/ssh_host_ed25519_key dropbear_ed25519_host_key
dropbearconvert openssh dropbear /etc/ssh/ssh_host_rsa_key dropbear_rsa_host_key

Copy public keys (same format):

cp /etc/ssh/ssh_host_ecdsa_key.pub dropbear_ecdsa_host_key.pub
cp /etc/ssh/ssh_host_ed25519_key.pub dropbear_ed25519_host_key.pub
cp /etc/ssh/ssh_host_rsa_key.pub dropbear_rsa_host_key.pub

Note: The dropbearconvert utility converts between Dropbear and OpenSSH private key formats. For more information, see the dropbearconvert(1) manual page.

4. Configure Authorized Keys

Copy your authorized SSH keys for root access:

cp /root/.ssh/authorized_keys authorized_keys

Alternatively, you can create a dedicated authorized_keys file with only the keys needed for remote unlocking.

5. Update Initramfs

After configuration, rebuild the initramfs to include the dropbear SSH server:

update-initramfs -u

Usage

Connecting During Boot

1. Boot your system and wait for the initramfs to load
2. Connect via SSH using the root user:

   ssh root@<system-ip>
   

3. You will be automatically prompted to enter the LUKS passphrase via the cryptroot-unlock command
4. Enter your LUKS encryption passphrase
5. The system will continue booting normally

Network Configuration

If your system uses a static IP address, you may need to configure networking in the initramfs. This can be done via:

• GRUB configuration: Add kernel parameters for network configuration
• Initramfs hooks: Configure network settings in initramfs scripts

For DHCP, networking should work automatically if configured in your system.

Security Considerations

1. Key Management: The SSH host keys are stored in the initramfs. Ensure your initramfs is properly secured.

2. Authorized Keys: Only include necessary SSH public keys in the authorized_keys file. Limit access to trusted users.

3. Idle Timeout: The -I 180 option disconnects idle sessions after 180 seconds, reducing the window for unauthorized access.

4. Port Forwarding: The -j and -k options disable port forwarding, limiting the attack surface.

5. Forced Command: The -c cryptroot-unlock option ensures users can only unlock the system, not execute arbitrary commands.

6. Network Security: Consider restricting network access to the dropbear SSH service using firewall rules.

Troubleshooting

SSH Key Warnings

If you see SSH key warnings, ensure:

• All host keys have been properly converted and copied
• The initramfs has been updated after key changes
• You're connecting to the same IP address

Cannot Connect During Boot

• Verify that dropbear is included in the initramfs: lsinitramfs /boot/initrd.img-* | grep dropbear
• Check network configuration in the initramfs
• Verify firewall rules allow SSH connections
• Check system logs: dmesg | grep dropbear

Passphrase Not Accepted

• Ensure you're using the correct LUKS passphrase
• Verify that the cryptsetup hook is properly configured in the initramfs
• Check for keyboard layout issues during early boot

References

• Dropbear SSH - Official Dropbear website
• Dropbear GitHub Repository - Source code and releases
• dropbear(8) Manual Page - Complete option reference
• dropbearconvert(1) Manual Page - Key conversion utility
• LUKS / cryptsetup - Official LUKS documentation
• cryptsetup(8) Manual Page - LUKS management commands
• Debian dropbear-initramfs Package - Package information

License

This documentation is provided as-is for informational purposes. Dropbear is distributed under an MIT-style license. See the official Dropbear website for license details.

Contributing

If you find errors or have improvements to suggest, please open an issue or submit a pull request.