Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/ovyerus/gfh
Git FIDO Helper - Sign your Git commits with multiple resident SSH keys
https://github.com/ovyerus/gfh
fido2 git signing solokeys ssh yubikey
Last synced: 5 days ago
JSON representation
Git FIDO Helper - Sign your Git commits with multiple resident SSH keys
- Host: GitHub
- URL: https://github.com/ovyerus/gfh
- Owner: Ovyerus
- License: mit
- Created: 2022-11-13T11:42:06.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2024-03-20T08:34:51.000Z (8 months ago)
- Last Synced: 2024-10-25T10:41:03.435Z (13 days ago)
- Topics: fido2, git, signing, solokeys, ssh, yubikey
- Language: Rust
- Homepage:
- Size: 125 KB
- Stars: 23
- Watchers: 3
- Forks: 3
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# gfh
> 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.
## Getting Started
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 `signingkey`s. If you only use one resident SSH key
for signing your commits, you can just use that config option without gfh.
### Caveats
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.
## Usage
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:
```sh
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.
## Installation
### 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](https://github.com/Ovyerus/gfh/releases) for Windows (x86), Mac
(ARM & x86), and Linux (various architectures).
### Homebrew
`brew install ovyerus/tap/gfh`
### Scoop
```
scoop bucket add ovyerus https://github.com/Ovyerus/bucket
scoop install gfh
```
### AUR (unofficial)
An unofficial AUR package from [wale](https://github.com/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
```
### Crate
`cargo install gfh`
### From source
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`
## License
This program is licensed under the MIT license (see [LICENSE](./LICENSE) or
https://opensource.org/licenses/MIT).