menuimage

Description

Usage

Options

Exit_Codes

Prerequisites

Dependencies

Notes

Changelog

Download

My_Other_Sites

My_Programs

Comments

unlock v0.3 [20 Apr 2017] - by Dominic

Description

This utility provides an easy way to enter the decrypt passphrase on a remote machine which has root dm-crypt+LUKS (e.g. as set up at Debian or Ubuntu installation if you select 'encrypted LVM') - so that local access is not required when booting the machine.

When the encrypted machine (suitably-modified - see below) boots it starts a little ssh server (dropbear) and waits for the passphrase: with local access you see the ip address but if you only have remote access you will have to find it some other way - to make this easier, set the ip on the encrypted machine as static or ensure that your DHCP server always allocates the encrypted machine the same ip address.

From a remote client you can use this utility 'unlock' to enter the passphrase, provided your public key (i.e. matching the private key used for ssh connection by 'unlock') has previously been into the encrypted machine's /etc/initramfs-tools/root/.ssh/authorized_keys and its initramfs has then been updated (see below). Please note this means there are two requirements for ability to remote boot the encrypted machine: you must know the passphrase *and* your public key must be pre-loaded on the encrypted machine.

You can use 'unlock' in test mode (-t) in a cron job to monitor the encrypted machine and warn you if it ceases to be fully available: if all is well then running unlock -t generates no text output, otherwise it will show an appropriate message.

Usage

./unlock [options] ip.address.of.remote.encrypted.machine

Options

-d - debug mode (implementation may vary)
-h - show this help and exit
-i file - specify private key identity file (default: selected automatically by ssh)
-l - show changelog and exit
-p n - where 'n' is the ssh port on the encrypted machine (default: 22)
-s file - test status of remote machine and output text if status has changed since the preceding run of 'unlock -s' to the specified 'file'
-t - test status of remote machine and exit - silent if running normally (exit code 0: running normally, code 1: error or machine is off, code 2: awaiting passphrase)
-v - show passphrase on console as you enter it

Exit Codes

0 - remote machine is running normally
1 - some error occurred or remote machine is off/unresponsive
2 - remote machine is still awaiting passphrase

Prerequisites

'unlock' is designed for a remote machine that has dm-crypt + LUKS on the root system so that it cannot be started up without the pre-set passphrase being entered. (The process of setting up a machine for dm-crypt + LUKS is not covered here, but it can most easily be done on Debian or Ubuntu using the automatic installer by selecting 'Guided - use entire disk and set up encrypted LVM'.) Normally booting such an encrypted machine requires local access in order to enter the passphrase, but remote access at this stage is possible by setting up the encrypted machine thus (tested under Ubuntu 16.04.2):

sudo -i # become root (if not already)
apt-get install openssh-server dropbear # check/install necessary software
# add public keys for remote users who could run unlock here, one per line:
nano /etc/initramfs-tools/root/.ssh/authorized_keys
update-initramfs -u -k all # update boot-time filesystem
hostname -I # note the ip address, please ensure it won't change on reboot

Dependencies

bash grep sed ssh

Notes

If you do not know the passphrase, or if you do not have a private key that matches a public key previously set up for the encrypted machine's initramfs, then utility 'unlock' cannot help you; you can get remote access only to the initial boot stage of the encrypted machine and it will be impossible to access the main system or data. If you have the passphrase but not a suitable private key, you will require local access to the encrypted machine in order to start it up fully.

More information about remote booting with dmcrypt + LUKS can be found at:
https://ubuntuforums.org/archive/index.php/t-2085267.html
http://blog.neutrino.es/2011/unlocking-a-luks-encrypted-root-partition-remotely-via-ssh/
https://www.adfinis-sygroup.ch/blog/en/decrypt-luks-devices-remotely-via-dropbear-ssh/

For a tool for converting an existing unencrypted partition to dm-crypt+LUKS (must be offline) see:
http://johndoe31415.github.io/luksipc

You can test a passphrase on an *already-mounted* dm-crypt + LUKS partition. In this example, /dev/sda5 is encrypted (as /dev/sda5_crypt), and the 'x' can be anything (required but ignored). A non-zero exit code indicates a wrong passphrase:
cryptsetup open /dev/sda5 x --test-passphrase --tries 1; echo $?

Depending on the remote machine's network configuration when booting and when fully loaded, these two states may have different ips; if so, after you have successfully entered the passphrase 'unlock' will report that it was unable to connect and ask you to check if the remote machine is switched on when actually it is working fine, but at a different ip address. You are advised to ensure that the same ip address is allocated when booting (see below) and when full booted (e.g. per /etc/network/interfaces), and is allocated in the same way.

To specify ip parameters at boot time (i.e. running from initramfs) set parameter 'ip=' in GRUB_CMDLINE_LINUX in /etc/default/grub and then run update-grub. The parameters are ip=client-ip:[server-ip]:gw-ip:netmask:[hostname]:device:autoconf - for more info see https://www.kernel.org/doc/Documentation/filesystems/nfs/nfsroot.txt and https://www.eugenemdavis.com/set-static-ip-initramfs.html. Never specify server-ip; and do not specify a hostname because 'unlock' depends on the hostname when booting being '(none)'. Examples:
GRUB_CMDLINE_LINUX="ip=:::::eth0:dhcp"
GRUB_CMDLINE_LINUX="ip=192.0.2.1::192.0.2.62:255.255.255.192::eth0:none"

Changelog

0.3 [20 Apr 2017] - add -s option, other fixes
0.2 [12 Apr 2017] - updated help, add -i and -t options, several other fixes
0.1 [04 Apr 2017] - initial version

Download unlock

My Other Sites

My Programs

Here is a selection of some (other) programs I have written, most of which run from the command line (CLI), are freely available and can be obtained by clicking on the links. Dependencies are shown and while in most cases written for a conventional Linux server, they should run even on a Raspberry Pi, and many can run under Windows using Cygwin. Email me if you have problems or questions, or if you think I could help with a programming requirement.

Backup Utilities

Debian/Ubuntu kernel and LVM Utilities

Dellmont / Three / Giffgaff / Vodafone - VoIP and Mobile Phone Account Utilities

Miscellaneous Programs

Comments

No comments yet
*Name:
Email:
Hide my email
*Text:
 
Powered by Scriptsmill Comments Script