Skip to main content

The RemoteKey application is what you need on your computer to make comfortable inputs.

    The complete feature set of the application is:

    • Request input from another RemoteKey application or smartphone app
    • Reply to a request from RemoteKey
    • De-/Encrypt file
    • Load and decrypt file from a webspace

    The following installation methods are supported:

    • Via APT:
      • Ubuntu 20.04
      • Ubuntu 20.10
      • Debian Buster
      • Proxmox VE 6 (based on Debian Buster) 
    • Via Docker: docker pull shbb/remotekey:latest
    • Direct download:
      • Linux (amd64/i386)
      • Windows (amd64/i386)
      • MacOS (amd64)
    • Direct download: (experimental)
      • Linux (arm/arm64)

    Installation via APT

    RemoteKey is split in several packages:

    • remotekey: The commandline interface
    • remotekey-initramfs: Integrates RemoteKey into the initramfs and allows to enter the passphrase for encrypted drives.

    Run these commands.

    Note: For Proxmox replace "$(lsb_release -sc)" with "buster".

    wget -O - | apt-key add -
    echo "deb $(lsb_release -sc) stable" > /etc/apt/sources.list.d/shbb.list

    apt update
    # Just the commandline
    apt-get install --yes remotekey
    # Enable unlock at boot
    apt-get install --yes remotekey-initramfs


    Use to unlock at boot:

    This option requires RemoteKey to be installed via APT.

    If RemoteKey is integraded into initramfs, it tries to connect with the internet via DHCP. If that is not possible in your network, you have to specify the IP-configuration as kernel parameter.
    Details can be found here:
    If DHCP is not working for you, you can use this script as support:

    curl > && bash eth0

    RemoteKey brings every network down it brought up during boot. This is done to not block the operating system to manage the network.

    To enable/configure RemoteKey you edit /etc/remotekey/initrd.json, only if this file exists, its integrated into the initramfs. Every change to this file must be enabled with an update of the initramfs.

    Example how to configure RemoteKey for initramfs:

    # Copy example to correct location
    cp /etc/remotekey/samples/initrd.json /etc/remotekey/initrd.json
    # Generate and update relay id and aes key in /etc/remotekey/initrd.json
    RID=$(dd if=/dev/urandom bs=1024 count=100 2>/dev/null | LC_ALL=C grep --text -oE '[[:alnum:]]+' | tr -d '\n' | head -c 10)
    sed -i.bk -E "s'\"relay-id\"[: \"]+[^\"]+'\"relay-id\":\"$(hostname)_${RID}'g" /etc/remotekey/initrd.json
    sed -i.bk -E "s'\"key\"[: \"]+[^\"]+'\"key\":\"base64:$(dd if=/dev/urandom bs=32 count=1 | base64 | tr -d '\n')'g" /etc/remotekey/initrd.json
    # Remove backup file
    rm /etc/remotekey/initrd.json.bk
    # Update initramfs
    update-initramfs -u -k all
    # Display QR-Code/Config string for the smartphone app and commandline to answer with RemoteKey application
    remotekey config --file /etc/remotekey/initrd.json --config ask-password --operation relay-registration | less
    echo "Done!"

    Boot process with RemoteKey:

    • Boot of the computer
    • Prepare input for ZFS/Cryptsetup
    • Check network connectivity
      • (A) No network connection found, try to bring it up (Default: DHCP)
      • (B) Network connection found: Do not touch anything
    • Request passphrase for drive(s)
      • On success: Boot
      • On fail: Use original input method
    • Cleanup
      • (A) Bring network down, the operationg system has full control
      • (B) Do not touch anything

    Best Practices:

    • Use config files:
      • Shorter commands
      • Central place for changes
      • Reusability increses
      • Config-Files are like password files and should only be readable by user (chmod 600)
    • Passwords must stay human typeable
      • If the internet is down, RemoteKey does not work!
      • When beeing offline, you have to enter the password from hand.