microsoft / microsoft/WSL

Expose Windows SSH-Agent inside WSL environments

Open
#11,207 11 comments 46 reactions 0 assignees View on GitHub
feature
Dominant language
C++
Stars
33.7k
Forks
1.8k
Avg merge
3d 17h
Merged PRs (30d)
116

Description

**Is your feature request related to a problem? Please describe.**

I often use SSH keys for authentication. Basically, whenever I want to connect to another server or clone a repository on GitHub, I use SSH. I am always frustrated when I cannot clone a repository or connect to one of my servers from within WSL. I would love to be able to access the SSH agent which runs outside WSL from within all of my WSL instances.

**Describe the solution you'd like**

* Expose a unix domain socket at `/mnt/wsl/ssh-agent` or `/mnt/wslg/ssh-agent`. (Since you are already exposing various sockets within `/mnt/wslg/`, I assume this should be possible?)
* When a client connects to `/mnt/wsl[g]/ssh-agent`, try to connect to the named pipe provided by the ssh-agent of Windows. Forward all traffic in both directions.
* If the environment variable `SSH_AUTH_SOCK` is defined outside the WSL environment, it should point to a named pipe. This is the named pipe you should use.
* I am not sure if there is a fallback which should be used if the environment variable is not set.
* Set environment variable `SSH_AUTH_SOCK` within WSL to `/mnt/wsl[g]/ssh-agent`. (You may skip this step if you cannot control the environment variables inside WSL.)

*Note: I am not sure if there are security considerations which need to be made. If possible, `/mnt/wsl[g]/ssh-agent` should probably only be accessible by the main user of the Linux distro. Besides, my understanding was that using WSL was not really supported in a context where strict isolation of different users on one Windows installation is required.*

**Describe alternatives you've considered**

As far as I am aware, there are currently three noteworthy protocols for SSH agents on Windows. Here are the three corresponding applications:

* Native ssg-agent for Windows
* MSYS2 ssh-agent
* Pageant (PuTTY authentication agent)

I assume that the native ssh-agent and the ssh-agent of MSYS2 are technically using the same protocol, but just a different transport layer. While the ssh-agent of Windows is using named pipes, MSYS2 is using their compatibility layer for unix domain sockets.

While it would be technically possible to implement a solution for each of the three agents, relying on the protocol of the native ssh-agent seems to be the most straightforward solution. For supporting MSYS2, we would first need to implement the relevant parts of the MSYS2 compatibility layer. For Pageant, we may have to implement some protocol translation layer. Also note that [Pageant already supports the native ssh-agent protocol](https://the.earth.li/~sgtatham/putty/0.80/htmldoc/Chapter9.html#pageant-cmdline-openssh).

The biggest problem I see is that the ssh-agent from Windows and MSYS2 are both using the same environment variable `SSH_AUTH_SOCK`. This naming conflict means that you cannot use the ssh-agent of Windows if you are also using some ssh-agent for MSYS2. This is especially annoying because Git for Windows uses the ssh client of MSYS2 by default. The Git installer technically asks you if you want to use the native ssh client instead, but I have never tried it. I am not sure if “forcing” users to the native client if they want to benefit from this feature may have unfortunate side effects. If the relevant parts of the MSYS2 compatibility layer are easy to implement, it might make sense to support it as well.

Note: I am currently using Pageant and the script `cmd/start-ssh-pageant.cmd` which comes with Git for Windows. This means, on my system, `SSH_AUTH_SOCK` currently points to a unix domain socket of MSYS2. This means I would also be affected by the problem I just described.

There was also #10512 which suggested to automatically start an ssh-agent with WSL. The ticket was closed because starting an ssh-agent inside WSL would be the responsibility of the Linux distribution. Besides, it would also be far less useful as you would still have to set up an SSH-key for each WSL-instance separately. This feature request strives to make SSH work out of the box in all WSL instances if you have some ssh-agent enabled on Windows.

**Additional context**

* Some official documentation about how to start the SSH agent in windows.
https://learn.microsoft.com/en-us/windows-server/administration/openssh/openssh_keymanagement#user-key-generation
* Pageant did support exposing the agent to WSL1, but the solution doesn't work with WSL2.
https://the.earth.li/~sgtatham/putty/0.80/htmldoc/Chapter9.html#pageant-cmdline-unix
* There were also third party implementations for WSL1, which stopped working with WSL2 due to #5961. See https://github.com/benpye/wsl-ssh-pageant/issues/33 for example.
* There are also third-party solutions for WSL2, but I have never tried them. They are also a bit annoying to set up for each WSL instance.
https://github.com/BlackReloaded/wsl2-ssh-pageant
https://github.com/rupor-github/wsl-ssh-agent#wsl2-compatibility

Contributor guide

Open the contributing guide

Research direction

Start by reading cmd/start-ssh-pageant.cmd and the linked WSL2 compatibility reports to understand existing agent exposure approaches. Then locate WSL's existing socket exposure and Windows integration entry points; done means forwarding the Windows SSH-agent named pipe through a Unix socket in WSL, handling SSH_AUTH_SOCK, and respecting the stated access restrictions.

Written by the indexing model from the issue text.

Assessment

Domain
networking, operating-systems, security
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.