Windows-only SSH agent (Go) exposing Windows Certificate Store / smart-card keys over multiple SSH agent protocols. Fork of buptczq/WinCryptSSHAgent — module path is still github.com/buptczq/WinCryptSSHAgent; use that in imports.
- Do not preserve backward compatibility.
- Choose the simplest implementation that fully meets the current requirements.
- Prefer established, well-maintained libraries over custom implementations.
go.modreplaceshattya/go.notify => boypt/go.notify v0.1.1(adds missingwindows/arm64syscall bindings, isomorphic to amd64).- Drop the replace once upstream merges/releases an equivalent (go.notify with arm64 files).
- No test suite exists. Verification = a successful cross-compile +
go vet. Do not inventgo testexpectations. go vet ./...has pre-existingpossible misuse of unsafe.Pointerwarnings (utils/pageant.go,capi/wincapi.go- Win32 interop). Don't treat them as regressions; just don't add new ones.- The app is GUI + Win32 (
x/sys/windows, winio, WMI): it cannot run on Linux/macOS. Cross-compile instead:GOOS=windows GOARCH=amd64 go build— quick check buildmake— full 64-bit build: syncsversioninfo.jsonfrom the latestv*git tag (requiresjq), runsgo generate, injects version ldflags (-X main.agentVersion/...), outputsWinCryptSSHAgent.exe. Restoresversioninfo.jsonafterward locally (CI keeps it changed).make all→ amd64 + arm64;make <arch>(amd64/arm64) → single arch;make cleanremoves built exes and generated*.syso.- When building manually with
go build, add-ldflags "-w -s -H=windowsgui"(same as inMakefile).
go generaterunsgoversioninfowith-platform-specific— install first:go install github.com/josephspurrier/goversioninfo/cmd/goversioninfo@latest. It generatesresource_windows_<arch>.sysofiles (all gitignored via*.syso).- Known quirk: the
Makefileinjects-X main.agentCommit, butmain.godeclaresagentBuildHash— the linker silently ignores-Xfor nonexistent vars, so the commit hash never lands in the binary.
- Known quirk: the
- Git remotes:
origin= upstreambuptczq/WinCryptSSHAgent(no push access),pt= forkboypt/WinCryptSSHAgent(the push target;mastertrackspt). Release flow:git push pt masterfirst, then create the lightweight tag (git tag vX.Y.Z) andgit push pt v*— nevergit push origin(permission denied). CI only needs the tag (it checks out the tag ref with full history), but mainline must be pushed explicitly: pushing a tag uploads the commits without moving the remotemasterref. - CI (
.github/workflows/go.yml) triggers only on pushing av*tag: builds amd64 + arm64 viamake alland uploadsWinCryptSSHAgent*.exeto a prerelease. Full git history is fetched because the version derives fromgit describe. - House style after CI: edit the release to a formal/latest one with notes, e.g.
gh release edit v1.1.14 --notes-file <md> --prerelease=false --latest. Tags are lightweight.
main.go— entrypoint: single-instance mutex, systray, debug-log setup, confirm-mode resolution, selects agent backend, launches allapp.Applications.app/— one file per transport/protocol (WSL, Hyper-V vsock, Cygwin socket, named pipe, Pageant, XShell, pubkey view). Each implements theApplicationinterface (app/app.go); new apps must be added to theapplicationsslice inmain.go.sshagent/— agent backends:CAPIAgent(Windows CryptoAPI),KeyRingAgent(in-memory fallback),HVAgent(Hyper-V guest mode),WrappedAgent(composes backends).SourceAgenttags requests with the transport's full name so backends can reportSource:.capi/— CryptoAPI bindings;utils/— Win32 helpers (UAC, WSL2 detection, Hyper-V, notifications, confirm dialog + registry).- Runtime mode switch in
main.go: ifConnectHyperV(dial toHvsockGUIDParent) succeeds, the process is inside a guest VM and acts as an agent client (HVAgent) — all signing is forwarded over vsock to the host's WinCryptSSHAgent. On the physical host the dial fails (not supported), so it serves local cert-store keys via CAPI. WSL2/Linux guests use the same vsock service but connect via socat (byte-forwarder) rather than running this exe. - Systray menu (
github.com/hattya/go.notify): the native popup is rebuilt from the Go-side item list on every right-click, andsysTray.CreateMenu()replaces that list.buildMenu()inmain.gore-registers all app items plus the Manual/Auto Confirm items — call it from the event-loop goroutine whenever menu state changes.
WCSA_DEBUG=1→ redirects stdout/stderr to%USERPROFILE%\WCSA_DEBUG.log(no console; binary is built-H=windowsgui).-iinstalls the Hyper-V guest communication service (needs elevation);-disable-capiforces in-memory keyring;-disable-pin-cacheclears smart-card PIN cache after each op.WCSA_CHECKSVR=1→ before each CAPI signing, warns if the Smart Card service is stopped and offers to restart it.- Confirm mode:
-confirmflag orWCSA_CONFIRM=1forces Manual Confirm and writes the registry; otherwise state loads fromHKCU\Software\WinCryptSSHAgentDWORDConfirmRequired(absent → Auto). Manual = blocking Yes/No dialog per signing and the "Authenticated" toast is suppressed; Auto = silent signing + toast.
- Confirm dialog =
MessageBox(MessageBoxIndirectwithMB_USERICON+ plain-MessageBoxfallback inutils/confirm.go).TaskDialogIndirectwas tried and reverted — its popup is noticeably slower. Keep the manifest anyway: Common-Controls v6 givesMessageBoxmodern visuals for free. - Manifest wiring:
versioninfo.jsonManifestPath=app.manifest(Common-Controls 6.0), embedded bygoversioninfoduringgo generate. It must be committed — theMakefilereverts uncommittedversioninfo.jsonlocally after a successful build (restore-version; on a failed build restore it manually withgit checkout -- versioninfo.json), silently dropping the manifest on the next generate. - goversioninfo id quirk: the manifest occupies resource id 1, shifting the icon group from id 1 to id 2. All icon loads handle both layouts:
initSystraytriesLoadIcon(2)thenLoadIcon(1);messageBoxConfirmtries iconResId 2, then 1, then plainMessageBox. - Caption icon:
MessageBoxresolves the title-bar icon as exe icon id 1 and falls back to the genericIDI_APPLICATIONicon after the shift. The foreground watcher (utils/foreground.go) setsWM_SETICON(ICON_SMALL+ICON_BIG) with the app icon (ids {2,1},LR_SHARED) once the dialog appears. - Focus: a background tray process cannot rely on
MB_SETFOREGROUND(foreground-lock no-op).raiseDialogWhenShownpins the OS thread, finds the#32770dialog viaEnumThreadWindows, and forces foreground via temporaryAttachThreadInput. Applies to any thread-owned modal dialog. - Debugging dialogs from Linux (cannot run): inspect PE resources (e.g. throwaway
debug/pelister) forRT_GROUP_ICON/RT_MANIFESTids;WCSA_DEBUG=1log captures Win32HRESULTs.
- Per README: use GitHub issues for everything; discuss non-trivial changes in an issue before a PR.
- Comments and some script messages are a mix of English and Chinese — match the file you're editing.
- User-facing prompts (dialogs, toasts, menus) are English-only.
- User-facing label for the transport origin is
Source:(notChannel:) in both dialogs and notifications.