keyward

Install

One wizard. One admin prompt.

keyward is pre-release: there is no public download yet. These are the steps the first release will use, and what you need ready.

Pre-release.Signed downloads, checksums and packages arrive with the first release. Until then, keyward is built from source and installed by hand on the author's machines. Don't install builds you didn't make or verify.

Requirements

  • Windows 11 with Windows OpenSSH (built in). Git for Windows works once pointed at Windows' ssh; setup does that.
  • Linux with systemd, X11 or Wayland for the manager, and libfido2 for security keys (already installed wherever OpenSSH is). The libfido2 udev rules give you access to the key.
  • A FIDO2 security key is optional. Any key with hmac-secret unlocks the vault; hardware-held SSH keys need Ed25519 support (YubiKey 5 firmware 5.2.3 or later). Set a FIDO2 PIN on it first.
  • Storage: a vault file anywhere you like, or 17 MiB for its own partition owned by a root-only service. On a dual boot, one partition serves both operating systems.

Windows

  1. Run the manager

    Keep keyward.exe and keyward-manager.exe together and run the manager. With nothing installed it opens setup.

  2. Choose storage

    A new partition (setup shrinks an NTFS volume by 17 MiB), an existing keyward partition, or a vault file. One UAC prompt installs to C:\Program Files\keyward, registers the keyward-store service and the keyward-agent sign-in task, sets SSH_AUTH_SOCK, points Git at Windows OpenSSH and stops the built-in ssh-agent.

  3. Create the vault

    Choose a passphrase, write down the 24-word recovery phrase it shows once, enrol your YubiKey, and import the keys found in .ssh on both operating systems.

  4. Use ssh as before

    New terminals pick up SSH_AUTH_SOCK. The first login to each server may ask you to approve. Once logins work through the agent, delete the private key files and keep the .pub.

Linux

  1. Run the manager as yourself

    Root parts run through one pkexec script: programs into /usr/local/bin, config in /etc/keyward, the keyward-store systemd unit.

  2. Choose storage

    A vault file, an existing keyward partition (make it from the Windows side on a dual boot), or unallocated space on a GPT disk for a new one.

  3. Create the vault

    Same as Windows: passphrase, recovery phrase, YubiKey, import. The agent is a systemd user service and SSH_AUTH_SOCK is set through environment.d, so it applies at next sign-in.

  4. Lock on screen lock

    Optional: a small user unit runs keyward lock when the screen locks or the machine sleeps. See the docs.

Pointing ssh at the agent

keyward env prints the line for your shell.

# Linux
export SSH_AUTH_SOCK=$XDG_RUNTIME_DIR/keyward/agent.sock

# Windows (PowerShell; setup sets this as a user variable)
$env:SSH_AUTH_SOCK = '\\.\pipe\keyward-agent-<user>'

Windows OpenSSH ignores a pipe path in IdentityAgent, so the environment variable is the way. Git for Windows ships its own ssh that can't talk to pipes; setup sets core.sshCommand to Windows' ssh.

Verifying a download

Coming with the first release.Each release will ship SHA-256 checksums and a detached signature you can check offline, plus a reproducible-build note so the binary can be matched to the source. Windows builds will be code-signed. This page will carry the public key and the exact commands.

Uninstall

Windows: Settings → Apps → keyward. Linux: /usr/local/share/keyward/uninstall.sh. Both leave the vault partition or file alone, and say where it is.