[3/3] Add Windows SSH server support

[fdcastel]

Based on #479 -- Closes #370

Adds full support for running opkssh as an SSH AuthorizedKeysCommand on Windows OpenSSH servers, including installation scripts, platform-specific path handling, and integration test workflows.

This is the third and final PR splitting the work from #389.

How to test

# Setup OpenSSH Server
Add-WindowsCapability -Online -Name OpenSSH.Client~~~~0.0.1.0
Add-WindowsCapability -Online -Name OpenSSH.Server~~~~0.0.1.0
Start-Service sshd
Set-Service -Name sshd -StartupType 'Automatic'
Get-NetFirewallRule -Name "OpenSSH-Server-In-TCP" | Set-NetFirewallRule -Profile Any

#
# Setup opkssh server
#   Unofficial build from https://github.com/fdcastel/opkssh/releases which includes the updates from this PR.
#
$version = 'v0.14.0-win'
$repo = 'fdcastel/opkssh'

# Download the install script to $env:TEMP folder
Set-ExecutionPolicy Bypass -Scope Process -Force
[System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072
$ProgressPreference = 'SilentlyContinue'
$installerUrl = "https://github.com/$repo/releases/download/$version/Install-OpksshServer.ps1"
Invoke-WebRequest -Uri $installerUrl -OutFile $env:TEMP/Install-OpksshServer.ps1

& $env:TEMP/Install-OpksshServer.ps1 -InstallVersion $version -GitHubRepo $repo -Verbose
# The system PATH has been updated, but you’ll need to reload your shell for the changes to take effect. 

# Alternatively, you can run the following command to refresh the PATH in your current session.
$env:Path = (Get-ItemProperty 'HKLM:\System\CurrentControlSet\Control\Session Manager\Environment').Path + ';' + `
            (Get-ItemProperty 'HKCU:\Environment').Path

# Authorize user
opkssh add administrator <YOUR-EMAIL> <YOUR-PROVIDER>

Tested on

• Windows Server 2025
• Windows Server 2022

Changes

Windows installation scripts (scripts/windows/)

• Install-OpksshServer.ps1 — Fully automated installer for opkssh on Windows SSH servers. Handles:

  • Downloading and installing the opkssh binary
  • Configuring sshd_config for AuthorizedKeysCommand
  • Creating the opksshuser service account (for pre-Server 2025 systems)
  • Setting up correct NTFS ACLs on all configuration files
  • Proper PATH management (handles Windows REG_EXPAND_SZ registry values)
  • Detection of OpenSSH version for AuthorizedKeysCommandUser support (System account on 8.9+)

• Uninstall-OpksshServer.ps1 — Clean uninstaller that reverses all installation changes.

• Test-OpksshInstallation.ps1 — Post-installation validation script.

• test/Install-OpksshServer.Tests.ps1 — Pester tests for the installer.

Platform-specific paths and logging

• logpath_unix.go / logpath_windows.go — Platform-specific log file paths (/var/log/opkssh.log on Unix, %ProgramData%\opk\opkssh.log on Windows).
• main.go: Updated verify command to use platform-independent configuration paths via GetSystemConfigBasePath().

OpenSSH version handling

• main.go (isOpenSSHVersion8Dot1OrGreater): Updated version parser to handle Windows OpenSSH version format (e.g., OpenSSH_for_Windows_9.5p2, LibreSSL 3.8.2) in addition to standard Unix format.
• internal/sysdetails/openssh.go: Enhanced OpenSSH version detection with OS-specific methods.
• internal/sysdetails/os.go: Added OS name detection utility.

ReadHome for Windows

• commands/readhome_windows.go: Windows implementation for reading user home directory policy files, resolving user profile paths from the Windows registry.

Build and release

• .goreleaser.yaml:
  • Removed Windows ARM64 build ignore (now builds for all platforms).
  • Added Windows installer scripts to release assets.
  • Reorganized release configuration.

Policy and enforcement

• policy/enforcer.go: Made plugin policy directory path platform-aware using GetPluginPolicyDir().

SSH certificate improvements

• sshcert/sshcert.go: Improved error messages when parsing SSH authorized keys, including actual type information and truncated key data for easier debugging.

GitHub Actions

• gha-windows.yml: Integration test workflow for Windows Server 2022. Tests the full SSH flow: install OpenSSH Server → build opkssh → configure AuthorizedKeysCommand → authenticate with GitHub OIDC → SSH login.
• gha-windows-2025.yml: Same integration test for Windows Server 2025.

Related

• Part 3 of 3 from Adds support to OpenSSH Servers on Windows. #389
• Fix Support for Windows OpenSSH Server? #370

[fdcastel]

Rebased onto the latest main.

[EthanHeilman]

@fdcastel Let me know when this is ready to review. It looks like it has a bunch of merge conflicts.

[fdcastel]

@fdcastel Let me know when this is ready to review. It looks like it has a bunch of merge conflicts.

Sure! I was just waiting for #479 to land.

I’ll take care of this one tonight 🙌🏻

[fdcastel]

@EthanHeilman Everything set and ready to go!

As always, feel free to request any adjustments you wish.

Tests are passing on Windows Server 2025 and 2022! 🚀

[EthanHeilman]

Given the statement

Removed Windows ARM64 build ignore (now builds for all platforms).

We probably want to add Windows ARM64 to the integration tests

[fdcastel]

add Windows ARM64 to the integration tests

Working on it!

[fdcastel]

Added initial support for tests on Windows 11 / ARM64.

Changes:

1. ci.yml: Two new jobs using windows-11-arm runner:

   • build-windows-arm64: native ARM64 build + binary verification
   • test-windows-arm64: unit tests on ARM64

2. gha-windows-arm64.yml: New end-to-end integration test workflow (OpenSSH Server install, opkssh setup, SSH login via GitHub OIDC) on Windows 11 ARM64

P.S.: The first run of the ARM64 integration test timed out (10 min wasn't enough since Go isn't pre-installed on windows-11-arm). Fixed by switching from manual actions/cache to actions/setup-go and increasing the timeout to 15 minutes.

[EthanHeilman]

P.S.: The first run of the ARM64 integration test timed out (10 min wasn't enough since Go isn't pre-installed on windows-11-arm). Fixed by switching from manual actions/cache to actions/setup-go and increasing the timeout to 15 minutes.

Interesting that the windows arm test is now faster than all the other integration tests.

Edit: Ok, I see what you did. I meant add windows to the integration tests here

opkssh/.github/workflows/ci.yml

Lines 92 to 105 in 91ec2f7

	test:
	needs: build
	name: 'Integration Tests'
	runs-on: ${{ matrix.runs_on }}
	timeout-minutes: 8
	strategy:
	matrix:
	runs_on: [ubuntu-24.04, ubuntu-24.04-arm]
	os: [ubuntu, centos, arch, opensuse]
	exclude:
	- runs_on: ubuntu-24.04-arm
	os: arch
	env:
	OS_TYPE: ${{ matrix.os }}

[EthanHeilman]

Thanks for all your work on this. It is almost ready.

Make sure to document that we support windows on the server support matrix in the readme
https://github.com/openpubkey/opkssh?tab=readme-ov-file#server-support

[fdcastel]

• Rebased onto latest main.
• Updated README.md.

[EthanHeilman]

I'll give this another review once all the outstanding items are resolved. It is looking pretty close. Then I'll do a manual test on windows if I don't run into any errors, I'll merge it.

Any reason not to merge when i get to that point?

[fdcastel]

Any reason not to merge when i get to that point?

Nope, all good on my side! 👍🏻

That said, I’d love to test a rebased version of this PR on top of the other PRs I submitted yesterday -- just to do one last manual integration check.

[EthanHeilman]

You want to do those PRs first?

[fdcastel]

You want to do those PRs first?

I just had that brilliant realization… right after I started submitting them 😅

You know... sleep deprivation + questionable decision-making.

Jokes apart... Feel free to go with whatever flow works best for you. I’m happy to rebase anything if needed 👍

[EthanHeilman]

I'll merge them first. Reviewing and testing this PR is going to take a while.

[fdcastel]

Please ring me here when you'd like a rebase onto the latest main.

[fdcastel]

System PATH is now correctly configured on both Server 2022 and 2025.

The WM_SETTINGCHANGE approach was ineffective: it didn’t refresh the PATH in the current session. I'm removing it.

Both Server 2022 and Server 2025 working (here 😉).

[fdcastel]

That  might be a BOM-related issue -- I’ll dig into that further.

Found it! Fixing...

[fdcastel]

@EthanHeilman That  in the error message is the UTF-8 BOM (Byte Order Mark, bytes EF BB BF) being displayed in a Latin-1/CP1252 context.

Root Cause

The providers file at C:\ProgramData\opk\providers is being created with a UTF-8 BOM because the PowerShell installer uses Set-Content -Encoding UTF8, and Windows PowerShell 5.1 (the default shell on Windows Server 2022 and 2025) always writes a UTF-8 BOM with -Encoding UTF8 — there is no way to disable it. Only PowerShell 7+ has -Encoding utf8NoBOM.

Here's how the BOM causes the parse error:

1. NewTable() in policy/files/table.go converts the file bytes to a Go string. The BOM bytes EF BB BF become the Unicode character U+FEFF.
2. The first row becomes "\ufeff# Issuer Client-ID expiration-policy".
3. CleanRow() strips the comment with strings.Split(row, "#")[0], leaving just "\ufeff" (the BOM character alone).
4. Go's strings.TrimSpace() does not consider U+FEFF as whitespace, so the non-empty string proceeds to parsing.
5. shellquote.Split produces a single-element slice ["\ufeff"], and len(row) != 3 triggers the "wrong number of arguments (expected=3, got=1)" error.

The actual provider entries on lines 2+ parse fine — the BOM only affects the first line.

Fixes Applied

Fix 1 — Go code (defensive, handles any BOM source): Strip the UTF-8 BOM at the start of NewTable() in policy/files/table.go:

// Strip UTF-8 BOM if present
if len(content) >= 3 && content[0] == 0xEF && content[1] == 0xBB && content[2] == 0xBF {
    content = content[3:]
}

This is important for robustness since users may also edit config files with Windows Notepad, which can re-add a BOM on save.

Fix 2 — PowerShell installer (prevents the BOM from being written): Replaced Set-Content -Encoding UTF8 with a .NET call that writes UTF-8 without BOM in Install-OpksshServer.ps1:

# Before:
Set-Content -Path $providersPath -Value $providersContent -NoNewline -Encoding UTF8

# After:
[System.IO.File]::WriteAllText($providersPath, $providersContent, [System.Text.UTF8Encoding]::new($false))

A test case for BOM-prefixed input was also added to table_test.go.

[EthanHeilman]

Got it working!

The auth_id policy file appears to be be case sensitive, but ssh converts Administrator@ to administrator@ but I had set the username in the auth_id to Administrator for some reason. Not sure if we want to fix this:

• Usenames in linux are case sensitive
• Usernames in windows are case insensitive

Defaulting to being case sensitive seems like the safest option. Let me know if you have a better idea

Recording.2026-03-30.092912.mp4

[Copilot]

Pull request overview

Copilot reviewed 29 out of 29 changed files in this pull request and generated 4 comments.

Comments suppressed due to low confidence (1)

main.go:583

• isOpenSSHVersion8Dot1OrGreater builds a version string like v9.5 and then compares it with v8.1.0 via semver.Compare. golang.org/x/mod/semver treats v9.5 as invalid (missing patch), so this comparison will likely always report "< v8.1.0" and emit warnings even on new OpenSSH versions. Normalize the extracted version to a full semver (e.g., append .0 for the patch or parse major.minor.patch when available) before calling semver.Compare.

	version := "v" + matches[1] // semver requires that version strings start with 'v'
	// OpenSSH doesn't use semantic versioning, but does use major.minor which after stripping the patch version can be compared using semver
	if semver.Compare(version, "v8.1.0") >= 0 {
		// if version is greater than or equal to v8.1.0

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[fdcastel]

Nice! I’ll take care of these tonight (in a few hours).

[fdcastel]

Defaulting to being case sensitive seems like the safest option. Let me know if you have a better idea

Agreed.

SUGGESTION: normalize the principal to lowercase at the entry points on Windows only, leaving the core engine untouched.

1. main.go: In the verify command handler, after userArg := args[0], add strings.ToLower(userArg) when runtime.GOOS == "windows" -- ensures the principal sent to CheckPolicy matches what Windows sshd sends
2. main.go: In the add command handler, same normalization for the principal argument — ensures opkssh add Administrator ... stores administrator
3. main.go: In the readhome command handler, same normalization

Considerations:

• Keep core engine (enforcer.go) case-sensitive -- changing it would break Linux where usernames are case-sensitive
• Normalize at OS-aware boundary (main.go) only -- minimal, safe, and platform-specific
• Use strings.ToLower() to store the canonical form, not runtime EqualFold comparison
• Deny list is already case-insensitive: The deny list uses strings.EqualFold for both principals and emails (enforcer.go). This is already correct for both platforms, but worth noting the existing asymmetry with the allow list for documentation.

@EthanHeilman! I can jump on this now, or open a new issue and tackle it after this PR is merged. Just let me know what you’d prefer.

[EthanHeilman]

SUGGESTION: normalize the principal to lowercase at the entry points on Windows only, leaving the core engine untouched.

I believe SSH already does this. I don't think this is worth solving as it opens a whole can of worms.

Deny list is already case-insensitive: The deny list uses strings.EqualFold for both principals and emails (enforcer.go). This is already correct for both platforms, but worth noting the existing asymmetry with the allow list for documentation.

That is tricky. Create a ticket to document this.

[fdcastel]

Deny list is already case-insensitive: The deny list uses strings.EqualFold for both principals and emails (enforcer.go). This is already correct for both platforms, but worth noting the existing asymmetry with the allow list for documentation.

That is tricky. Create a ticket to document this.

Done in #504 👍🏻

[EthanHeilman]

LGTM

[EthanHeilman]

LGTM

[EthanHeilman]

Tests breaking post merge

https://github.com/openpubkey/opkssh/actions/runs/23819884753/job/69429162670

[fdcastel]

Tests breaking post merge

https://github.com/openpubkey/opkssh/actions/runs/23819884753/job/69429162670

Working on it.

[fdcastel]

@EthanHeilman Found the problem. Fix in #506.