|
| 1 | +--- |
| 2 | +title: Host Guardian Service Troubleshooting Guide |
| 3 | +description: Resolves issues that occur when you configure HGS to use HTTPS for key protection and attestation in test environments. |
| 4 | +ms.date: 10/06/2025 |
| 5 | +author: kaushika-msft |
| 6 | +ms.author: kaushika |
| 7 | +manager: dcscontentpm |
| 8 | +audience: itpro |
| 9 | +ms.topic: troubleshooting |
| 10 | +ms.reviewer: kaushika |
| 11 | +ms.custom: |
| 12 | +- sap: virtualization and hyper-v\shielded virtual machines |
| 13 | +- pcy: Virtualization\shielded VMs |
| 14 | +appliesto: |
| 15 | + - <a href=https://learn.microsoft.com/windows/release-health/windows-server-release-info target=_blank>Supported versions of Windows Server</a> |
| 16 | +--- |
| 17 | + |
| 18 | +# Can't configure HGS for HTTPS key protection and attestation |
| 19 | + |
| 20 | +## Summary |
| 21 | + |
| 22 | +This article helps you to handle issues that occur when you configure the Host Guardian Service (HGS) to use HTTPS for key protection and attestation in test environments. By following these steps and guidelines, you can resolve configuration issues that affect the HGS, and ensure secure communication for your VMs. |
| 23 | + |
| 24 | +## Symptoms |
| 25 | + |
| 26 | +The following symptoms occur when you try to enable HTTPS on the HGS: |
| 27 | + |
| 28 | +- Attestation and key unwrap operations for VMs fail. |
| 29 | +- TLS (Transport Layer Security) and certificate trust errors appear in browsers and clients. |
| 30 | +- The certificate’s Subject Alternative Name (SAN) includes only the DNS HGS service name and not individual node hostnames. |
| 31 | +- You receive the following error message: |
| 32 | + |
| 33 | +> TransientError Host Unreachable |
| 34 | +
|
| 35 | +When this issue occurs, the following conditions apply: |
| 36 | + |
| 37 | +- Failures occur during attestation and key unwrap processes over HTTPS. |
| 38 | +- The configuration functions correctly when HTTP is used instead of HTTPS. |
| 39 | +- Network trace and Test-NetConnection confirm communication on required ports. |
| 40 | +- The certificate’s Subject Alternative Name (SAN) includes only the DNS HGS service name and not individual node hostnames. |
| 41 | +- The issue isn't reproducible in other test environments, such as the support engineer’s lab environment. |
| 42 | + |
| 43 | +## Cause |
| 44 | + |
| 45 | +The root cause of the problem is related to the HTTPS configuration and certificate requirements for HGS: |
| 46 | + |
| 47 | +- Nonmandatory HTTPS: HTTPS is optional for HGS. HTTP communications are already encrypted at the message level as part of the Key Protection Service (KPS) protocol. |
| 48 | +- Certificate issues: The certificate that's used for HTTPS doesn't meet the documented requirements, such as missing SAN entries for all HGS node hostnames. |
| 49 | +- Environment-specific factors: The issue might be caused by configuration or compatibility challenges that are specific to the environment, or from deprecated features in the Windows Server version that's used. |
| 50 | +- Feature design: Development confirms that HGS over HTTP provides adequate encryption, and HTTPS isn't required for security. |
| 51 | + |
| 52 | +## Resolution |
| 53 | + |
| 54 | +To resolve this issue, follow these steps: |
| 55 | + |
| 56 | +1. Use HTTP for HGS communication: |
| 57 | + |
| 58 | +Based on recommendations from the product and development teams, you should continue to use HTTP for HGS. HTTP provides message-level encryption, ensuring data security. |
| 59 | + |
| 60 | +2. Validate encryption: |
| 61 | + |
| 62 | +Collect network traces to verify that HTTP payloads are encrypted and not exposed in plain text. |
| 63 | + |
| 64 | +3. Certificate reconfiguration (if HTTPS is required): |
| 65 | + |
| 66 | +If HTTPS must be used, make sure that certificates meet all documented requirements, including SAN entries for all HGS node hostnames. Consult the HGS documentation for guidance to issue certificates correctly. |
| 67 | + |
| 68 | +4. Use available tools for troubleshooting and validation: |
| 69 | + |
| 70 | +Use the following tools and commands to troubleshoot and verify the configuration: |
| 71 | + |
| 72 | +- Test-NetConnection to verify required port connectivity |
| 73 | +- PowerShell cmdlets such as Set-HgsServer for configuring HGS |
| 74 | +- Network tracing tools to verify encryption of HTTP payloads |
| 75 | +- Browser-based validation to verify HTTPS endpoint and certificate trust |
| 76 | + |
| 77 | +5. Plan for future deployments: |
| 78 | + |
| 79 | +- Review feature deprecation notices for HGS and shielded VMs in newer Windows Server versions. |
| 80 | +- Consider alternatives, such as Azure Confidential Computing, for future deployments. |
| 81 | + |
| 82 | +6. Review documentation and guidelines: |
| 83 | + |
| 84 | +- Share relevant public documentation and internal guidelines with your team to ensure proper configuration and understanding of HGS. |
| 85 | + |
| 86 | +## Data collection |
| 87 | + |
| 88 | +Before you contact Microsoft Support, you can gather the following information about your issue. |
| 89 | + |
| 90 | +- Network traces: Perform network tracing during key protection exchanges to verify encryption of communications. |
| 91 | +- PowerShell diagnostic outputs: Collect outputs from HGS servers and guarded hosts by using HGS-related PowerShell commands. |
| 92 | +- HTTP and HTTPS traffic logs: Analyze logs for TLS-related errors and communication issues. |
| 93 | +- Configuration details: Record details about the environment, such as certificate attributes, HGS node hostnames, and DNS configuration. |
| 94 | + |
| 95 | +## References |
| 96 | + |
| 97 | +- [Host Guardian Service overview](/windows-server/security/guarded-fabric-shielded-vm/guarded-fabric-and-shielded-vms) |
| 98 | +- [Configure HGS](/windows-server/security/guarded-fabric-shielded-vm/guarded-fabric-setting-up-the-host-guardian-service-hgs) |
| 99 | +- [Certificate requirements for HGS](/windows-server/security/guarded-fabric-shielded-vm/guarded-fabric-obtain-certs) |
| 100 | +- [How to configure HTTPS](/windows-server/security/guarded-fabric-shielded-vm/guarded-fabric-configure-hgs-https) |
| 101 | +- [Frequently Asked Question About HGS Certificates](/archive/blogs/datacentersecurity/frequently-asked-questions-about-hgs-certificates) |
| 102 | + [Azure Confidential Computing](/azure/confidential-computing/overview) |
0 commit comments