Git FIDO helper, or God Fucking Help me.
gfh is a tool for helping you sign your commits in Git with resident SSH keys stored on multiple FIDO devices.
Getting Started - Usage - Installation
NB: Currently this project has only been tested with the YubiKey 5C NFC. Any FIDO2 certified device should be compatible, but please let me know if you encountered any issues with particular devices, or also if it works fine so that I can have a running list of all keys that are verified working.
Before you get started with gfh, you'll need to make sure that you already have
a resident SSH key on your FIDO key(s). The simplest way to do this is via
ssh-keygen -t ed25519-sk -O resident, but there are better guides online if
you need some different stuff.
If you don't own multiple FIDO keys/only use one resident SSH key, then you more
than likely do not need to use gfh. This tool has a very niche use case due to
Git not supporting multiple signingkeys. If you only use one resident SSH key
for signing your commits, you can just use that config option without gfh.
I've only personally validated gfh as working on macOS, some friends of mine has had it work fine on Windows (10 & 11), but I haven't had any luck with that myself.
On Linux, gfh seems to fail with
warning: gpg.ssh.defaultKeyCommand succeeded but returned no keys: key::...,
which makes no sense, because the format it expects is evidently there. A friend
of mine has said that running eval `ssh-agent` (or eval (ssh-agent -c)
as the Fish equivalent) solved the issue for them, however I haven't had any
luck with this personally so YMMV.
If you ever find out a consistent workaround for these problems, please let me know and I'll try and see if I can reproduce them.
The simplest way to add your keys to gfh is via gfh -a. This will prompt you
to select the FIDO key to use, as well as the path to the public key (or private
key) to use with it (this must be a resident key that you generated for that
particular FIDO device).
If you prefer, you can edit the config manually by creating a file at
~/.config/gfh/keys with the following format:
serial::~/.ssh/id_ed25519_sk
serial::~/.ssh/id_ecdsa_sk
(Blank lines & lines starting with # will be ignored, but won't be retained if
you use gfh -a)
After importing your keys to gfh, run the following commands to set up SSH signing with Git:
git config --global commit.gpgsign true
git config --global tag.gpgsign true
git config --global gpg.format "ssh"
git config --global gpg.ssh.program "gfh-keygen"
git config --global gpg.ssh.defaultKeyCommand "gfh"If you're on Windows, change the last two commands to set gfh-keygen.exe and
gfh.exe respectively.
(You shouldn't set user.signingkey because gfh will handle that for you
automatically.)
If all goes according to plan, you should be able to create a new commit or tag with your FIDO key plugged in, and Git will correctly prompt you to sign with it.
Releases are currently pending fixed CI builds, in the meantime you can install via Cargo just fine.
Static binary builds of gfh are available on our releases page for Windows (x86), Mac (ARM & x86), and Linux (various architectures).
brew install ovyerus/tap/gfh
scoop bucket add ovyerus https://github.com/Ovyerus/bucket
scoop install gfh
An unofficial AUR package from wale is available at https://aur.archlinux.org/packages/gfh. You can use your favourite AUR helper, or you can install it manually like so:
git clone https://aur.archlinux.org/gfh.git
cd gfh
makepkg -fsri
cargo install gfh
Pull this repository and run cargo build --release, and look for the gfh and
gfh-keygen binaries in ./target/release/.
When building from source or from Cargo, on Linux you will need the following
packages: pkg-config libpcsclite-dev libudev-dev
This program is licensed under the MIT license (see LICENSE or https://opensource.org/licenses/MIT).
