Share via

Step by Step - Configuring the Host Guardian Service in Windows Server 2016

  • Article

For the most up-to-date installation instructions, check out our official documentation at https://aka.ms/ShieldedVMs

[This post is authored by Amitabh Tamhane, Senior Program Manager and Ryan Puffer, Program Manager for the Windows Server Product Team]

The “Host Guardian Service” (HGS) is a new server role introduced in Windows Server 2016. HGS provides Attestation and Key Protection services that enable Hyper-V to run Shielded virtual machines. A Hyper-V host is known as a “guarded host” once the Attestation service affirmatively validates its identity & configuration. Once affirmatively attested, the Key Protection service provides the transport key (TK) needed to unlock & run Shielded VMs.

Shielded VMs protect VM data and state by supporting a virtual TPM (vTPM) device which allows BitLocker encryption of the VM’s disks. This vTPM device is encrypted with a transport key. HGS is a security critical component that protects the TK. In addition, there are significant security enhancements made across multiple components (including Hyper-V) that raise the security assurance levels for Shielded VMs. For more details on terms like Shielded VMs, guarded fabric, guarded hosts, etc. click here.

The purpose of this blog is to walk-through the default configuration steps for the Host Guardian Service role and the corresponding Hyper-V support components. For advanced scenarios and more information on the guarded fabric topology, consult the guarded fabric deployment guide.

1. Installing Host Guardian Service (HGS) Role

On a machine running Windows Server 2016, install the Host Guardian Service role using Server Manager or Windows PowerShell. As a security best practice, it is recommended that you use a dedicated physical machine running the Server Core installation option for HGS.
Using Server Manager: 01

Using PowerShell: 02

2. Configuring HGS Server

After installing the HGS role, you still need to configure the role to make it a fully functional HGS server. All management of HGS is done through Windows PowerShell.

Note: This blog assumes the default installation mode for HGS where a new Active Directory forest will be created specifically for the Host Guardian Service. If you wish to instead join HGS to an existing, highly trusted Active Directory domain, please consult the guarded fabric deployment guide for the extra configuration steps you must take.

2.1. Install-HgsServer

The first step is set up the dedicated Active Directory forest for the HGS servers. Each node in the HGS cluster is a domain controller for this private domain. Ensure the HGS server is not already joined to a domain before running this command.

03

After the machine restarts, it will be the primary domain controller for the newly created domain. Log into the server with your administrator account to continue the HGS setup process.

2.2. Initialize-HgsServer

With the domain set up, it is now time to configure the HGS cluster and web services for Key Protection and Attestation. You will need 2 certificates (1 for signing, 1 for encryption) in order to complete this step. 04

“HgsServiceName” will be used to register the cluster service name with the local DNS server. In the above example, the service name is “HGS”, so the FQDN of the service will be “HGS.DomainName.com” (refer to the domain name specified in the Install-HgsServer).

The “TrustTpm” parameter specifies the Attestation service operation mode. For TPM-trusted fabrics, use “-TrustTpm”. If your host machines do not meet the hardware requirements for TPM attestation, you can configure HGS to use AD attestation with the “-TrustActiveDirectory” parameter.

The last 4 parameters are for specifying the signing and encryption certificates, where the certificates are provided as references to password-protected PFX files that contain the public and private keys of each certificate. These certificates are used by the Key Protection Service in HGS to decrypt keys of shielded VMs. Owners of shielded VMs use the public keys to authorize a fabric to run their VMs.

If you are setting up HGS in your test lab, you can use self-signed certificates to get started quickly. To generate self-signed certificates and export them to PFX files, use the New-SelfSignedCertificate and Export-PfxCertificate cmdlets.

When using HSM backed certificates or non-exportable certificates from your PKI, you will specify the thumbprint of the certificate instead of a PFX file and password when running Initialize-HgsServer. The guarded fabric deployment guide explains the extra steps you need to take when using PKI-issued or HSM-backed certificates.

2.3. Validate your configuration

Once the primary HGS Server is configured, you can run the HGS diagnostics to ensure everything is set up correctly. In PowerShell, run the following command to check if there are any additional steps you need to take. HGS01

3. Authorizing guarded hosts

Before a Hyper-V host can run shielded VMs, HGS must be configured with attestation policies which are used to determine if the host is “healthy” and allowed to request keys for shielded VMs.

3.1. TPM-trusted attestation

For TPM-trusted attestation, a guarded host’s TPM 2.0’s Endorsement Key (EK) needs to be retrieved and added to the list of authorized hosts in HGS.

On each host, use the Get-PlatformIdentifier cmdlet to generate an XML file containing the EKpub and EKcert. 05

Copy this file to your HGS server and use the Add-HgsAttestationTpmHost cmdlet to authorize the guarded host with the attestation service: 06

3.2 AD-trusted attestation

For Admin-trusted attestation, the guarded host is expected to be part of an Active Directory security group. Use the Add-HgsAttestationHostGroup to authorize the Active Directory group’s SID with the Attestation service: 07

