menuimage

Description

Usage

Options

Exit_Codes

Prerequisites

Dependencies

Notes

Cryptroot-unlock

License

Changelog

Download

Donation

My_Other_Sites

My_Programs

Comments

unlock v0.8 [14 Nov 2018] - by Dominic

Description

This utility provides an easy way to enter the decrypt passphrase on a remote machine which has root encryption with 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 boots it loads an initramfs image from a small unencrypted boot partition and then waits for the encryption passphrase, without which it cannot read the main partition. If it has previously been suitably modified (see below) you can reach it remotely (by ssh) at this boot stage and enter the passphrase, which allows booting to complete.

From a remote client you can use unlock.sh to enter the passphrase, provided your public key (i.e. matching the private key used for ssh connection by unlock.sh) has previously been added to the encrypted machine's /etc/dropbear/initramfs/authorized_keys file 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 also use unlock.sh 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.sh -t generates no text output, otherwise it will show an appropriate message.

Usage

./unlock.sh [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 used by dropbear in initramfs 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.sh -s' to the specified 'file'
-t - test status of remote machine and exit with code - silent if running normally
-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.sh 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 if you use the alternate or netboot installer [file: mini.iso] and select 'Guided - use entire disk and set up encrypted LVM'.) By default, 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 22.04; for 20.04 and earlier use /etc/dropbear-initramfs/authorized_keys instead of /etc/dropbear/initramfs/authorized_keys):

sudo -i # become root (if not already)
apt-get install dropbear-initramfs # check/install necessary software
# add public keys for remote users who could run unlock.sh here, one per line:
nano /etc/dropbear/initramfs/authorized_keys
sed -i -e '$a\' /etc/dropbear/initramfs/authorized_keys # ensure file ends with EOL
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 unlock.sh 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 thus (a non-zero exit code indicates a wrong passphrase):

cryptsetup open $(blkid|grep crypto_LUKS|cut -d: -f1|head -n1) x --test-passphrase --tries 1; echo $?

Depending on the remote machine's network configuration and resulting state (a) during booting and (b) after booting has completed, these two states may have different ips or accept connections from different ports; if so, after you have successfully entered the passphrase unlock.sh will report that it was unable to connect and ask you to check if the remote machine is switched on - the remote machine may be working fine but with a different ip address or port. So try to ensure that the same ip address is allocated when booting (see below) as when fully 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 'ip=' in variable GRUB_CMDLINE_LINUX in /etc/default/grub and then run update-grub. The parameters are ip=client-ip:[server-ip]:gateway-ip:netmask:[hostname]:device:autoconf - for more info see https://www.kernel.org/doc/Documentation/filesystems/nfs/nfsroot.txt. Never specify server-ip; and do not specify a hostname because unlock.sh depends on the hostname during booting being '(none)'. Examples:

GRUB_CMDLINE_LINUX="ip=:::::eth0:dhcp"
GRUB_CMDLINE_LINUX="ip=192.0.2.62::192.0.2.1:255.255.255.192::eth0:none"

And afterwards run

update-grub


To specify a non-standard ssh port at boot time (i.e. not 22), add a line in /etc/dropbear/initramfs/dropbear.conf (in Ubuntu 20.04 and earlier: /etc/dropbear-initramfs/config) like

DROPBEAR_OPTIONS=-p 4748

And then update initramfs

update-initramfs -u -k all

Cryptroot-unlock

Whereas unlock.sh runs under bash on the client machine, cryptroot-unlock resides by default in the initramfs package on the encrypted machine and can be run using SSH from a client with any OS. cryptroot-unlock has the same prerequisites (see above) as unlock.sh. Subject to that, here are examples of how, instead of using unlock.sh, cryptroot-unlock can be run from a remote client logging in with SSH:

One-line example to run remotely (i.e. on client machine) to remote machine 192.168.20.88 under Linux or Cygwin or WSL:

ssh -t -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no root@192.168.20.88 cryptroot-unlock

Another one-line example but using a non-default private key file:

ssh -ti /path/to/private_key_file -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no root@192.168.20.88 cryptroot-unlock

or under Windows using plink:

plink.exe -t -i C:\path\private_key_file.ppk root@192.168.20.88 cryptroot-unlock

License

Copyright © 2023 Dominic Raferd. Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at https://www.apache.org/licenses/LICENSE-2.0. Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Changelog

0.8 [14 Nov 2018] - silently correct if user supplies ip address in form name@n.n.n.n
0.7 [09 Nov 2018] - modify instructions to reference cryptroot-unlock, remove references to pass.sh
0.6 [07 Nov 2018] - correct instructions for location of authorized_keys file
0.5 [06 Nov 2018] - bugfix -i option
0.4 [30 May 2017] - bugfix -t option
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.sh

Donation

I have provided this software free gratis and for nothing. If you would like to thank me with a contribution, please let me know and I will send you a link. Thank you!

My Other Sites

My Programs

Here is a selection of some (other) programs I have written, most of which run under GNU/Linux 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 and tested on an x86-based Linux server, they should run on a Raspberry Pi, and many can run under Windows using Windows Subsystem for Linux (WSL) or 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

Miscellaneous Programs

Comments

This section is closed. If you have a question, please submit it by email, thank you.

No comments yet for '/programs/help/unlock.sh.php'