{"id":13706671,"url":"https://github.com/mgbowen/windows-fido-bridge","last_synced_at":"2025-05-05T23:31:23.719Z","repository":{"id":40572560,"uuid":"258889871","full_name":"mgbowen/windows-fido-bridge","owner":"mgbowen","description":"An OpenSSH SK middleware that allows you to use a FIDO/U2F security key (e.g. a YubiKey) to SSH into a remote server from WSL or Cygwin.","archived":true,"fork":false,"pushed_at":"2024-09-16T15:20:08.000Z","size":192,"stargazers_count":114,"open_issues_count":12,"forks_count":15,"subscribers_count":10,"default_branch":"master","last_synced_at":"2024-11-13T15:48:58.799Z","etag":null,"topics":["cygwin","fido","fido-u2f","openssh","openssh-client","u2f","webauthn","windows","wsl","wsl2","yubikey"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mgbowen.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}},"created_at":"2020-04-25T22:47:55.000Z","updated_at":"2024-09-16T15:20:25.000Z","dependencies_parsed_at":"2024-11-13T15:43:53.134Z","dependency_job_id":null,"html_url":"https://github.com/mgbowen/windows-fido-bridge","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mgbowen%2Fwindows-fido-bridge","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mgbowen%2Fwindows-fido-bridge/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mgbowen%2Fwindows-fido-bridge/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mgbowen%2Fwindows-fido-bridge/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mgbowen","download_url":"https://codeload.github.com/mgbowen/windows-fido-bridge/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252593044,"owners_count":21773397,"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":["cygwin","fido","fido-u2f","openssh","openssh-client","u2f","webauthn","windows","wsl","wsl2","yubikey"],"created_at":"2024-08-02T22:01:04.572Z","updated_at":"2025-05-05T23:31:23.061Z","avatar_url":"https://github.com/mgbowen.png","language":"C++","funding_links":[],"categories":["C++"],"sub_categories":[],"readme":"\u003e [!WARNING]\n\u003e **I no longer maintain this repository**\n\u003e\n\u003e I have substantially less free time these days for OSS, I don't use Windows as\n\u003e my daily driver anymore, and there seem to be much better options for using a\n\u003e security key within WSL in 2024 and beyond\n\u003e ([for example](https://archive.is/https://threatzer.com/posts/wsl-yubikeys/)).\n\n# windows-fido-bridge\n\nThis repository implements [an OpenSSH security key\nmiddleware](https://github.com/openssh/openssh-portable/blob/e9dc9863723e111ae05e353d69df857f0169544a/PROTOCOL.u2f)\nthat allows you to use [a FIDO/U2F security\nkey](https://en.wikipedia.org/wiki/Universal_2nd_Factor) (for example, [a\nYubiKey](https://www.yubico.com/products/)) to SSH into a remote server from a\nmachine running Windows 10 with [Windows Subsystem for\nLinux](https://docs.microsoft.com/en-us/windows/wsl/about) or [Cygwin](\nhttps://www.cygwin.com/).\n\n## Requirements\n\nAt a minimum, you must have the following in order to use this repository:\n\n* A local Linux distribution running inside WSL with OpenSSH 8.3 or newer\n  installed.\n  * An earlier version of OpenSSH will not work because of an incompatibility\n    with Microsoft's WebAuthn API.\n* A remote server running OpenSSH 8.2 or newer.\n  * The aforementioned API incompatibility does not affect the remote server, so\n    it **does not** need OpenSSH 8.3.\n* A FIDO/U2F security key that supports Ed25519 or ECDSA.\n\nCygwin is also supported on a best-effort basis; see the Cygwin section under\nTips below.\n\n## Install\n\nYou may want to visit [the\nwiki](https://github.com/mgbowen/windows-fido-bridge/wiki/Installing-a-distro-with-OpenSSH-8.3)\nthat details how to get a Linux distro with a version of OpenSSH that's new\nenough to work with windows-fido-bridge.\n\n### From the apt repository\n\nThe recommended method of installing windows-fido-bridge is to use its apt\nrepository at [apt.mgbowen.dev](https://apt.mgbowen.dev). Go to that link and\nfollow its instructions to set up access to the repository for your operating\nsystem, then run the following:\n\n```\nsudo apt install windows-fido-bridge\n```\n\n### From source\n\nYou can also build this repository from source:\n\n```\nsudo apt install build-essential cmake g++-mingw-w64-x86-64 git\n\ngit clone https://github.com/mgbowen/windows-fido-bridge.git\ncd windows-fido-bridge\nmkdir build\ncd build\ncmake -DCMAKE_BUILD_TYPE=Release ..\nmake -j $(nproc)\nmake test\nsudo make install\n```\n\nThere is also the option of packaging the built binaries into a deb package and\ninstalling that package instead of using `make install`:\n\n```\nsudo apt install debhelper\n\nmake package\nsudo apt install ./windows-fido-bridge_*_*.deb ./windows-fido-bridge-skapi*_*_*.deb\n```\n\nNote that if you install the deb package, apt will place the built binaries in\n`/usr/lib`, whereas `make install` will place them, by default, in\n`/usr/local/lib`. The distinction is important to remember when you set the\n`SecurityKeyProvider` option when calling `ssh` or the `SSH_SK_PROVIDER`\nenvironment variable.\n\n#### Compile-time options\n\nYou may set the following options when you invoke `cmake`:\n\n* `BUILD_TESTS`: Whether or not to build tests. Defaults to `ON`, set to `OFF`\n  to disable.\n* `SK_API_VERSION`: The version of the OpenSSH security key API to target. The\n  following versions are required to use with their respective OpenSSH versions:\n    * `5`: OpenSSH 8.3\n    * `7`: OpenSSH 8.4 (default)\n    * `9`: OpenSSH 8.9\n\n## Use\n\nFirst, you need to generate a key tied to your FIDO/U2F-compliant security key.\nTo do that, you need to tell OpenSSH what middleware library to use. If you used\nthe installation instructions above, you can use the following command:\n\n```\nSSH_SK_PROVIDER=libwindowsfidobridge.so ssh-keygen -t ecdsa-sk\n```\n\nIf everything goes well, you should see a Windows dialog pop up asking you to\nuse your security key. After you confirm and tap your security key, OpenSSH\nshould then write a public/private key pair to disk. After adding the public key\nto your remote server's `.ssh/authorized_keys` file, you can then authenticate\nusing the following command:\n\n```\nssh -oSecurityKeyProvider=libwindowsfidobridge.so remote-server\n```\n\nYou should now be logged in to your remote server!\n\n## Tips\n\n### Turn on debug logging\n\nIf you're having problems and want more information to help you solve it, or if\nyou're just curious about what's going on as windows-fido-bridge executes, you\ncan turn on debug logging by setting the `WINDOWS_FIDO_BRIDGE_DEBUG` environment\nvariable to any value before executing an OpenSSH executable.\n\n### Force user verification\n\n**Note that this is only possible if _both_ your client and server are running\nOpenSSH 8.4 or newer!**\n\nOpenSSH 8.4 added the ability to require user verification in order to log in to\nan SSH server via a security key. This means you can require the user to, e.g.\nprovide a PIN to the security key or place their finger on a security key's\nfingerprint reader (if it has one) before being granted access to a remote\nserver.\n\nWhen using a security key that requires user verification, OpenSSH will prompt\nthe user for their PIN and pass that PIN to the security key middleware, which\nthen passes it to the security key. However, presumably for security reasons,\nMicrosoft's WebAuthn API does not permit a middleware to prompt for a PIN.\nDespite this, OpenSSH will _always_ prompt the user for a PIN before passing\ncontrol to a security key middleware, and OpenSSH does not provide the ability\nto disable this prompt, which means that you are prompted for a PIN twice: once\nfrom OpenSSH and once from Windows.\n\nTo get around this, you can force windows-fido-bridge to create a security key\nassertion with user verification even if OpenSSH is configured not to do so,\nallowing you to only be prompted for a PIN once by Windows. There are two ways\nto enable this behavior:\n\n* When creating an OpenSSH security key-backed SSH key, set the FIDO application\n  to `ssh:windows-fido-bridge-verify-required`, like so:\n  ```\n  SSH_SK_PROVIDER=libwindowsfidobridge.so \\\n      ssh-keygen -t ecdsa-sk -Oapplication=ssh:windows-fido-bridge-verify-required\n  ```\n  The key will be created normally; when you use it to log in,\n  windows-fido-bridge will ask for a PIN (if that's how your security key\n  performs user verification), but OpenSSH will not.\n* Set the `WINDOWS_FIDO_BRIDGE_FORCE_USER_VERIFICATION` environment variable to\n  any value before logging in to a remote server with `ssh`. You do not need to\n  set it before generating the SSH key with `ssh-keygen -t ecdsa-sk`.\n\nNote that it is still possible to create an OpenSSH security key-backed key with\nwindows-fido-bridge that requires user verification using `ssh-keygen\n-Overify-required ...`, and windows-fido-bridge will respect asking for user\nverification when logging in with keys that are configured as such.\n\nFinally, you need to enforce that the remote server checks for user verification\nbefore permitting a user to log in with a security key. You can do so by\nprepending the public SSH key in your `~/.ssh/authorized_keys` file with\n`verify-required`, like so:\n```\n# ~/.ssh/authorized_keys\nverify-required sk-ecdsa-sha2-nistp256@openssh.com AAAA[...]abcdef user@server\n```\n\n### Use with ssh-agent\n\nIf you want to use a security key-backed SSH key with `ssh-agent`, you should\nmake sure to either invoke `ssh-add` with the `-S` argument pointing to\n`libwindowsfidobridge.so` or set the `SSH_SK_PROVIDER` environment variable\nbefore calling `ssh-add`. Note that you **must** specify the full path to the\nlibrary when passing it to `ssh-add` for `ssh-agent` to accept it. For example:\n\n```\nssh-add -S /usr/lib/libwindowsfidobridge.so\n\n# or\n\nSSH_SK_PROVIDER=/usr/lib/libwindowsfidobridge.so ssh-add\n```\n\nYou may also completely omit the explicit library specification if you place the\n`SSH_SK_PROVIDER` environment variable definition in your `.bashrc` or whatever\nyour shell's equivalent file is.\n\n### Use from Windows\n\nIf you want to be able to run `ssh` from a Windows command prompt without first\nbeing in a WSL prompt, you can create a directory somewhere on your Windows\nfilesystem (for example, `C:\\Users\\\u003cusername\u003e\\bin`), add that directory to your\n`PATH`, and create a file inside that directory named `ssh.bat` with the\nfollowing contents:\n\n```\n@wsl ssh %*\n```\n\nIf the WSL distribution you installed windows-fido-bridge in is not your\ndefault, be sure to pass the `--distribution` argument to `wsl` specifying the\nname of the appropriate distribution. Also be sure that you don't have the\nMicrosoft-distributed OpenSSH client installed or that one may be used instead\nof the WSL one.\n\n### Use with Cygwin\n\nwindows-fido-bridge supports Cygwin on a best-effort basis; while the primary\nexecution environment is intended to be WSL, it also happens to be reasonably\neasy to compile on Cygwin as well.\n\nTo compile in a Cygwin environment, ensure the latest stable versions of the\nfollowing packages are installed:\n\n* `cmake`\n* `gcc-g++`\n* `git`\n* `make`\n\nThen, run the standard installation steps as if you were compiling for WSL\n(ignore the `apt` commands, of course). The build system will detect that you're\nbuilding inside Cygwin and adjust the default options accordingly. The default\nbuild artifact will be a library named `cygwindowsfidobridge.dll`, which is the\nfile you should specify when telling SSH what SK middleware to use. For example:\n\n```\n# Generate a security key-backed SSH key:\nSSH_SK_PROVIDER=cygwindowsfidobridge.dll ssh-keygen -t ecdsa-sk\n\n# Use your security key-backed SSH key:\nssh -oSecurityKeyProvider=cygwindowsfidobridge.dll user@remote\n```\n\nAll other functionality, e.g. changing the middleware's behavior via environment\nvariables, works the same as it does in WSL.\n\nNote that you cannot use artifacts targeting Cygwin with a non-Cygwin OpenSSH,\nand attempting to do so will almost certainly result in a crash when attempting\nto pass data back to OpenSSH.\n\n## References\n\n* [Web Authentication: An API for accessing Public Key Credentials, Level\n  1](https://www.w3.org/TR/webauthn/)\n  * The official W3C WebAuthn specification. Microsoft's API seems to be largely\n    based directly on this document.\n* [U2F support in OpenSSH\n  HEAD](https://marc.info/?l=openssh-unix-dev\u0026m=157259802529972\u0026w=2)\n  * Email by Damien Miller announcing the release of OpenSSH's U2F/FIDO support.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmgbowen%2Fwindows-fido-bridge","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmgbowen%2Fwindows-fido-bridge","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmgbowen%2Fwindows-fido-bridge/lists"}