Step-by-step: Quick reference guide to deploying guarded hosts

  • Article

My original blog post on the topic of deploying Shielded VMs without VMM included the instructions to deploy guarded hosts.  Based on feedback around keeping the blog posts short and scenario-focused, I split the content into 2. This blog serves as a quick reference to deploy guarded hosts.

Once again, I highly recommend you read through the deployment guide first to understand the building blocks that enable the shielded VM scenario. I assume you understand the terminology, as well as the difference between Admin-trusted and TPM-trusted attestation mode. They are all well explained in the deployment guide.

Prerequisites

At a minimum, you will need 2 machines running the TP5 release of the Windows Server 2016. One machine will be configured as a guarded host (a Hyper-V host that can run shielded VMs), and the other machine will be configured as a Host Guardian Service (HGS) Server.

If you are testing the TPM-trusted attestation mode, the Hyper-V guarded host must provide/support the following:

  • IOMMU and SLAT must be supported and enabled
  • TPM v2.0
  • UEFI 2.3.1 or later
  • Configured to boot using UEFI (not BIOS or “legacy” mode),
  • Secure Boot enabled

If you are testing Admin-trusted attestation, there will be no additional hardware requirements, other than being able to run Hyper-V in Windows Server 2016 TP5.

TPM-trusted attestation and Admin-trusted attestation configuration requirements are very different for each Hyper-V host. They will be illustrated individually in the sections below.

Role/feature installation on the guarded host

You must install the following on the guarded host:

  • Hyper-V (role)
  • Host Guardian Hyper-V Support (feature)

You may use Server Manager or run the following cmdlet to install the roles/features:

 Install-WindowsFeature Hyper-V, HostGuardian –IncludeManagementTools -Restart

1. Deploy and configure guarded hosts using TPM-trusted attestation

The process involves the following steps which generate files on the guarded host. The files are later copied to the HGS server to complete the configuration.

  1. Retrieve the TPM identifier: this is used to register the specific host with the HGS server.
  2. Create code integrity (CI) policy: this is used to ensure the software running on the host is trusted
  3. Capture the TPM baseline: this is used to measures the pre-OS UEFI firmware loaded on the host, to ensure only those are trusted and authorized can be loaded on each guarded host
  4. Configure the Hyper-V guarded host’s HGS server

Note: if you are testing with more than one Hyper-V host, you will get the TPM identifier from each host.  If the hardware and software configuration of the second host is the same, you can use the same CI policy and TPM baseline measurement as long.

Retrieve TPM identifier

Run the following cmdlet to get the TPM identifier on the host:

 (Get-PlatformIdentifier –Name 'HostName').InnerXml | Out-file HostName.xml

Create and apply CI policy

It is recommended that you first create the CI policy in audit mode to see if it’s missing anything, then enforce the policy when using the system to host production workloads. For more information about generating CI policies and the enforcement mode, consult the Device Guard Deployment Guide.
Run the following cmdlets to create the CI policy on the host:

 New-CIPolicy –Level FilePublisher –Fallback Hash –FilePath 'CodeIntegrity.xml'

Next, we convert the XML file to the format used by HGS:

 ConvertFrom-CIPolicy –XmlFilePath 'CodeIntegrity.xml' –BinaryFilePath 'CodeIntegrity.p7b'

You can create one CI policy for all the hosts as long as they have the same hardware and software configuration, but you must apply the CI policy on each host. To do so, copy the binary CI policy file (CodeIntegrity.p7b) to the following location on each host (the name must match exactly):

 C:\Windows\System32\CodeIntegrity\SIPolicy.p7b

Restart the host to activate the CI policy in audit mode.

Capture TPM baseline

Run the following cmdlet to capture the TPM baseline:

 Get-HgsAttestationBaselinePolicy –Path 'c:\host.tcglog'

Configure the host to be managed by a specific HGS server

Run the following cmdlet to configure the host to attest against an HGS server:

 Set-HgsClientConfiguration -AttestationServerURL 'https://<HGS Server FQDN>/Attestation' -KeyProtectionServerURL 'https://<HGS Server FQDN>/KeyProtection'

