YubiKey related scripts and tools.
This repository is intended to grow into a collection of YubiKey-related tooling. The current implemented areas are FIDO2-backed SSH key management and Git commit signing with YubiKey-backed SSH keys. Future areas may include PIV and other YubiKey applications.
YubiKey workflows often span hardware prompts, local key stubs, command-line tools, and service-specific configuration. This repository aims to make those workflows easier to audit, repeat, and explain.
The current FIDO2 SSH module focuses on:
- creating resident OpenSSH
ed25519-skkeys on a YubiKey, - restoring resident SSH key stubs onto another machine,
- preserving useful key metadata where OpenSSH and YubiKey behavior allow it,
- documenting PIN, touch, recovery, and local-file behavior clearly.
The Git SSH workflows module focuses on IDE and Git configuration for using those SSH security-key identities as commit signing and remote authentication keys.
- FIDO2 SSH helpers: create and restore resident
ed25519-skSSH keys stored on a YubiKey. - Git SSH workflows: configure Git and IDEs to sign commits and authenticate remotes with YubiKey-backed SSH security keys.
- Generate flow documentation: Mermaid diagram and explanation for creating resident SSH keys.
- Restore flow documentation: Mermaid diagrams and explanation for recovering resident SSH key stubs and restoring comments.
- Git signing askpass flow documentation: Mermaid diagram and explanation for the macOS askpass helper.
- Git signing wrapper flow documentation: Mermaid diagram and explanation for the Git SSH signing wrapper.
- Git auth askpass flow documentation: Mermaid diagram and explanation for the macOS auth askpass helper.
- Git auth wrapper flow documentation: Mermaid diagram and explanation for the Git SSH auth wrapper.
The current FIDO2 SSH scripts are designed to be Linux-compatible, but they have only been validated on macOS so far. See the module README for prerequisites, usage, caveats, and validation notes.
The Git SSH workflows module includes macOS-specific askpass helper scripts for IDE commit and remote-auth workflows.
GitHub Releases package validated modules as separate tarballs, for example yubikey-fido2-ssh-v0.1.0.tar.gz and yubikey-git-ssh-workflows-v0.1.0.tar.gz. Each module tarball includes that module's README.md, scripts/, docs/, plus the repository LICENSE and SECURITY.md.
The automatically generated source archives are still available from GitHub, but module tarballs are the intended downloads for users who only need one workflow.
This repository should not contain real YubiKey serial numbers, credential IDs, private keys, public key blobs, PINs, passphrases, tokens, local machine paths, or personal command output. Documentation examples should use placeholders or generic values.
Generated SSH key stubs and common secret file formats are ignored by .gitignore, but always review changes before publishing.
Issues and pull requests are welcome. Start with CONTRIBUTING.md, especially the safety rules for sanitized logs, YubiKey serial numbers, credential IDs, key material, PINs, and passphrases.
This repository is licensed under the GNU General Public License v3.0. See LICENSE.