{"id":13490964,"url":"https://github.com/FiloSottile/yubikey-agent","last_synced_at":"2025-03-28T07:31:39.577Z","repository":{"id":38195133,"uuid":"258864129","full_name":"FiloSottile/yubikey-agent","owner":"FiloSottile","description":"yubikey-agent is a seamless ssh-agent for YubiKeys.","archived":false,"fork":false,"pushed_at":"2023-12-03T05:40:19.000Z","size":71,"stargazers_count":2731,"open_issues_count":59,"forks_count":138,"subscribers_count":59,"default_branch":"main","last_synced_at":"2025-03-23T03:11:47.575Z","etag":null,"topics":["cryptography","piv","smartcard","ssh","ssh-agent","yubikey"],"latest_commit_sha":null,"homepage":"https://filippo.io/yubikey-agent","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/FiloSottile.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"custom":"https://github.com/FiloSottile/FiloSottile/blob/main/maintenance.md#funding"}},"created_at":"2020-04-25T20:08:42.000Z","updated_at":"2025-03-22T16:50:08.000Z","dependencies_parsed_at":"2023-01-31T22:00:58.074Z","dependency_job_id":"de553038-4a8b-4176-9bd6-63992da9ea7c","html_url":"https://github.com/FiloSottile/yubikey-agent","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FiloSottile%2Fyubikey-agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FiloSottile%2Fyubikey-agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FiloSottile%2Fyubikey-agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FiloSottile%2Fyubikey-agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/FiloSottile","download_url":"https://codeload.github.com/FiloSottile/yubikey-agent/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245989167,"owners_count":20705774,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cryptography","piv","smartcard","ssh","ssh-agent","yubikey"],"created_at":"2024-07-31T19:00:52.438Z","updated_at":"2025-03-28T07:31:38.974Z","avatar_url":"https://github.com/FiloSottile.png","language":"Go","funding_links":["https://github.com/FiloSottile/FiloSottile/blob/main/maintenance.md#funding"],"categories":["Go","Tools"],"sub_categories":["Third-party Tools"],"readme":"# yubikey-agent\n\nyubikey-agent is a seamless ssh-agent for YubiKeys.\n\n* **Easy to use.** A one-command setup, one environment variable, and it just runs in the background.\n* **Indestructible.** Tolerates unplugging, sleep, and suspend. Never needs restarting.\n* **Compatible.** Provides a public key that works with all services and servers.\n* **Secure.** The key is generated on the YubiKey and can't be extracted. Every session requires the PIN, every login requires a touch. Setup takes care of PUK and management key.\n\nWritten in pure Go, it's based on [github.com/go-piv/piv-go](https://github.com/go-piv/piv-go) and [golang.org/x/crypto/ssh](https://golang.org/x/crypto/ssh).\n\n![](https://user-images.githubusercontent.com/1225294/81489747-63a03b00-9247-11ea-923a-b7434bcf7fd1.png)\n\n## Installation\n\n### macOS\n\n```\nbrew install yubikey-agent\nbrew services start yubikey-agent\nyubikey-agent -setup # generate a new key on the YubiKey\n```\n\nThen add the following line to your `~/.zshrc` and restart the shell.\n\n```\nexport SSH_AUTH_SOCK=\"$(brew --prefix)/var/run/yubikey-agent.sock\"\n```\n\n### Linux\n\n#### Arch\n\nOn Arch, use [the `yubikey-agent` package](https://aur.archlinux.org/packages/yubikey-agent/) from the AUR.\n\n```\ngit clone https://aur.archlinux.org/yubikey-agent.git\ncd yubikey-agent \u0026\u0026 makepkg -si\n\nsystemctl daemon-reload --user\nsudo systemctl enable --now pcscd.socket\nsystemctl --user enable --now yubikey-agent\n\nexport SSH_AUTH_SOCK=\"${XDG_RUNTIME_DIR}/yubikey-agent/yubikey-agent.sock\"\n```\n\n#### NixOS / nixpkgs\n\nOn NixOS unstable and 20.09 (unreleased at time of writing), you can\nadd this to your `/etc/nixos/configuration.nix`:\n\n```\nservices.yubikey-agent.enable = true;\n```\n\nThis installs `yubikey-agent` and sets up a systemd unit to start\nyubikey-agent for you.\n\nOn other systems using nix, you can also install from nixpkgs:\n\n```\nnix-env -iA nixpkgs.yubikey-agent\n```\n\nThis installs the software but does *not* install a systemd unit.  You\nwill have to set up service management manually (see below).\n\n#### Other systemd-based Linux systems\n\nOn other systemd-based Linux systems, follow [the manual installation instructions](systemd.md).\n\nPackaging contributions are very welcome.\n\n### FreeBSD\n\nInstall the [`yubikey-agent` port](https://svnweb.freebsd.org/ports/head/security/yubikey-agent/).\n\n### Windows\n\nWindows support is currently WIP.\n\n## Advanced topics\n\n### Coexisting with other `ssh-agent`s\n\nIt's possible to configure `ssh-agent`s on a per-host basis.\n\nFor example to only use `yubikey-agent` when connecting to `example.com`, you'd add the following lines to `~/.ssh/config` instead of setting `SSH_AUTH_SOCK`.\n\n```\nHost example.com\n    IdentityAgent /usr/local/var/run/yubikey-agent.sock\n```\n\nTo use `yubikey-agent` for all hosts but one, you'd add the following lines instead. In both cases, you can keep using `ssh-add` to interact with the main `ssh-agent`.\n\n```\nHost example.com\n    IdentityAgent $SSH_AUTH_SOCK\n\nHost *\n    IdentityAgent /usr/local/var/run/yubikey-agent.sock\n```\n\n### Conflicts with `gpg-agent` and Yubikey Manager\n\n`yubikey-agent` takes a persistent transaction so the YubiKey will cache the PIN after first use. Unfortunately, this makes the YubiKey PIV and PGP applets unavailable to any other applications, like `gpg-agent` and Yubikey Manager. Our upstream [is investigating solutions to this annoyance](https://github.com/go-piv/piv-go/issues/47).\n\nIf you need `yubikey-agent` to release its lock on the YubiKey, send it a hangup signal or use `ssh-add`'s \"delete all identities\" flag. Likewise, you might have to kill `gpg-agent` after use for it to release its own lock.\n\n```\nssh-add -D\n```\n\nThis does not affect the FIDO2 functionality.\n\n### Changing PIN and PUK\n\nUse YubiKey Manager to change the PIN and PUK.\n\n`yubikey-agent -setup` sets the PUK to the same value as the PIN.\n\n```\nkillall -HUP yubikey-agent\nykman piv access change-pin\nykman piv access change-puk\n```\n\n### Unblocking the PIN with the PUK\n\nIf the wrong PIN is entered incorrectly three times in a row, YubiKey Manager can be used to unlock it.\n\n`yubikey-agent -setup` sets the PUK to the same value as the PIN.\n\n```\nykman piv access unblock-pin\n```\n\nIf the PUK is also entered incorrectly three times, the key is permanently irrecoverable. The YubiKey PIV applet can be reset with `yubikey-agent --setup --really-delete-all-piv-keys`.\n\n### Manual setup and technical details\n\n`yubikey-agent` only officially supports YubiKeys set up with `yubikey-agent -setup`.\n\nIn practice, any PIV token with an RSA or ECDSA P-256 key and certificate in the Authentication slot should work, with any PIN and touch policy. Simply skip the setup step and use `ssh-add -L` to view the public key.\n\n`yubikey-agent -setup` generates a random Management Key and [stores it in PIN-protected metadata](https://pkg.go.dev/github.com/go-piv/piv-go/piv?tab=doc#YubiKey.SetMetadata).\n\n### Alternatives\n\n#### Native FIDO2\n\nRecent versions of OpenSSH [support using FIDO2 tokens directly](https://buttondown.email/cryptography-dispatches/archive/cryptography-dispatches-openssh-82-just-works/). Since those are their own key type, they require server-side support, which has only recently reached Debian and [GitHub](https://www.yubico.com/blog/github-now-supports-ssh-security-keys/).\n\nFIDO2 SSH keys by default don't require a PIN, and require a private key file, acting more like a second factor. `yubikey-agent` keys always require PINs and can be ported to a different machine simply by plugging in the YubiKey. (With recent enough tokens such as a YubiKey 5, a similar setup can be achieved by using the `verify-required` and `resident` options, after setting a FIDO2 PIN with YubiKey Manager: the private key file will still be required, but it can be regenerated from the YubiKey.)\n\n#### `gpg-agent`\n\n`gpg-agent` can act as an `ssh-agent`, and it can use keys stored on the PGP applet of a YubiKey.\n\nThis requires a finicky setup process dealing with PGP keys and the `gpg` UX, and seems to lose track of the YubiKey and require restarting all the time. Frankly, I've also had enough of PGP and GnuPG.\n\n#### `ssh-agent` and PKCS#11\n\n`ssh-agent` can load PKCS#11 applets to interact with PIV tokens directly. There are two third-party PKCS#11 providers for YubiKeys (OpenSC and ykcs11) and one that ships with macOS (`man 8 ssh-keychain`).\n\nThe UX of this solution is poor: it requires calling `ssh-add` to load the PKCS#11 module and to unlock it with the PIN (as the agent has no way of requesting input from the client during use, a limitation that `yubikey-agent` handles with `pinentry`), and needs manual reloading every time the YubiKey is unplugged or the machine goes to sleep.\n\nThe ssh-agent that ships with macOS (which is pretty cool, as it starts on demand and is preconfigured in the environment) also has restrictions on where the `.so` modules can be loaded from. It can see through symlinks, so a Homebrew-installed `/usr/local/lib/libykcs11.dylib` won't work, while a hard copy at `/usr/local/lib/libykcs11.copy.dylib` will.\n\n`/usr/lib/ssh-keychain.dylib` works out of the box, but only with RSA keys. Key generation is undocumented.\n\n#### Secretive and SeKey\n\n[Secretive](https://github.com/maxgoedjen/secretive) and [SeKey](https://github.com/sekey/sekey) are similar projects that use the Secure Enclave to store the private key and Touch ID for authorization. The Secure Enclave has so far a worse security track record compared to YubiKeys.\n\n#### `pivy-agent`\n\n[`pivy-agent`](https://github.com/joyent/pivy#using-pivy-agent) is part of a suite of tools to work with PIV tokens. It's similar to `yubikey-agent`, and inspired its design.\n\nThe main difference is that it requires unlocking via `ssh-add -X` rather than using a graphical pinentry, and it caches the PIN in memory rather than relying on the device PIN policy. It's also written in C.\n\n`yubikey-agent` also aims to provide an even smoother setup process.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FFiloSottile%2Fyubikey-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FFiloSottile%2Fyubikey-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FFiloSottile%2Fyubikey-agent/lists"}