Note: For AD-trusted attestation, you also need to establish one-way trust between the fabric Active Directory domain and the HGS domain. Consult the deployment guide for instructions on how to set up this trust.

4. Configuring Policies (TPM-trusted attestation only)

For TPM-trusted attestation, the guarded host’s software integrity is also verified. You need to configure baseline policies with the attestation service to establish one or more authorized (known good) host configurations.

Note: For AD-trusted attestation, the guarded host’s configuration is not verified. Hence, the steps below are not required for AD-trusted attestation.

4.1. Add-HgsAttestationCIPolicy

On a reference host (sometimes called a golden image) that is completely configured with all software agents and features installed, run the New-CIPolicy cmdlet to generate a code integrity policy. This policy will be applied to every machine with the same configuration, and is used to prevent unauthorized software from running on the host. You will need to create a CI policy once for each unique hardware/software configuration in your datacenter. Consult the deployment guide for detailed instructions on the CI policy cmdlets.

Once generated, you’ll have a code integrity policy stored in a binary file with a .p7b extension. Copy this file to your HGS server and add it to the attestation service: 08

4.2. Get-HgsAttestationBaselinePolicy

Next, for each unique hardware configuration in your datacenter you need to collect a TPM baseline policy. This file will contain information about the UEFI boot sequence up to the point where control of the system is handed off to the Windows boot loader. It is validated by HGS to ensure the system did not try to load unauthorized code such as a rootkit before Windows was loaded.

To capture a TPM baseline policy, run the following command on a reference host: 09

Copy the file to your HGS server and register it with the attestation service:

10

5. Configure HGS Client

The final step is to configure each guarded host to attest with and request keys from your HGS servers. You can find the two URLs to use here by running Get-HgsServer on the HGS server. Run the following command on each guarded host: 11

This command will trigger an attestation attempt with the server and show you its result. If “IsHostGuarded” is not true, check the attestation status and substatus for indications as to why your host did not pass attestation with HGS.

6. Conclusion

Now that the HGS attestation service has been configured with information about the trusted hosts and their trusted configurations in your datacenter, you are ready to create your first shielded VM. Check out this blog post or the deployment guide for information about creating a shielded VM.

Comments

  • Anonymous
    October 10, 2016
    Hi, Very good guidance and explanation.But for your scenario, are the host is in the same domain forest or different forest? Thanks
    • Anonymous
      April 04, 2017
      Hi Azuki,Sorry we missed this comment! If you're still wondering, the Hyper-V hosts should be in a different forest than HGS. This is to ensure the separation of admin duties requirement. If HGS were in the same forest as the Hyper-V hosts and admins, whom this solution is designed to protect against, it would be possible for a fabric admin to gain control over HGS and change the attestation policies. This could end up allowing bad CI policies that permit malware or other attacks to run on the Hyper-V hosts.Ryan
  • Anonymous
    December 05, 2016
    Hi,thanks for the good explanation. Is the Setup possible for testing with nested Hyper-V?Thanks
    • Anonymous
      January 30, 2017
      Yes, you can use nested HYPER-V for testing. With nested virtualization, there won't be DMA protection, but good for feature evaluation purpose.
  • Anonymous
    April 04, 2017
    Thanks for this guide, its very helpful.Just i side note, when i get to 2.3. Validate your configuration, the validation fails due to lack of Code Integrity Policies and missing hosts.
  • Anonymous
    April 04, 2017
    Thanks for the great guide.Regarding step 3.2 AD-trusted attestation, i get an error due to lack of hosts and code integrity policies.And was just wondering if you have any suggestions regarding the policy i should apply to the HGS host.
    • Anonymous
      April 04, 2017
      sry i meant 2.3. Validate your configuration
      • Anonymous
        April 04, 2017
        Hi Kent,Our screenshot is a bit ahead of itself -- you should see warnings about not having any policies registered at step 2.3. This is just telling you that while HGS is ready for use, it isn't configured to let any Hyper-V hosts attest successfully. Step 3 covers all the pieces needed to register those hosts with HGS. If you re-run "Get-HgsTrace" afterwards, you should see it pass without any warnings.If you encounter further issues, please do not hesitate to contact us at shieldedvmfeedback [at] microsoft [dot] com.Ryan
  • Anonymous
    April 16, 2017
    Does the HGS server have to join the domain?It was not very clear, you need to join the HGS server, or in the trust already entered it.
  • Anonymous
    April 16, 2017
    TPM 2.0 chip required for testing?
    • Anonymous
      April 17, 2017
      For Guarded host, if you are using TPM-trusted attestation, the host server must have TPM2.0.You can also use Admin-trusted attestation, host server doesn't need TPM at all. This page explains the difference between AD-trusted vs TPM-trusted attestation:https://technet.microsoft.com/en-us/windows-server-docs/security/guarded-fabric-shielded-vm/guarded-fabric-and-shielded-vms