YubiHSM 2 Connector Unreachable on TCP Port 12345: Restore Network HSM Access
Overview
When YubiHSM 2 clients cannot reach a network yubihsm-connector on TCP port 12345, check four documented conditions in order: the client ConnectorURL, the connector service, its listen address (localhost:12345 by default) and the host firewall. Change only the one that failed, with a backup and rollback ready; key material is never touched.
Diagnose
Symptom
What responders observe.
Applications using libyubihsm’s HTTP backend, such as the KSP behind Microsoft Certificate Services or SQL Server Always Encrypted, or yubihsm-shell on a virtual machine, lose contact with the connector at http://<connector-host>:12345. Key operations fail. Scope: the TCP/IP path to a connector that previously worked.
Detection
Metrics, logs and confirmation commands.
-
Record every output. Steps 1 to 3 run on an affected client, steps 4 to 7 on the connector host.Read the client’s connector URL (Windows client, any account that can read HKLM; read-only):Get-ItemProperty -Path 'HKLM:\SOFTWARE\Yubico\YubiHSM' -Name ConnectorURL Get-ItemProperty -Path 'HKLM:\SOFTWARE\Wow6432Node\Yubico\YubiHSM' -Name ConnectorURLExpected: the same value in both (Yubico configures the 64-bit and 32-bit subkeys separately), such as http://192.168.100.252:12345. Naming only ConnectorURL keeps the stored AuthKeysetPassword off screen. Stop if either value is wrong: go to remediation C.
-
Test the TCP port (same client, standard user; read-only):Test-NetConnection -ComputerName <connector-host> -Port 12345Expected: TcpTestSucceeded : True and a RemoteAddress that is the connector host. If False, go to step 4. Under TCP (RFC 9293) a SYN to a port with no listener is answered with a reset, so a quick failure is consistent with no listener, while a time-out is consistent with a firewall dropping packets. Both are inferences; steps 4 to 7 confirm.Ask the connector for its status (same client; read-only). Yubico documents a GET request on /connector/status for connector information:Invoke-WebRequest -Uri 'http://<connector-host>:12345/connector/status' -UseBasicParsingExpected: StatusCode : 200; save the body. If steps 2 and 3 succeed, the network path is healthy: stop and escalate as an application or authentication fault.
-
Check the service (connector host, local administrator; read-only except the start below):Get-Service -DisplayName 'YubiHSM'Expected: the connector service, Status Running; note its Name. If nothing matches, take the service name from your installation records. If it is Stopped, this is the one state change in diagnosis: preview, then start it, and repeat step 2. Escalate if it stops again.Get-Service -Name <name> | Where-Object {$_.Status -eq "Stopped"} | Restart-Service -WhatIfRemove -WhatIf to run it. No rollback is needed: it returns the service to its intended state.
-
Check the listener (connector host, local administrator; read-only):Get-NetTCPConnection -LocalPort 12345 -State ListenExpected: a LocalAddress matching the address clients use. Only 127.0.0.1 or ::1 means the default localhost:12345: go to remediation A. Nothing listed while the service runs: escalate.
-
Query the connector locally (connector host; read-only), using the URL from Yubico’s quick start:Invoke-WebRequest -Uri 'http://127.0.0.1:12345/connector/status' -UseBasicParsingUse the bound address instead if it is not loopback. Expected: StatusCode : 200. A failure while the service runs points at the connector’s access to the device, which the YubiHSM 2 driver controls on Windows: escalate.Find inbound rules for the port (connector host, local administrator; read-only):Get-NetFirewallPortFilter | Where-Object -Property LocalPort -EQ 12345 | Get-NetFirewallRuleExpected: an enabled inbound Allow rule covering the clients; save the output as the baseline. Rules scoped to any port will not appear here, so check them before concluding. No covering rule: remediation B. A covering rule but step 2 still fails: the block is outside this host, so escalate to the network owner.
Root cause
Why the incident occurred.
-
Record every output.
-
Steps 1 to 3 run on an affected client, steps 4 to 7 on the connector host.Read the client’s connector URL (Windows client, any account that can read HKLM; read-only):Get-ItemProperty -Path 'HKLM:\SOFTWARE\Yubico\YubiHSM' -Name ConnectorURL Get-ItemProperty -Path 'HKLM:\SOFTWARE\Wow6432Node\Yubico\YubiHSM' -Name ConnectorURLExpected: the same value in both (Yubico configures the 64-bit and 32-bit subkeys separately), such as http://192.168.100.252:12345.
-
Naming only ConnectorURL keeps the stored AuthKeysetPassword off screen.
-
Stop if either value is wrong: go to remediation C.
-
Test the TCP port (same client, standard user; read-only):Test-NetConnection -ComputerName <connector-host> -Port 12345Expected: TcpTestSucceeded : True and a RemoteAddress that is the connector host.
-
If False, go to step 4.
-
Under TCP (RFC 9293) a SYN to a port with no listener is answered with a reset, so a quick failure is consistent with no listener, while a time-out is consistent with a firewall dropping packets.
-
Both are inferences; steps 4 to 7 confirm.Ask the connector for its status (same client; read-only).
-
Yubico documents a GET request on /connector/status for connector information:Invoke-WebRequest -Uri 'http://<connector-host>:12345/connector/status' -UseBasicParsingExpected: StatusCode : 200; save the body.
-
If steps 2 and 3 succeed, the network path is healthy: stop and escalate as an application or authentication fault.
-
Check the service (connector host, local administrator; read-only except the start below):Get-Service -DisplayName 'YubiHSM'Expected: the connector service, Status Running; note its Name.
-
If nothing matches, take the service name from your installation records.
-
If it is Stopped, this is the one state change in diagnosis: preview, then start it, and repeat step 2.
-
Escalate if it stops again.Get-Service -Name <name> | Where-Object {$_.Status -eq "Stopped"} | Restart-Service -WhatIfRemove -WhatIf to run it.
-
No rollback is needed: it returns the service to its intended state.
-
Check the listener (connector host, local administrator; read-only):Get-NetTCPConnection -LocalPort 12345 -State ListenExpected: a LocalAddress matching the address clients use.
-
Only 127.0.0.1 or ::1 means the default localhost:12345: go to remediation A.
-
Nothing listed while the service runs: escalate.
-
Query the connector locally (connector host; read-only), using the URL from Yubico’s quick start:Invoke-WebRequest -Uri 'http://127.0.0.1:12345/connector/status' -UseBasicParsingUse the bound address instead if it is not loopback.
-
Expected: StatusCode : 200.
-
A failure while the service runs points at the connector’s access to the device, which the YubiHSM 2 driver controls on Windows: escalate.Find inbound rules for the port (connector host, local administrator; read-only):Get-NetFirewallPortFilter | Where-Object -Property LocalPort -EQ 12345 | Get-NetFirewallRuleExpected: an enabled inbound Allow rule covering the clients; save the output as the baseline.
-
Rules scoped to any port will not appear here, so check them before concluding.
-
No covering rule: remediation B.
-
A covering rule but step 2 still fails: the block is outside this host, so escalate to the network owner.
Contain and prevent
Blast radius
What else this can affect.
Prevention
Controls and guardrails that stop it recurring.
-
Document the listen address and every client’s ConnectorURL.
-
Change them together.Keep the rule limited to known clients.
-
The connector defaults to HTTP.
-
Yubico supports HTTPS with a certificate and key, or TLS through a reverse proxy such as nginx.
-
Run the connector service under a dedicated low-privilege account, as Yubico recommends.Poll /connector/status from a client network.Rehearse remediations in a lab and confirm the connector version before production changes.After any change, re-run validation from every client.
-
If one fails, roll back that single change first.
Fix
Pre-flight checks
Check these before you change anything.
-
Local administrator rights on the connector host and read access to HKLM on clients.
-
An approved change window, and a non-production lab where remediations have been rehearsed.
-
The connector version and its configuration file location confirmed before any change.
Commands
Get-ItemProperty -Path 'HKLM:\SOFTWARE\Yubico\YubiHSM' -Name ConnectorURL
Test-NetConnection -ComputerName <connector-host> -Port 12345
Invoke-WebRequest -Uri 'http://<connector-host>:12345/connector/status' -UseBasicParsing
Get-Service -DisplayName '*YubiHSM*'
Get-NetTCPConnection -LocalPort 12345 -State Listen
Invoke-WebRequest -Uri 'http://127.0.0.1:12345/connector/status' -UseBasicParsing
Get-NetFirewallPortFilter | Where-Object -Property LocalPort -EQ 12345 | Get-NetFirewallRule
Copy-Item -Path 'C:\ProgramData\YubiHSM\yubihsmconnector.yaml' -Destination 'C:\ProgramData\YubiHSM\yubihsmconnector.yaml.bak'
Restart-Service -Name <connector-service-name>
New-NetFirewallRule -DisplayName 'YubiHSM Connector TCP 12345' -Direction Inbound -Protocol TCP -LocalPort 12345 -RemoteAddress <client-IP-1>,<client-IP-2> -Action Allow
Verify and recover
Verification
Evidence required before you close the incident.
-
Test-NetConnection -ComputerName <connector-host> -Port 12345 from every affected client — TcpTestSucceeded : True — All clients succeed. Invoke-WebRequest to http://<connector-host>:12345/connector/status — StatusCode : 200 — Status returned from every client. Get-NetTCPConnection -LocalPort 12345 -State Listen on the connector host — Listener only on the intended address — No unintended listener.
-
Run one real KSP or yubihsm-shell operation — connect and session open complete — Operation succeeds.
Commands in these steps
Invoke-WebRequest to http://<connector-host>:12345/connector/status — StatusCode : 200 — Status returned from every clientGet-NetTCPConnection -LocalPort 12345 -State Listen on the connector host — Listener only on the intended address — No unintended listener
Rollback
The safe way back.
-
Remediation A: copy yubihsmconnector.yaml.bak back over yubihsmconnector.yaml with Copy-Item -Force, restart the connector service, and confirm the loopback listener returns.
-
Remediation B: Remove-NetFirewallRule -DisplayName 'YubiHSM Connector TCP 12345'.
-
Remediation C: set ConnectorURL in both KSP registry subkeys back to the value recorded in diagnosis step 1.
Escalate when
Conditions that need another owner.
-
The service stops again after a start, or runs with no listener on port 12345.Local /connector/status fails while the service runs, which points at USB, driver or device access.TCP and status succeed but KSP operations fail: not a network fault.enable-host-whitelist is on, or another team owns the blocking firewall.Service is not restored within your agreed recovery target.
-
Network team HSM owner Application owner.
Fixed? Get the next one before it hits you: The KBY Brief
Practical fixes for the systems you run, by email about twice a week. Unsubscribe at any time.
About this page
Credited to
Dates
Published
Last updated
Corrections
No corrections are listed for this page. Some review sweeps corrected pages without naming each one; those are in the corrections log.
Was this useful?
Reports go to the site owner and are used to correct pages. Corrections are listed at /corrections.
Sources
Based on the vendor sources listed below. Check each step against your environment before acting.
First published 15 November 2026 · Last updated 16 November 2026
YubiHSM 2 Connector
Cited for: Supports the documented platform behaviour, diagnosis or recovery controls used by this Runbook.
Set up KSP on Windows
Cited for: Supports the documented platform behaviour, diagnosis or recovery controls used by this Runbook.
Libyubihsm Backend
Cited for: Supports the documented platform behaviour, diagnosis or recovery controls used by this Runbook.
YubiHSM 2 Quick Start
Cited for: Supports the documented platform behaviour, diagnosis or recovery controls used by this Runbook.
YubiHSM 2 Shell
Cited for: Supports the documented platform behaviour, diagnosis or recovery controls used by this Runbook.
Test-NetConnection
Cited for: Supports the documented platform behaviour, diagnosis or recovery controls used by this Runbook.
Get-NetTCPConnection
Cited for: Supports the documented platform behaviour, diagnosis or recovery controls used by this Runbook.
New-NetFirewallRule
Cited for: Supports the documented platform behaviour, diagnosis or recovery controls used by this Runbook.
Restart-Service
Cited for: Supports the documented platform behaviour, diagnosis or recovery controls used by this Runbook.
RFC 9293: Transmission Control Protocol (TCP)
Cited for: Supports the documented platform behaviour, diagnosis or recovery controls used by this Runbook.
Incident Response Recommendations and Considerations for Cybersecurity Risk Management
Cited for: Supports the documented platform behaviour, diagnosis or recovery controls used by this Runbook.