Merge pull request #78 from BriceGagnageRenault/master

Updated Windows configuration and new WSL support

README.md

@@ -49,6 +49,7 @@ If you have a comment or suggestion, please open an [issue](https://github.com/d
   - [GitHub](#github)
   - [OpenBSD](#openbsd)
   - [Windows](#windows)
+  - [Windows Subsystem for Linux (WSL)](#wsl)
 - [Troubleshooting](#troubleshooting)
 - [Notes](#notes)
 - [Similar work](#similar-work)
@@ -1384,27 +1385,77 @@ Install `pcsc-tools` and enable with `doas rcctl enable pcscd`, then reboot in o
 
 ## Windows
 
-Export the SSH key from GPG:
+Windows can already have some virtual smartcard readers installed, like the one provided for Windows Hello. To ensure your Yubikey is the correct one used by scdaemon, you should add it to its configuration. You will need your device's full name. To find out what is your device's full name, plug your Yubikey, open the Device Manager, select "View->Show hidden devices". Go to the Software Devices list, you should see something like `Yubico YubiKey OTP+FIDO+CCID 0`. The name slightly differs according to the model. Thanks to [Scott Hanselman](https://www.hanselman.com/blog/HowToSetupSignedGitCommitsWithAYubiKeyNEOAndGPGAndKeybaseOnWindows.aspx) for sharing this information.
 
+- Create or edit %APPDATA%/gnupg/scdaemon.conf, add `reader-port <your yubikey device's full name>`.
+- In %APPDATA%/gnupg/gpg-agent.conf, add:
 ```
-$ gpg --export-ssh-key $USERID
+enable-ssh-support
+enable-putty-support
 ```
 
+- Open a command console, restart the agent:
+```
+> gpg-connect-agent killagent /bye
+> gpg-connect-agent /bye
+```
+- Enter `> gpg --card-status`, now you should see your Yubikey's details.
+- Import your [public key](#export-public-key): `> gpg --import <path to public key file>`
+- Trust it: [Trust master key](#trust-master-key)
+- Retrieve your public key's id: `> gpg --list-public-keys`
+- Export the SSH key from GPG: `> gpg --export-ssh-key <your public key's id>`
+
 Copy this key to a file for later use. It represents the public SSH key corresponding to the secret key on your YubiKey. You can upload this key to any server you wish to SSH into.
 
-To authenticate SSH sessions via YubiKey, enable Gpg4Win's PuTTY integration. Create a file named `gpg-agent.conf` and place it in the directory `C:\%APPDATA%\gnupg`.
-The file should contain the line `enable-putty-support`.
+- Create a shortcut that points to `gpg-connect-agent /bye` and place it in your startup folder `shell:startup` to make sure the agent starts after a system shutdown. Modify the shortcut properties so it starts in a "Minimized" window, to avoid unnecessary noise at startup.
+
+Now you can use PuTTY for public key SSH authentication. When the server asks for public key verification, PuTTY will forward the request to GPG, which will prompt you for your PIN and authorize the login using your YubiKey.
+
+## WSL
+The goal here is to make the SSH client inside WSL work together with the Windows agent you are using (gpg-agent.exe in our case). Here is what we are going to achieve:
+![WSL agent architecture](media/schema_gpg.png)
+**Note**: this works only for SSH agent forwarding. Real GPG forwarding (encryption/decryption) is actually not supported. See the [weasel-pageant](https://github.com/vuori/weasel-pageant) readme for further information.
 
-Then, open a terminal and run the following commands:
+### Prerequisites
+- Install Ubuntu >16.04 for WSL
+- Install Kleopatra
+- [Windows configuration](#windows)
 
+### WSL configuration
+- Download or clone [weasel-pageant](https://github.com/vuori/weasel-pageant).
+- Add `eval $(/mnt/c/<path of extraction>/weasel-pageant -r -a /tmp/S.weasel-pageant)` to your .bashrc or equivalent.
+**Note**: we use a named socket here so we can use it in the RemoteForward directive of the .ssh/config file.
+- Source it `$ . ~/.bashrc`.
+- You should be able to see your SSH key with `$ ssh-add -l`.
+- Edit your `~/.ssh/config` file.
+- For each host you want to use agent forwarding, add:
 ```
-> gpg-connect-agent killagent /bye
-> gpg-connect-agent /bye
+ForwardAgent yes
+RemoteForward <remote ssh socket path> /tmp/S.weasel-pageant
 ```
+**Note**: the remote ssh socket path can be found by executing `$ gpgconf --list-dirs agent-ssh-socket` on the host.
 
-Create a shortcut that points to `gpg-connect-agent /bye` and place it in your startup folder to make sure the agent starts after a system shutdown.
+### Remote host configuration
+- Add to your .bashrc or equivalent:
+```
+export SSH_AUTH_SOCK=$(gpgconf --list-dirs agent-ssh-socket)
+export GPG_TTY=$(tty)
+```
+- Edit your /etc/ssh/sshd_config and add:
+```
+AllowAgentForwarding yes
+StreamLocalBindUnlink yes
+```
+- Reload the ssh daemon (e.g. `$ sudo service sshd reload`).
 
-Now you can use PuTTY for public key SSH authentication. When the server asks for public key verification, PuTTY will forward the request to GPG, which will prompt you for your PIN and authorize the login using your YubiKey.
+### Final test
+- Unplug your Yubikey, disconnect or reboot.
+- Log back on Windows, open a WSL console and enter `$ ssh-add -l`, you should see nothing.
+- Plug your Yubikey, enter the same command, you should see your ssh key.
+- Log in to your remote host, you should have the pinentry popup/window asking for your Yubikey pin.
+- On your remote host, type `$ ssh-add -l`. If you see your ssh key, that means your forwarding works !
+
+**Note**: you can chain the agent forwarding through multiple hosts, you just have to follow the same [protocol](#remote-host-configuration) to configure each host.
 
 # Troubleshooting
 
@@ -1454,3 +1505,4 @@ Now you can use PuTTY for public key SSH authentication. When the server asks fo
 * https://alexcabal.com/creating-the-perfect-gpg-keypair/
 * https://www.void.gr/kargig/blog/2013/12/02/creating-a-new-gpg-key-with-subkeys/
 * https://evilmartians.com/chronicles/stick-with-security-yubikey-ssh-gnupg-macos
+* https://www.hanselman.com/blog/HowToSetupSignedGitCommitsWithAYubiKeyNEOAndGPGAndKeybaseOnWindows.aspx