/OmniSSHAgent

Integrated ssh-agent for windows. (pageant compatible. openSSH ssh-agent etc ..)

Primary LanguageGoApache License 2.0Apache-2.0

OmniSSHAgent

OmniSSHAgent

About

Unifies the chaotic ssh-agent state under Windows.

The Chaotic State of SSH-Agent on Windows

There are several different communication methods for ssh-agent in Windows, and it is very complicated to use and configure them. The following diagram shows the current communication methods for Windows ssh-agent. windows-ssh-agent-chaosmap

Connection diagram of OmniSSHAgent

OmniSSHAgent is a program to simplify what used to be a chaotic situation, as shown in the following figure. OmniSSHAgentmap

Required environment for operation

The following interfaces are supported

  • pageant.exe(PuTTY) shared memory
  • Unix domain socket for WSL2
  • NamedPipe on Windows
  • Unix domain socket for WSL1
  • Unix domain socket for MSYS2(Cygwin) ( #1 )

Usage

  1. Download OmniSSHAgent.zip from https://github.com/masahide/OmniSSHAgent/releases/latest, unzip it, and place it in a folder of your choice.
  2. If you are using Windows native ssh-agent, you'll need to stop and disable it. Open powershell with administrator privileges and execute the following commands.
Stop-Service ssh-agent
Set-Service -StartupType Disabled ssh-agent
  • Alternatively, you can set it through the GUI if you prefer.Bring up the start menu and type Services. You’ll see the Services app listed. Once the Services app is open, find the OpenSSH Authentication Agent service and set the Service Status to Stop and the Startup Type to Disabled.

  1. If you are using PuTTY Pageant - stop it.

  2. Launch OmniSSHAgent.exe by double-clicking.

  3. Press the Open new file button to add a private key file. Or you can use ssh-add command or KeePassXC to add your private key.

Registering for launch on boot

OmniSSHAgent does not have an installer, nor registers itself to start upon boot. You'll need to do the following to register it:

  • Press the Windows logo key + R, type shell:startup, then click OK. This opens the Startup folder.
  • Copy and paste the shortcut to the OmniSSHAgent.exe from the file location to the Startup

Using with WSL2

Setting up socat pipe in Ubuntu(WSL2).

Choose the instructions for your favourite shell below. If your shell isn't listed here you can convert the bash script to your shell syntax and send a PR to add it to the repo.

Bash (and all POSIX-compliant shells)
  1. Download ubuntu.setup.sh with the following command:
mkdir -p $HOME/omni-socat
curl -sL https://raw.githubusercontent.com/masahide/OmniSSHAgent/main/hack/ubuntu.setup.sh -o $HOME/omni-socat/ubuntu.setup.sh
  1. Add the following line to ~/.bashrc, ~/.zshrc, or whatever file is applicable to your shell:
source $HOME/omni-socat/ubuntu.setup.sh
Fish
  1. Download ubuntu-fish.setup.fish with the following command:
mkdir -p $HOME/omni-socat
curl -sL https://raw.githubusercontent.com/masahide/OmniSSHAgent/main/hack/ubuntu-fish.setup.fish -o $HOME/omni-socat/ubuntu-fish.setup.fish
  1. Add the following line to ~/.config/fish/config.fish:
. $HOME/omni-socat/ubuntu-fish.setup.fish

Setting up socat pipe in rocky linux.

  1. Download rocky.setup.sh with the following command
mkdir -p $HOME/omni-socat
curl -sL https://raw.githubusercontent.com/masahide/OmniSSHAgent/main/hack/rocky.setup.sh -o $HOME/omni-socat/rocky.setup.sh
  1. Add the following line to ~/.bashrc, ~/.zshrc, or whatever file is applicable to your shell:
source $HOME/omni-socat/rocky.setup.sh

Using with WSL1

Setting up Unix doman socket in ubuntu environment.

  1. Check the setting of Unix domain socket file path(WSL1): in OmniSSHAgent. For example, if you have the following settings.. (UserName varies depending on your environment) C:\Users\<UserName>\OmniSSHAgent.sock The WSL1 path will be /mnt/c/Users/<UserName>/OmniSSHAgent.sock.

  2. Add the following line to ~/.bashrc

export SSH_AUTH_SOCK=/mnt/c/Users/<UserName>/OmniSSHAgent.sock

Using with Cygwin/MSYS2/Git for windows/(GitBash)

  1. Check the setting of Cygwin Unix domain socket file path(MSYS2): in OmniSSHAgent.

    • For example, if you have the following settings.(UserName varies depending on your environment).
    • C:\Users\<UserName>\OmniSSHCygwin.sock.
    • The Cygwin path will be /mnt/c/Users/<UserName>/OmniSSHCygwin.sock.

  2. On the Windows taskbar, right-click the Windows icon and select System. In the Settings window, under Related Settings, click Advanced system settings.

    • On the Advanced tab, click Environment Variables.
    • Users variables Click on Create new to create a new environment variable.
    • Set the following values(UserName varies depending on your environment).
Variable name:  SSH_AUTH_SOCK
Variable Value: /mnt/c/Users/<UserName>/OmniSSHAgent.sock

Using with 1Password proxy mode

This is a mode using 1Password's ssh-agent function as a backend as shown in the following figure. 1Password-Proxy-mode

By setting "Enable proxy mode for 1Password key-agent" in the configuration, OmniSSHAgent becomes a Proxy that works with 1Password's ssh-agent as a backend.

When "Enable proxy mode for 1Password key-agent" is enabled, OmniSSHAgent operates as a mere proxy, and therefore, private keys cannot be added.

Supported key file formats

  • PuTTY private key file (.ppk) file format
  • OpenSSH format

Supported key formats

  • rsa
  • ecdsa
  • ed25519

(dsa, ecdsa-sk, ed25519-sk are not supported)

FAQ

Where is the passphrase for the private key stored?

It's stored in Windows Credential Manager.

Screen shot