Note: you can get the FQDN and entire URL values by running Get-HGSServer on the HGS server.
The output of the cmdlet will show the host is not guarded, this is expected as HGS server has not yet been configured to trust this host.

TP5 specific step

If you are running Windows Server Technical Preview 5 on your guarded host(s), you must download and run this script from each host in order to configure certain security settings necessary for TPM attestation. Restart the host after running the script to apply the changes.

Configuration on the HGS server

Configure the following on the HGS server to complete the host deployment:

  1. Add each guarded host on the HGS server
  2. Add one CI policy for each set of hosts that use the same hardware and software configuration
  3. Add one TPM baseline policy for each set of hosts that use the same hardware and software configuration

The following configuration steps requires the files you created in the previous section (e.g. host.xml, CodeIntegrity.p7b and host.tcglog). For simplicity’s sake, copy them manually to the HGS server or to a file share that both the Hyper-V host and the HGS server can access. Once you’ve copied all 3 files, proceed with the following commands.

Adding a guarded host

Run the following cmdlet to add a guarded host:

 Add-HgsAttestationTpmHost –Path 'c:\host.xml' –Name 'Host1' -Force

Note: the file specified here was created in the section Retrieving TPM identifier.

Add CI policy

Run the following cmdlet to add a CI policy:

 Add-HgsAttestationCIPolicy -Path 'c:\CodeIntegrity.p7b' -Name 'HostCIPolicy'

Note: the file specified here was created in the section Creating and apply CI policy.

Add TPM baseline policy

Run the following cmdlet to add a TPM baseline policy:

 Add-HgsAttestationTpmPolicy –Path 'c:\host.tcglog' –Name 'HostTPMPolicy'

Note: the file specified here was created in the section Capture TPM baseline.

Verification

Run the following cmdlet on each host to validate attestation status:

 Get-HgsClientConfiguration

Check the output, to ensure the AttestationStatus equals passed and IsHostGuarded is True. Now the hosts are guarded and ready to deploy the shielded VMs.

If the AttestationStatus is failed, check the AttestationSubstatus for details, and consult the deployment guide to fix the errors. You can also use the HGS Diagnostic cmdlets to check your topology setup, for details running the HGSDiag tool, see the diag blog post.

2. Deploy and configure guarded hosts using Admin-trusted attestation

With admin-trusted attestation, hosts will leverage Active Directory to provide proof of identity. You will create a new GLOBAL security group in the fabric domain and add the trusted hosts to this security group.
On the HGS server, you will create a guarded host group using this cmdlet:

 Add-HgsAttestationHostGroup -Name 'GuardedHostGroup' –Identitifier '<SID>'

To obtain the SID, use the following PowerShell cmdlet against the fabric AD and copy the SID as formatted in the output (don’t forget to wrap it in quotes).

 Get-ADGroup 'GuardedHost'

To verify that the guarded host group was successfully added, run

 Get-HgsAttestationHostGroup

The friendly name of your group should appear.

On the guarded host, run the following cmdlet to complete the HGS configuration:

 Set-HgsClientConfiguration -AttestationServerURL 'https://<HGS Server FQDN>/Attestation' -KeyProtectionServerURL 'https://<HGS Server FQDN>/KeyProtection'

Note: you can get the URL values by running the following cmdlet on the HGS server:

 Get-HGSServer

The output of the cmdlet shows the attestation status. Check it to ensure the AttestationStatus is passed and IsHostGuarded is True. Now the hosts are guarded and ready to deploy the shielded VMs.

If the AttestationStatus is failed, check the AttestationSubstatus for details, and consult the deployment guide to fix the errors. You can also use the HGS Diagnostic cmdlets to check your topology setup, for details running the HGSDiag tool, see the diag blog post.

Conclusion

Now you have the guarded hosts ready and can proceed to deploy the shielded VMs.
As always, we value your comments and feedback, and you can share with us, or submit and vote on request through the User Voice website.