diff options
| -rw-r--r-- | .SRCINFO | 20 | ||||
| -rw-r--r-- | .gitignore | 5 | ||||
| -rw-r--r-- | PKGBUILD | 27 | ||||
| -rw-r--r-- | README.adoc | 139 | ||||
| -rw-r--r-- | UNLICENSED | 24 | ||||
| -rw-r--r-- | mkinitcpio-wireguard.install | 15 | ||||
| -rw-r--r-- | wireguard_config | 60 | ||||
| -rw-r--r-- | wireguard_hook | 90 | ||||
| -rw-r--r-- | wireguard_install | 52 |
9 files changed, 432 insertions, 0 deletions
diff --git a/.SRCINFO b/.SRCINFO new file mode 100644 index 000000000000..c579ddbfcf22 --- /dev/null +++ b/.SRCINFO @@ -0,0 +1,20 @@ +pkgbase = mkinitcpio-wireguard + pkgdesc = mkinitcpio hook that initialises Wireguard to assist in the remote unlocking of encrypted partitions. + pkgver = 0.1.0 + pkgrel = 1 + url = https://github.com/dharrigan/mkinitcpio-wireguard + install = mkinitcpio-wireguard.install + arch = x86_64 + license = Unlicense + depends = mkinitcpio>=0.9.0 + depends = wireguard-tools + backup = etc/wireguard/remote-unlock + source = wireguard_hook + source = wireguard_install + source = wireguard_config + sha256sums = baa64d53adf5a60092c5df59c6ccf9e8253be4b7c947f89a9afd2cf0a84eea97 + sha256sums = edf47fa52c1e5e802a5920b8fc3dea281d33c243e79364717c64588f384befaf + sha256sums = 9385ec468589f0621d2a90839ebe4b38d37824ea706c2b2edf8f41b0f239f7e8 + +pkgname = mkinitcpio-wireguard + diff --git a/.gitignore b/.gitignore new file mode 100644 index 000000000000..ab42fdb9f0a3 --- /dev/null +++ b/.gitignore @@ -0,0 +1,5 @@ +/*.pkg.tar.* +/*.src.tar.* +tags +pkg/ +src/ diff --git a/PKGBUILD b/PKGBUILD new file mode 100644 index 000000000000..77fe8f2d3af5 --- /dev/null +++ b/PKGBUILD @@ -0,0 +1,27 @@ +# Maintainer: David Harrigan <dharrigan [@] gmail [dot] com> + +pkgname=mkinitcpio-wireguard +pkgver=0.1.0 +pkgrel=1 +pkgdesc='mkinitcpio hook that initialises Wireguard to assist in the remote unlocking of encrypted partitions.' +url='https://github.com/dharrigan/mkinitcpio-wireguard' +arch=('x86_64') +license=('Unlicense') +install="${pkgname}.install" +depends=('mkinitcpio>=0.9.0' 'wireguard-tools') +backup=('etc/wireguard/remote-unlock') +source=('wireguard_hook' 'wireguard_install' 'wireguard_config') + +package() { + install -o root -g root -D ${srcdir}/wireguard_hook ${pkgdir}/usr/lib/initcpio/hooks/wireguard + install -o root -g root -D ${srcdir}/wireguard_install ${pkgdir}/usr/lib/initcpio/install/wireguard + install -o root -g root -D ${srcdir}/wireguard_config ${pkgdir}/etc/wireguard/remote-unlock +} + +sha256sums=( +'baa64d53adf5a60092c5df59c6ccf9e8253be4b7c947f89a9afd2cf0a84eea97' +'edf47fa52c1e5e802a5920b8fc3dea281d33c243e79364717c64588f384befaf' +'9385ec468589f0621d2a90839ebe4b38d37824ea706c2b2edf8f41b0f239f7e8' +) + +# vim:set syntax=sh tw=78: diff --git a/README.adoc b/README.adoc new file mode 100644 index 000000000000..aa2c441da469 --- /dev/null +++ b/README.adoc @@ -0,0 +1,139 @@ += mkinitcpio Wireguard hook +:author: David Harrigan +:email: <dharrigan [@] gmail [dot] com> +:docinfo: true +:doctype: book +:icons: font +:numbered: +:sectlinks: +:sectnums: +:setanchors: +:source-highlighter: highlightjs +:toc: +:toclevels: 5 + +== Rationale + +Firstly, encryption. Encrypt all the things. + +Secondly, I think https://www.wireguard.io[Wireguard] is pretty awesome. It's +really easy to setup and use and works flawlessly (at least for me 😄). + +Thirdly, the ability to remotely unlock encrypted partitions is extremely +useful. However, a limitation is that in order to remotely unlock the +partition via SSH, you normally need to be on the same network (or at least +routeable) to the computer that needs unlocking. + +As far as I could tell, there was nothing available in +https://aur.archlinux.org[AUR] that provided a Wireguard hook for +`mkinitcpio`. Creating a hook should allow a basic Wireguard interface to be +established so that - via a secure network - you could gain access to the +remote machine. This is my small attempt to achieve that aim. + +IMPORTANT: I developed this little hook for myself and I'm releasing it into +the general community in the (probably misguided) hope that others may find it +useful too. As usual, no warranty implied or otherwise is given towards the +fitness of this software in meeting *YOUR* needs. Please refer to the included +https://unlicense.org[Unlicense] license file for more information. That said, +I find this little hook useful - perhaps you may too - so please enjoy! Oh, +and please be be awesome to each other! + +WARNING: Ensure you have read the Arch wiki section on +https://wiki.archlinux.org/index.php/Dm-crypt/Specialties#Remote_unlocking_of_the_root_(or_other)_partition[remote +unlocking]. It's a *very* good idea to get remote unlocking working *first* on +your local network - proving that it works for you (this includes using either +*tinyssh* or *dropbear* to authenticate and unlock successfully) +- *before* attempting to setup this mkinitcpio Wireguard hook for remote +unlocking. + +IMPORTANT: It is also *strongly* recommend that a *separate* Wireguard network +is setup and configured *just* for unlocking. You see, a private key (and a +public key) and a configuration file are written to the ramdisk (which +typically lives in an unencrypted boot partition). It's super trivially easy +for anyone to copy this ramdisk, extract out the contents and use the private +key and Wireguard configuration found therein to connect to your Wireguard +network. As a minimum, you could disable (on the remote peer *nominally called +the `server`*) the ability for the target machine (the `client` - the one on +which you are remotely unlocking partitions) to connect and authenticate - +only enabling connection *when* and *if* required. Please be careful and think +this through! Safety first! + +== OS Installation + +Standard installation rules apply. Here's an example using the +https://github.com/Jguer/yay[yay] package manager to install the utility. + +`yay -S mkinitcpio-wireguard` + +Please refer to your favourite package manager's documentation in learn how to +install it for you 😄 + +NOTE: Obviously, you must also install Wireguard! Choose either manual +installation (using git and compiling it yourself), or using `wireguard-arch` +or `wireguard-dkms`. Life is short, so personally I just roll with +`wireguard-arch`. Seems to work OOTB for me, but YMMV... + +== Configuration + +IMPORTANT: The setup and running of `mkinitcpio-wireguard` is *very* basic and +makes *lots* of assumptions. *This is intentional!* This hook is simple +because it is designed to get a minimal Wireguard up and running so that you +can remotely unlock encrypted partitions. The script does not attempt to do +anything else. This script will never be super fancy or clever. + +WARNING: Please read and familiarise yourself with how Wireguard works. In +particular, please refer to the *numerous* examples online of how to setup and +configure Wireguard. It is *strongly* suggested you get Wireguard up and +running first. A few examples of where to find documentation are listed below: + +* https://wiki.archlinux.org/index.php/WireGuard +* https://www.wireguard.com/quickstart/ +* https://git.zx2c4.com/WireGuard/about/src/tools/man/wg.8 + +After installing `mkinitcpio-wireguard`, a configuration file will be written +to `/etc/wireguard/remote-unlock`. You *MUST* edit this file to suit your +particular Wireguard requirements. The file is really simple and therefore +should be pretty self-explanatory. + +NOTE: If you have an existing `wg0.conf` in your `/etc/wireguard` directory, +you can use the contents of that file as a reference. Please be aware of the +warning above concerning the recommended use of a separate network for remote +unlocking. + +== Hook Installation + +After you have edited the `/etc/wireguard/remote-unlock` file to suit your +needs, ensure that you've added the `wireguard` hook to the *HOOKS* array of +`/etc/mkinitcpio.conf`. Shown below is an example that also includes the use +of `netconf`, `tinyssh` and `encryptssh`. + +---- +HOOKS=(base udev autodetect keyboard keymap modconf block netconf wireguard tinyssh encryptssh filesystems fsck) +---- + +== Final Steps + +Lastly, run (as root): + +---- +mkinitcpio -P +---- + +This will regenerate the ramdisk with your Wireguard configuration. + +You should now be able to reboot your machine and after the interface has come +up be able to ping it via your Wireguard network! You should now also be able +to SSH to the machine (you did remember to set that all up before doing this, +right?) and unlock any encrypted partitions and thus enable the continuation +of your boot process! FTW! + +== Unlicensed + +Find the full unlicense in the UNLICENSE file, but here's a snippet. +This is free and unencumbered software released into the public domain. + +---- +Anyone is free to copy, modify, publish, use, compile, sell, or distribute +this software, either in source code form or as a compiled binary, for any +purpose, commercial or non-commercial, and by any means. +---- diff --git a/UNLICENSED b/UNLICENSED new file mode 100644 index 000000000000..cf1ab25da034 --- /dev/null +++ b/UNLICENSED @@ -0,0 +1,24 @@ +This is free and unencumbered software released into the public domain. + +Anyone is free to copy, modify, publish, use, compile, sell, or +distribute this software, either in source code form or as a compiled +binary, for any purpose, commercial or non-commercial, and by any +means. + +In jurisdictions that recognize copyright laws, the author or authors +of this software dedicate any and all copyright interest in the +software to the public domain. We make this dedication for the benefit +of the public at large and to the detriment of our heirs and +successors. We intend this dedication to be an overt act of +relinquishment in perpetuity of all present and future rights to this +software under copyright law. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR +OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, +ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +OTHER DEALINGS IN THE SOFTWARE. + +For more information, please refer to <http://unlicense.org> diff --git a/mkinitcpio-wireguard.install b/mkinitcpio-wireguard.install new file mode 100644 index 000000000000..aedd9a6616f9 --- /dev/null +++ b/mkinitcpio-wireguard.install @@ -0,0 +1,15 @@ +#!/bin/sh + +post_install() { + echo ">" + echo "> Now add 'wireguard' to your HOOKS array in your '/etc/mkinitcpio.conf' and rebuild the ramdisk." + echo "> e.g., HOOKS=(base udev autodetect keyboard keymap modconf block netconf wireguard tinyssh encryptssh filesystems fsck)" + echo "> don't forget to configure the '/etc/wireguard/remote-unlock' file then rerun mkinitcpio..." + echo ">" +} + +post_remove() { + sed -i "/^HOOKS=/s/wireguard//" /etc/mkinitcpio.conf +} + +# vim:set syntax=sh tw=78: diff --git a/wireguard_config b/wireguard_config new file mode 100644 index 000000000000..ec0907cc1d07 --- /dev/null +++ b/wireguard_config @@ -0,0 +1,60 @@ +# +# This is free and unencumbered software released into the public domain. +# +# Anyone is free to copy, modify, publish, use, compile, sell, or +# distribute this software, either in source code form or as a compiled +# binary, for any purpose, commercial or non-commercial, and by any +# means. +# +# In jurisdictions that recognize copyright laws, the author or authors +# of this software dedicate any and all copyright interest in the +# software to the public domain. We make this dedication for the benefit +# of the public at large and to the detriment of our heirs and +# successors. We intend this dedication to be an overt act of +# relinquishment in perpetuity of all present and future rights to this +# software under copyright law. +# +# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +# IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR +# OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, +# ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +# OTHER DEALINGS IN THE SOFTWARE. +# +# For more information, please refer to <http://unlicense.org/> +# + +# Information pertaining to the Wireguard mkinitcpio hook +# +# Please ensure you've read the documentation on how to setup and configure +# Wireguard for your needs. It's vital that you ensure that you can connect +# successfully before working on enabling remote unlocking functionality. + +# All the values below are just examples. You must change them to suit +# your Wireguard network setup. + +# Specifies the name of the Wireguard interface (usually wg0) +INTERFACE=wg0 + +# Specifies the address that the Wireguard interface will use. +# Please ensure you specify the address in CIDR format. +INTERFACE_ADDR=10.0.200.21/24 + +# This is the public key of the peer. +PEER_PUBLIC_KEY=abcdefg + +# This is the IP address and port of the peer. +# Usually this is the external public-facing IP, but it may also be internal! +PEER_ENDPOINT=192.168.80.1:12912 + +# This is your private key previously setup to establish connection to the peer. +PRIVATE_KEY_FILE=/etc/wireguard/privatekey + +# If you're behind a NAT, a ping of 25 seconds is useful! +PERSISTENT_KEEPALIVES=25 + +# The IP range that will be allowed. +ALLOWED_IPS=10.0.200.0/24 + +# vim:set syntax=sh tw=78: diff --git a/wireguard_hook b/wireguard_hook new file mode 100644 index 000000000000..f914e7cf50bf --- /dev/null +++ b/wireguard_hook @@ -0,0 +1,90 @@ +#!/bin/ash +# +# This is free and unencumbered software released into the public domain. +# +# Anyone is free to copy, modify, publish, use, compile, sell, or +# distribute this software, either in source code form or as a compiled +# binary, for any purpose, commercial or non-commercial, and by any +# means. +# +# In jurisdictions that recognize copyright laws, the author or authors +# of this software dedicate any and all copyright interest in the +# software to the public domain. We make this dedication for the benefit +# of the public at large and to the detriment of our heirs and +# successors. We intend this dedication to be an overt act of +# relinquishment in perpetuity of all present and future rights to this +# software under copyright law. +# +# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +# IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR +# OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, +# ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +# OTHER DEALINGS IN THE SOFTWARE. +# +# For more information, please refer to <http://unlicense.org/> +# + +_fatal () { echo ":: wireguard [FATAL]: ${@}. Cannot initialise Wireguard\!"; break=y; } + +if [ -f /etc/wireguard/remote-unlock ]; then + . /etc/wireguard/remote-unlock +fi + +run_hook() +{ + if [ -z $INTERFACE ]; then + _fatal 'Interface name is not defined!' + return 1 + fi + + if [ -z $INTERFACE_ADDR ]; then + _fatal 'Interface address is not defined!' + return 1 + fi + + if [ -z $PEER_PUBLIC_KEY ]; then + _fatal 'Peer Public Key is not defined!' + return 1 + fi + + if [ -z $PRIVATE_KEY_FILE -a -f $PRIVATE_KEY_FILE ]; then + _fatal 'Private key file is not defined!' + return 1 + fi + + if [ -z $PEER_ENDPOINT ]; then + _fatal 'Peer endpoint is not defined!' + return 1 + fi + + if [ -z $PERSISTENT_KEEPALIVES ]; then + _fatal 'Persistent Keep Alives is not defined!' + return 1 + fi + + if [ -z $ALLOWED_IPS ]; then + _fatal 'Allowed IPs is not defined!' + return 1 + fi + + echo "Starting Wireguard Remote Unlock." + + ip link add dev $INTERFACE type wireguard + wg set $INTERFACE \ + private-key $PRIVATE_KEY_FILE \ + peer $PEER_PUBLIC_KEY \ + endpoint $PEER_ENDPOINT \ + persistent-keepalive $PERSISTENT_KEEPALIVES \ + allowed-ips $ALLOWED_IPS + ip addr add $INTERFACE_ADDR dev $INTERFACE + ip link set $INTERFACE up +} + +run_cleanuphook() { + + ip link delete dev $INTERFACE + +} +# vim:set syntax=sh tw=78: diff --git a/wireguard_install b/wireguard_install new file mode 100644 index 000000000000..d681830892d7 --- /dev/null +++ b/wireguard_install @@ -0,0 +1,52 @@ +#!/bin/bash +# +# This is free and unencumbered software released into the public domain. +# +# Anyone is free to copy, modify, publish, use, compile, sell, or +# distribute this software, either in source code form or as a compiled +# binary, for any purpose, commercial or non-commercial, and by any +# means. +# +# In jurisdictions that recognize copyright laws, the author or authors +# of this software dedicate any and all copyright interest in the +# software to the public domain. We make this dedication for the benefit +# of the public at large and to the detriment of our heirs and +# successors. We intend this dedication to be an overt act of +# relinquishment in perpetuity of all present and future rights to this +# software under copyright law. +# +# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +# IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR +# OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, +# ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +# OTHER DEALINGS IN THE SOFTWARE. +# +# For more information, please refer to <http://unlicense.org/> +# + +build() +{ + add_binary wg + add_module wireguard + + add_full_dir /etc/wireguard + + add_runscript +} + +help() { + cat <<HELPME +This hook provides basic Wireguard support to assist in the remote unlocking +of encrypted partitions. There are various parameters that are to be +configured via the "/etc/wireguard/remote-unlock" file. This must be done! + +In addition to this hook, you will require something like tinyssh or dropbear +appropriately configured in order to gain remote access. Please refer to the +Arch Wiki for further details with regards to remote unlocking of encrypted +partitions. +HELPME +} + +# vim:set syntax=sh tw=78: |