{"id":20115484,"url":"https://github.com/viktorstiskala/cryptsetup-ssh-unlocker","last_synced_at":"2025-05-06T13:32:44.379Z","repository":{"id":57470854,"uuid":"106322502","full_name":"ViktorStiskala/cryptsetup-ssh-unlocker","owner":"ViktorStiskala","description":"Utility for unattended remote unlock of LUKS encrypted LVM using SSH and cryptsetup","archived":false,"fork":false,"pushed_at":"2018-10-09T17:51:53.000Z","size":16,"stargazers_count":21,"open_issues_count":1,"forks_count":3,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-05-05T21:00:54.783Z","etag":null,"topics":["cryptsetup","disk-encryption","dm-crypt","dropbear","luks","ssh"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ViktorStiskala.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-10-09T18:49:04.000Z","updated_at":"2025-04-11T09:27:40.000Z","dependencies_parsed_at":"2022-09-20T12:22:58.995Z","dependency_job_id":null,"html_url":"https://github.com/ViktorStiskala/cryptsetup-ssh-unlocker","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ViktorStiskala%2Fcryptsetup-ssh-unlocker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ViktorStiskala%2Fcryptsetup-ssh-unlocker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ViktorStiskala%2Fcryptsetup-ssh-unlocker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ViktorStiskala%2Fcryptsetup-ssh-unlocker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ViktorStiskala","download_url":"https://codeload.github.com/ViktorStiskala/cryptsetup-ssh-unlocker/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252693716,"owners_count":21789747,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cryptsetup","disk-encryption","dm-crypt","dropbear","luks","ssh"],"created_at":"2024-11-13T18:35:25.545Z","updated_at":"2025-05-06T13:32:44.124Z","avatar_url":"https://github.com/ViktorStiskala.png","language":"Python","readme":"# Cryptsetup SSH unlocker\n\nUtility for unattended remote unlock of LUKS encrypted LVM/root disk partition using SSH and cryptsetup.\nPeriodically polls defined servers for open SSH port, then tries to unlock the server using cryptsetup.\nRequires `dropbear` or any other SSH server which could be run from initial ramdisk.\n\n## Is it secure?\nThis utility should run from independent server (possibly VPS), thus separating all passphrases and SSH\nkeys from the servers being unlocked. Server authentication is performed during the connection process\nagainst a `known_hosts` file.\n\nServer will be unlocked only when SSH is available on the specified IP address and port and if\nthe fingerprint in the `known_hosts` file matches. You should always use IP addresses in the\nhost configuration rather than domain names to limit the attack possibility after\ncompromising a DNS server.\n\nPlease also note that the server host keys are always stored on an unencrypted partition,\nso this script won't protect you against an attack with both physical access to the server and the IP address used for unlocking.\nTo further limit the attack possibility, you should use monitoring and possibly disable SSH unlocker in the case of unexpected behavior.\n\nOther possible security implications and solutions how to prevent them are beyond the scope of this documentation.\n\n## Requirements\n\nPython 3.5 and higher is required for the installation, because the async/await syntax is used.\n\n## Installation and running\n\n```bash\n$ pip install ssh-unlocker\n```\n\nYou should be able to run the utility by using `ssh-unlocker`. Run `ssh-unlocker -h` for the list of available options.\n\n```bash\n$ ssh-unlocker -h\nusage: ssh-unlocker [-h] [-c CONFIG] [-v] [--logfile LOGFILE]\n\nCryptsetup SSH server unlocker. This utility is repeatedly polling configured\nservers and tries to unlock the encrypted root partition using cryptsetup once\nthe SSH connection is available.\n\noptional arguments:\n  -h, --help            show this help message and exit\n  -c CONFIG, --config CONFIG\n                        Path to config file - defaults to config.ini\n  -v, --verbose         Increase verbosity level to DEBUG\n  --logfile LOGFILE     Path to log file. By default the log messages are\n                        printed to stderr\n```\n\n## Configuration\n\nBy default the configuration is read from `config.ini` configuration file, but this can be specified as a parameter.\nServer configuration should be specified using respective `[server-identifier]` sections.\nUnspecified parameters are inherited from the `[DEFAULT]` section.\n\n### Configuration attributes\n\n- `host` – SSH server domain or IP address\n- `port` – SSH server port. It's recommended to run the dropbear SSH daemon for unlocking on a port that is closed on a\nrunning (unlocked) server. This way the connection will be closed before attempting SSH authentication and you'll avoid spamming logs.\n- `username` – username of a remote user\n- `ssh_private_key` – private SSH key used for authentication (password authentication is not supported for security reasons and should be avoided)\n- `ssh_private_key_passphrase` – passphrase for encrypted SSH private key (unused when blank)\n- `cryptsetup_passphrase` – passphrase for unlocking encrypted disk using cryptsetup \n\n\u003cbr\u003e\n\n- `known_hosts` – file with DSA host keys of SSH servers (used for server authentication and MITM attack prevention). This file cannot be empty - you should always provide server keys beforehand for security reasons\n- `connect_timeout` – connection timeout for TCP handshake during port scanning\n- `ssh_connect_timeout` – timeout for connection and SSH auth\n- `sleep_interval` – time between port scanning checks\n\nExample configuration file:\n```ini\n; [server-identifier]\n; host = 127.0.0.1\n; port = 22\n; username = default\n; cryptsetup_passphrase = securePassword13!\n\n[DEFAULT]\nconnect_timeout = 5\nssh_connect_timeout = 5\nsleep_interval = 2\n\nport = 22\nusername = root\nssh_private_key = unlock_key.rsa\nssh_private_key_passphrase =\nknown_hosts = known_hosts\n```\n\n# Starting automatically at system startup\n\nIn most scenarios ssh-unlocker should probably start automatically at system startup. You should also make sure, that the unlocker would be restarted in case of any unexpected exceptions. This can be done by a simple shell script or you can use one of more sophisticated solutions described below.\n\n## Systemd config\n\nSystemd is already pre-installed in most modern distribution, so using it should be only a matter of adding new configuration file. \n\nExample configuration:\n```ini\n[Unit]\nDescription=Utility for unattended remote unlock of LUKS encrypted LVM\nAfter=network.target\n\n[Service]\nExecStart=/root/ssh-unlocker/venv/bin/ssh-unlocker\nWorkingDirectory=/root/ssh-unlocker/\nRestart=always\nTimeoutStopSec=60\n\n# try to restart the service indefinitely (RestartSec * StartLimitBurst \u003e StartLimitIntervalSec)\nRestartSec=1\nStartLimitBurst=20\nStartLimitIntervalSec=1\n\n[Install]\nWantedBy=multi-user.target\n```\n\n## Supervisor config\nIf you're used to [Supervisor](http://supervisord.org/) or you don't want to use Systemd for some reason, here is a sample configuration file:\n\n```ini\n[program:cryptsetup-ssh-unlocker]\ncommand=/root/ssh-unlocker/venv/bin/ssh-unlocker --logfile /var/log/ssh-unlocker\ndirectory=/root/ssh-unlocker/\n\nautostart=true\nautorestart=true\nstartsecs=5\nstopwaitsecs=60\n```\n\n# Server configuration\nIn order for this utility to work correctly, SSH daemon has to be installed into initial ramdisk.\nThere are some tutorials, how to do that, such as [this one for Ubuntu](https://stinkyparkia.wordpress.com/2014/10/14/remote-unlocking-luks-encrypted-lvm-using-dropbear-ssh-in-ubuntu-server-14-04-1-with-static-ipst/).\n\n## Minimal Ubuntu installation\n\n### Install dropbear and update configuration\n\n```bash\n$ apt update\n$ apt install dropbear\n```\n\nEdit `/etc/initramfs-tools/initramfs.conf` and add or replace the following configuration:\n```ini\nDEVICE=eth0\nIP=192.168.1.100::192.168.1.1:255.255.255.0::eth0:off\nDROPBEAR_OPTIONS=\"-p 1022\"\n```\n\nThe format for `IP` is the following: `[host ip]::[gateway ip]:[netmask]:[hostname]::[device]:[autoconf]`\n(please notice double colons `::`). SSH port is specified using `DROPBEAR_OPTIONS`. I strongly recommend using another port than `22`.\n\nUpdate `/etc/default/dropbear` and \nchange `NO_START=1` to `NO_START=0`\n```ini\n# disabled because OpenSSH is installed\n# change to NO_START=0 to enable Dropbear\nNO_START=0\n```\n\n`DROPBEAR_PORT` in the same configuration file is ignored in initial ramdisk phase and has to be specified in `initramfs.conf`.\n\n### Add SSH keys\n\nAdd all public keys you would like to use for authentication during the unlock phase to `/etc/initramfs-tools/root/.ssh/authorized_keys`.\nCreate the file and/or folder(s) if they don't exist already.\n\nDon't forget to add public key of the RSA key that will be used by this utility.\nYou can easily generate new RSA keypair by running `ssh-keygen -t rsa -b 4096`.\n\n### [optional] Replace original host keys\n\n```bash\n$ dropbearkey -t rsa -f /etc/dropbear/dropbear_rsa_host_key\n$ dropbearkey -t dss -f /etc/dropbear/dropbear_dss_host_key\n```\n\n### Update ramdisk\n\n```bash\n$ sudo update-initramfs -u\n```\n\n# License\nThis software is licensed under MIT license.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fviktorstiskala%2Fcryptsetup-ssh-unlocker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fviktorstiskala%2Fcryptsetup-ssh-unlocker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fviktorstiskala%2Fcryptsetup-ssh-unlocker/lists"}