Skip to main content

YubiHSM 2 Connector Unreachable on TCP Port 12345: Restore Network HSM Access

High severity Target recovery 30mTCP/IP

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.

Markdown, one checkbox per step, for pasting into a ticket.

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.

  1. 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.

  2. 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.

  3. 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.

  4. 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.

  5. 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.

  1. Record every output.

  2. 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.

  3. Naming only ConnectorURL keeps the stored AuthKeysetPassword off screen.

  4. Stop if either value is wrong: go to remediation C.

  5. 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.

  6. If False, go to step 4.

  7. 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.

  8. Both are inferences; steps 4 to 7 confirm.Ask the connector for its status (same client; read-only).

  9. 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.

  10. If steps 2 and 3 succeed, the network path is healthy: stop and escalate as an application or authentication fault.

  11. 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.

  12. If nothing matches, take the service name from your installation records.

  13. If it is Stopped, this is the one state change in diagnosis: preview, then start it, and repeat step 2.

  14. Escalate if it stops again.Get-Service -Name <name> | Where-Object {$_.Status -eq "Stopped"} | Restart-Service -WhatIfRemove -WhatIf to run it.

  15. No rollback is needed: it returns the service to its intended state.

  16. Check the listener (connector host, local administrator; read-only):Get-NetTCPConnection -LocalPort 12345 -State ListenExpected: a LocalAddress matching the address clients use.

  17. Only 127.0.0.1 or ::1 means the default localhost:12345: go to remediation A.

  18. Nothing listed while the service runs: escalate.

  19. 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.

  20. Expected: StatusCode : 200.

  21. 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.

  22. Rules scoped to any port will not appear here, so check them before concluding.

  23. No covering rule: remediation B.

  24. 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.

  1. Local administrator rights on the connector host and read access to HKLM on clients.

  2. An approved change window, and a non-production lab where remediations have been rehearsed.

  3. 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.

  1. 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.

  2. 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 client
  • Get-NetTCPConnection -LocalPort 12345 -State Listen on the connector host — Listener only on the intended address — No unintended listener

Rollback

The safe way back.

  1. Remediation A: copy yubihsmconnector.yaml.bak back over yubihsmconnector.yaml with Copy-Item -Force, restart the connector service, and confirm the loopback listener returns.

  2. Remediation B: Remove-NetFirewallRule -DisplayName 'YubiHSM Connector TCP 12345'.

  3. 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.

The KBY Brief

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

Publisher: Yubicodocs.yubico.com

YubiHSM 2 Connector

Cited for: Supports the documented platform behaviour, diagnosis or recovery controls used by this Runbook.

Publisher: Yubicodocs.yubico.com

Set up KSP on Windows

Cited for: Supports the documented platform behaviour, diagnosis or recovery controls used by this Runbook.

Publisher: Yubicodocs.yubico.com

Libyubihsm Backend

Cited for: Supports the documented platform behaviour, diagnosis or recovery controls used by this Runbook.

Publisher: Yubicodocs.yubico.com

YubiHSM 2 Quick Start

Cited for: Supports the documented platform behaviour, diagnosis or recovery controls used by this Runbook.

Publisher: Yubicodocs.yubico.com

YubiHSM 2 Shell

Cited for: Supports the documented platform behaviour, diagnosis or recovery controls used by this Runbook.

Publisher: Microsoft Learnlearn.microsoft.com

Test-NetConnection

Cited for: Supports the documented platform behaviour, diagnosis or recovery controls used by this Runbook.

Publisher: Microsoft Learnlearn.microsoft.com

Get-NetTCPConnection

Cited for: Supports the documented platform behaviour, diagnosis or recovery controls used by this Runbook.

Publisher: Microsoft Learnlearn.microsoft.com

New-NetFirewallRule

Cited for: Supports the documented platform behaviour, diagnosis or recovery controls used by this Runbook.

Publisher: Microsoft Learnlearn.microsoft.com

Restart-Service

Cited for: Supports the documented platform behaviour, diagnosis or recovery controls used by this Runbook.

Publisher: IETF RFC Editorrfc-editor.org

RFC 9293: Transmission Control Protocol (TCP)

Cited for: Supports the documented platform behaviour, diagnosis or recovery controls used by this Runbook.

Publisher: NISTcsrc.nist.gov

Incident Response Recommendations and Considerations for Cybersecurity Risk Management

Cited for: Supports the documented platform behaviour, diagnosis or recovery controls used by this Runbook.

Share
YubiHSM 2 Connector Unreachable on TCP Port 12345