derivepassphrase.git

Add a changelog entry for Windows named pipe support
Parent 863e371
Marco Ricci

Marco Ricci commited on 2026-03-22 22:32:22
Zeige 1 geänderte Dateien mit 101 Einfügungen und 0 Löschungen. 

Also mention the `--ssh-agent-socket-provider` command-line option and
the `vault.ssh-agent-socket-provider` configuration option, and mention
some caveats with the test suite on The Annoying OS.

For developers, also mention related recent changes in the test suite:
non-isolated agents and the PERMITTED_SSH_AGENTS and
NON_REENTRANT_SSH_AGENTS environment variables.
docs/changelog.d/20260322_222936_the-13th-letter_annoying_os_named_pipes.md
Zeige Datei @ 28d6d73
... ... 
@@ -0,0 +1,101 @@
1 
+### Added
2 
+
3 
+  - For `derivepassphrase vault`, support interacting with SSH agents on
4 
+    <abbr title="Microsoft Windows">The Annoying OS</abbr>, using Windows
5 
+    named pipes and the `SSH_AUTH_SOCK` environment variable.
6 
+    Also support the two major SSH agents Pageant ([PuTTY][]) and
7 
+    `ssh-agent` ([OpenSSH][]) specifically, without needing the user to
8 
+    specify the address of the Windows named pipe.
9 
+    [GnuPG][]'s `gpg-agent` (masquerading as OpenSSH's `ssh-agent`) is also
10 
+    known to work.
11 
+
12 
+    This support is based on the [`ctypes.WinDLL`][ctypes.WinDLL] interface,
13 
+    and requires access to the `kernel32.dll` library on <abbr
14 
+    title="Microsoft Windows">The Annoying OS</abbr> at runtime.
15 
+    `derivepassphrase vault --version` will reliably report whether this
16 
+    feature -- the `windows_named_pipe`, `pageant_on_windows` and
17 
+    `openssh_on_windows` SSH agent socket providers -- is available.
18 
+
19 
+    <b>Caveat</b>: On <abbr title="Microsoft Windows">The Annoying
20 
+    OS</abbr>, the user or developer should [mark all SSH agents as
21 
+    non-reentrant](#changed-in-v0.6-non-reentrant-ssh-agents) and run the
22 
+    test suite without parallelization, because the test suite cannot spawn
23 
+    isolated agents on <abbr title="Microsoft Windows">The Annoying
24 
+    OS</abbr>.
25 
+    The OpenSSH agent implementation interacts very badly with the feature
26 
+    detection logic from the test suite, because it shuts down the
27 
+    connection upon negative responses of any kind (in violation of the
28 
+    protocol); the user or developer may want to use GnuPG's emulation
29 
+    instead, or restrict themselves to PuTTY.
30 
+
31 
+  - For `derivepassphrase vault`, support specifying the desired SSH agent
32 
+    socket provider via the command-line option
33 
+    `--ssh-agent-socket-provider` and via the configuration option
34 
+    `ssh-agent-socket-provider` in the `vault` table.
35 
+    The list of available providers can be queried with `derivepassphrase
36 
+    vault --version`.
37 
+    The command-line option takes precedence over the configuration option.
38 
+
39 
+### Changed
40 
+
41 
+  - For developers: The test suite now distinguishes between
42 
+    <dfn>isolated</dfn> SSH agents (spawned and managed by the test suite)
43 
+    and non-isolated ones (spawned by the user, potentially in use by other
44 
+    programs).
45 
+
46 
+    All tests involving SSH agents are included in a separate group, so that
47 
+    the test harness distributes them to the same worker process.
48 
+
49 
+  - For developers: The test suite now supports <b
50 
+    id="changed-in-v0.6-selective-ssh-agent-testing">selectively enabling
51 
+    SSH agents to test with</b> via the `PERMITTED_SSH_AGENTS` environment
52 
+    variable, which takes a comma-separated list of internal IDs of known
53 
+    SSH agent implementations.
54 
+    (Invalid entries are silently ignored.)
55 
+    The test suite will only attempt to spawn or interface with agents of
56 
+    permitted types, and skip tests otherwise.
57 
+
58 
+    Intended to avoid spawning certain SSH agents just because they are
59 
+    installed, or spawning unrelated executables that are mistaken for
60 
+    the respective SSH agent due to identical executable names.
61 
+
62 
+  - For developers: The test suite now supports <b
63 
+    id="changed-in-v0.6-non-reentrant-ssh-agents">marking SSH agents as
64 
+    non-reentrant</b> via the `NON_REENTRANT_SSH_AGENTS` environment
65 
+    variable, which takes a comma-separated list of internal IDs of known
66 
+    SSH agent implementations.
67 
+    (Invalid entries are silently ignored.)
68 
+    The test suite will avoid constructing multiple SSH agent clients
69 
+    connecting to such an SSH agent by reusing client instances, or skipping
70 
+    the test altogether.
71 
+
72 
+    Intended to avoid deadlocks with shared agent instances that do not
73 
+    cleanly support multiple simultaneous clients.
74 
+
75 
+      - [GnuPG][] v2.4.8 appears to use a single thread to both accept
76 
+        incoming SSH agent client connections and service them;
77 
+        running two clients simultaneously blocks the second client from
78 
+        connecting until the first client disconnects.
79 
+        This precludes normal usage in the test suite, where the test suite
80 
+        keeps a client connection to the agent open for the duration of the
81 
+        test run (to upload test keys at the beginning and remove them at
82 
+        the end).
83 
+
84 
+      - Pageant principally supports multiple simultaneous clients.
85 
+        However, the test suite sporadically triggers errors where responses
86 
+        from Pageant contain extra blocks of NUL characters, confusing
87 
+        `derivepassphrase`.
88 
+        We have not observed any such errors yet when treating Pageant as
89 
+        non-reentrant.
90 
+
91 
+        (So far, we have *only* been able to trigger these errors during
92 
+        test suite runs, not during instrumented calls specifically
93 
+        attempting to trigger this behavior.
94 
+        We are also unsure if this is a bug in Pageant, a bug in
95 
+        `derivepassphrase`, a bug or a limitation in Python's [`ctypes`][]
96 
+        implementation, or a bug or a limitation of Windows named pipes, or
97 
+        perhaps some combination of the aforementioned.)
98 
+
99 
+[OpenSSH]: https://www.openssh.org
100 
+[PuTTY]: https://putty.software
101 
+[GnuPG]: https://gnupg.org
0 102