derivepassphrase.git

@@ -8,7 +8,7 @@

       - [yet to be scheduled](index.md){: .unscheduled }

 ???+ bug "things to fix"

-      - [windows-ssh-agent-support][]{: .scheduled-next }

+    <i>no entries</i>

 ???+ wish "things to add"

       - [conventional-configurable-text-styling][]{: .unscheduled }

@@ -29,6 +29,7 @@

       - [remove-pageant-build-info-check][]{: .fixed }

       - [single-toplevel-module][]{: .fixed }

       - [test-filesystem-isolation][]{: .fixed }

+      - [windows-ssh-agent-support][]{: .fixed }

 ??? wish-success "things added"

@@ -1,26 +1,32 @@

 # `derivepassphrase` bug windows-ssh-agent-support

-???+ bug "Bug details: Support PuTTY/Pageant (and maybe OpenSSH/`ssh-agent`) on Windows"

+???+ bug-success "Bug details: Support PuTTY/Pageant (and maybe OpenSSH/`ssh-agent`) on Windows"

     <table id="bug-summary" markdown>

         <tr><th scope=col>Class<td><i>bug</i><td>This is clearly an actual problem we want fixed.

         <tr><th scope=col>Priority<td><i>high</i><td>This should be fixed in the next release.

         <tr><th scope=col>Difficulty<td><i>taxing</i><td>Needs external things we don't have: standards, users, et cetera.

         <tr><th scope=col>Present-in<td colspan=2>0.1.0 0.1.1 0.1.2 0.1.3 <b>0.2.0</b> 0.3.0 0.3.1 0.3.2 0.3.3 0.4.0 0.5 0.5.1 0.5.2

+        <tr><th scope=col>Fixed-in<td colspan=2>[010e3e9c6c9d162d32d0fb2dd0bccbfd13747c42](https://git.schokokeks.org/derivepassphrase.git/010e3e9c6c9d162d32d0fb2dd0bccbfd13747c42)

     </table>

-The SSH agent support in the default “vault” scheme assumes a UNIX host system, where all sensible SSH agent implementations use UNIX domain (`AF_UNIX`) sockets to connect the SSH client to the SSH agent, and expose the name of the socket in the `SSH_AUTH_SOCK` environment variable.

+The SSH agent support in the default “vault” scheme originally assumed a UNIX host system, where all sensible SSH agent implementations use UNIX domain (`AF_UNIX`) sockets to connect the SSH client to the SSH agent, and expose the name of the socket in the `SSH_AUTH_SOCK` environment variable.

-Windows historically did not support UNIX domain sockets, so portable programs using UNIX domain sockets would need to resort to other inter-process communication designs when ported to Windows. (A TCP/IP port on `localhost` plus an authentication token seems to be a common design, e.g. [GnuPG 2.3](https://lists.gnupg.org/pipermail/gnupg-devel/2021-March/034795.html).)

+Windows historically did not support UNIX domain sockets. Portable programs using UNIX domain sockets usually resort to other inter-process communication designs when ported to Windows, e.g. a TCP/IP port on `localhost` plus an authentication token ([GnuPG 2.3](https://lists.gnupg.org/pipermail/gnupg-devel/2021-March/034795.html)), or Windows named pipes (PuTTY/Pageant, and OpenSSH-on-Windows).

-PuTTY/Pageant uses (Windows) named pipes, presumably with a fixed address.  Annoyingly, stock Python does not support connecting to Windows named pipes: while UNIX domain sockets can be opened by the standard C open(3) call, Windows named pipes need a special Win32 API call to open, which Python does not bind.

+Stock Python does not support connecting to Windows named pipes: this requires binding the `kernel32.dll` `CreateFileW` function, which Python does not readily provide.

+As a result, while `derivepassphrase` does not actively use Windows-incompatible code for SSH agent handling, `derivepassphrase` cannot straightforwardly connect to the two main Windows SSH agent implementations.

-OpenSSH for Windows uses yet other means of advertising and of connecting to the running agent, [seemingly incompatible with the UNIX domain socket support in Windows 10 and later](https://github.com/PowerShell/Win32-OpenSSH/issues/1761).

+<b>Therefore</b>, implement specific support on Windows to locate and connect to running Pageant or OpenSSH agent instances.

-As a result, while `derivepassphrase` does not actively use Windows-incompatible code for SSH agent handling, the two main Windows SSH agent implementations likely cannot be straightforwardly connected to `derivepassphrase`.

+--------

-<b>Therefore</b>, implement specific support on Windows to locate and connect to running Pageant or OpenSSH agent instances.

+??? info "Historical notes (September–October 2024)"

----

+    Originally, we assumed that Pageant used a fixed address.  That turned out to be false: Pageant's named pipe address is a security capability, so it must be (computationally) unguessable.

+

+    Originally, we assumed that OpenSSH for Windows used yet other means of advertising and of connecting to the running agent, [seemingly incompatible with the UNIX domain socket support in Windows 10 and later](https://github.com/PowerShell/Win32-OpenSSH/issues/1761).  That turned out to be false: OpenSSH for Windows uses named pipes with a fixed address, and the agent runs as a system service.

+

+    --------

     <strong>Help wanted!</strong> As we have neither Windows experience nor Windows hardware to test this on, please get in touch if you can

@@ -42,3 +48,23 @@ Given this situation, the most sensible thing to do is to give up on waiting for

 [ANNOUNCEMENT]: https://devblogs.microsoft.com/commandline/af_unix-comes-to-windows/

 [PUTTY_PIPE_NAME]: https://git.tartarus.org/?p=simon/putty.git;a=blob;f=windows/utils/agent_named_pipe_name.c;h=aa64b3f60df455e06d6bc1b6c47923143b7a2dda;hb=a8601a72a918dfc2a8e8536a77139d7f37700044

+

+--------

+

+- July 2025: Now having access to a Windows machine, and a somewhat clearer understanding of how Python interfaces with external system libraries, start work on bringing support for Windows named pipes to `derivepassphrase`.

+

+- August 2025: Introduce "SSH agent socket providers", an abstraction layer for (system-specific) code that constructs sockets connected to an SSH agent.

+

+- November 2025: Finish work on SSH agent socket providers, particularly the restructuring of the test suite into "normal" and "heavy-duty" tests, the introduction of faked SSH agents (for testing purposes), and the parametrized testing of SSH agent interactions with all available SSH agent socket providers.

+

+- December 2025: Implement the first successful connection from Python/[`ctypes`][] to Pageant and GnuPG on Windows.

+

+- January 2026: Redo the test suite machinery *again*, because SSH agents on Windows are hard to isolate from each other, and the test suite is not prepared to deal with shared external resources just yet. Encounter lockups with GnuPG's OpenSSH emulation (consistently), and message corruption when talking to Pageant (very sporadically, only in the test suite but never in proof-of-concept scripts, and even when access to Pageant is protected by a lock).

+

+- February 2026: Distinguish "non-reentrant" SSH agents from "reentrant" ones; the former cannot serve more than one client at once. This works around the lockups in GnuPG's OpenSSH emulation.

+

+- February 2026: Support configuring the desired SSH agent socket provider in the configuration file and on the command-line. Update the manpages to reflect this.

+

+- March 2026: Observe that when treating Pageant as non-reentrant, message corruption has not happened anymore.

+

+- March 2026: Finish updating the documentation: a new tutorial, and new agent-specific notes for the "SSH key" how-to and reference page.