{"id":16847393,"url":"https://github.com/indygreg/yubikey-ssh-agent","last_synced_at":"2025-04-11T06:35:17.278Z","repository":{"id":41961300,"uuid":"483471367","full_name":"indygreg/yubikey-ssh-agent","owner":"indygreg","description":"An opinionated SSH agent for YubiKeys","archived":false,"fork":false,"pushed_at":"2022-05-09T22:05:05.000Z","size":243,"stargazers_count":16,"open_issues_count":2,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-25T04:28:37.228Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/indygreg.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-04-20T01:52:39.000Z","updated_at":"2025-01-02T22:03:08.000Z","dependencies_parsed_at":"2022-08-12T00:50:10.279Z","dependency_job_id":null,"html_url":"https://github.com/indygreg/yubikey-ssh-agent","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/indygreg%2Fyubikey-ssh-agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/indygreg%2Fyubikey-ssh-agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/indygreg%2Fyubikey-ssh-agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/indygreg%2Fyubikey-ssh-agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/indygreg","download_url":"https://codeload.github.com/indygreg/yubikey-ssh-agent/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248357752,"owners_count":21090400,"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":[],"created_at":"2024-10-13T13:07:45.855Z","updated_at":"2025-04-11T06:35:17.243Z","avatar_url":"https://github.com/indygreg.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# YubiKey SSH Agent\n\nThis project defines an SSH Agent specifically tailored for use with\nYubiKeys.\n\nThe canonical home for this project is\nhttps://github.com/indygreg/yubikey-ssh-agent.\n\n## Usage\n\n**The agent is only well tested on macOS. It may work on Linux, but that's\nnot the focus of development at the moment.**\n\nObtain a pre-built release from https://github.com/indygreg/yubikey-ssh-agent/releases\nor compile your own via `cargo build`.\n\nExtract the zip file and drag the `YubiKey SSH Agent` application\nto your `Applications` folder in Finder.\n\nLaunch the application by double clicking or running\n`open \"/Applications/YubiKey SSH Agent.app\"` from the terminal.\nYou should see a key/lock appear in your system tray at the top of\nthe screen.\n\nThen, tell SSH how to use it:\n\n    $ export SSH_AUTH_SOCK=\"~/Library/Application Support/com.gregoryszorc.yubikey-ssh-agent/agent.sock\"\n\n**To make this change permanent**, you'll want something like this at the\ntop of your `~/.ssh/config`:\n\n    Host *\n        IdentityAgent \"~/Library/Application Support/com.gregoryszorc.yubikey-ssh-agent/agent.sock\"\n\nThen perform an SSH operation needing the private key on your YubiKey:\n\n    $ ssh git@github.com\n\n**The application does not yet persist across logouts or restarts.\nYou will need to launch the application whenever you log in.** This\nwill be fixed in a future release.\n\n## Features\n\nThe `yubikey-ssh-agent` process provides a minimal SSH agent daemon\nthat interfaces directly with attached YubiKeys to service requests\nfor public key lookups and cryptographic signing operations.\n\nThe process provides a minimal GUI displaying current state and\nprovides a mechanism for inputting the PIN to unlock the YubiKey.\n\n## Advantages Over Normal SSH Agent\n\nThis tool was born because out of the author's frustration with the user\nexperience when using YubiKeys with OpenSSH using the default OpenSSH\nagent (`ssh-agent`) and `libykcs11`.\n\nWhen you use the default OpenSSH SSH agent + `libykcs11`:\n\n1. `ssh-agent` spawns a `ssh-pkcs11-helper` process.\n2. `ssh-pkcs11-helper` loads `libykcs11.{so,dylib,dll}`.\n3. When `ssh-agent` receives a message requesting interfacing with the\n   YubiKey, it calls into APIs in `libykcs11`, which speaks to the\n   YubiKey.\n4. Results from `libykcs11` are relayed back to `ssh`.\n\nA common problem is that `libykcs11` will lose contact with the YubiKey\nor your cached PIN expires due to a timeout. What happens in these\nscenarios is `ssh-agent` thinks that no YubiKey keys are available\nand tells `ssh` there are no keys. `ssh` summarily tries to\nauthenticate without knowledge of the YubiKey keys. And this often\nfails with a `Permission denied` message because the client didn't\nactually present any public keys!\n\nOr a variant of this is that `ssh-agent` advertises the YubiKey-hosted\nkey but when it attempts to use the key it fails because the YubiKey is\nlocked (a PIN is required). This also often materializes as a nebulous\nand hard-to-debug `Permission denied` error.\n\n**Unlike the default `ssh-agent` + `libykcs11` behavior, this agent\nwon't fail SSH client operations because the YubiKey is locked, the agent\nlost a connection with the YubiKey, or the agent's cached PIN has expired.\nInstead, this agent recognizes when a key is locked and prompts the user\nto unlock it, before failing the SSH operation.**\n\nThis SSH agent makes the assumption that the YubiKey is the provider of\nSSH keys. Therefore, when there is a request for available keys or a\nsignature request, it can be very vocal about raising an error (through\nits own GUI) when user interaction is needed. For example, if SSH wants\nto perform a cryptographic signature but the YubiKey is locked, this agent\nwill open a modal window requesting the YubiKey PIN and the SSH agent will\nwait for you to unlock the YubiKey before failing the SSH attempt.\n\n### Security Advantages\n\nThis agent doesn't support adding keys. This agent doesn't (yet) support\ncaching the YubiKey PIN or management key.\n\nThere are no secrets lingering in memory that can easily be extracted by\na user on the same machine. (If someone accesses the process at just the\nright time they could acquire the PIN, however.)\n\nThe main threat model for this SSH agent is an unwanted client requesting\nsigning operations. This threat model exists for all SSH agent implementations.\nFor the ultra paranoid, you'll want to set a PIN protection policy on the\nYubiKey to require a PIN or touch for every operation. Without such a policy,\nmultiple signing operations may be performed from a single unlock/touch\nand anyone with access to the SSH agent could effectively use the private\nkey on the YubiKey.\n\n## State of Project\n\nThis project is still very alpha. The graphical UI in particular is\nvery crude and in need of a lot of work.\n\nPlease file issues or just contribute pull requests to improve things.\n\nOnly macOS is well tested. Windows doesn't currently build due to\nhttps://github.com/sekey/ssh-agent.rs not compiling on Windows (this\nis a very fixable problem).\n\n## Quirks\n\n### macOS Default SSH Agent\n\nmacOS has an SSH agent built-in and will set `SSH_AGENT_SOCK` automatically\nto a value like `SSH_AUTH_SOCK=/private/tmp/com.apple.launchd.{random}/Listeners`.\n\n[Stick with Security: YubiKey, SSH, GnuPG, macOS](https://evilmartians.com/chronicles/stick-with-security-yubikey-ssh-gnupg-macos)\nhas a good overview of the problem and how to work around it.\n\nEssentially, the system built-in\n`/System/Library/LaunchAgents/com.openssh.ssh-agent.plist` will launch\n`ssh-agent` and set `SSH_AUTH_SOCK` to point to its socket.\n\nYou can't edit this file with system integrity protection enabled. So a\nworkaround is to create your own plists for use with launchd/launchctl\nto spawn this agent and symlink over `SSH_AUTH_SOCK`.\n\nSome day we'll likely streamline this procedure to enable people to easily\nreplace `SSH_AUTH_SOCK` so SSH clients never use the system default\nagent.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Findygreg%2Fyubikey-ssh-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Findygreg%2Fyubikey-ssh-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Findygreg%2Fyubikey-ssh-agent/lists"}