Summary
To help customers identify orphaned Windows Hello for Business (WHfB) keys affected by a TPM vulnerability, Microsoft has published a PowerShell module that can be run by administrators. This article explains how to address the issue described in ADV190026 | “Microsoft Guidance for cleaning up orphaned keys generated on vulnerable TPMs and used for Windows Hello for Business.”
Important Note Before using WHfBTools to remove orphaned keys, the guidance in ADV170012 should be followed to update the firmware of any vulnerable TPMs. If this guidance is not followed, any new WHfB keys generated on a device with firmware that has not been updated will still be affected by CVE-2017-15361 (ROCA).
How to install the WHfBTools PowerShell Module
Install the module by running the following commands:
|
Installing WHfBTools PowerShell module |
|
Install via PowerShell PS> Install-Module WHfBTools PS> # Save the current execution policy so it can be reset later PS> $SaveExecutionPolicy = Get-ExecutionPolicy PS> Set-ExecutionPolicy RemoteSigned -Scope Currentuser PS> Import-Module WHfBTools Or Install using a download from PowerShell Gallery
Start PowerShell, copy and run the following commands: PS> # Save the current execution policy so it can be reset later PS> $SaveExecutionPolicy = Get-ExecutionPolicy PS> Set-ExecutionPolicy RemoteSigned -Scope Currentuser PS> CD C:\ADV190026\WHfBTools PS> Import-Module .\WHfBTools.psd1 |
Install dependencies for using the module:
|
Installing dependencies for using the WHfBTools module |
|
If you are querying Azure Active Directory for orphaned keys, install the MSAL.PS PowerShell module Install via PowerShell PS> Install-Module -Name MSAL.PS -RequiredVersion 4.5.1.1 PS> Import-Module MSAL.PS Or install using a download from PowerShell Gallery
Start PowerShell, copy and run the following commands: PS> CD C:\MSAL.PS PS> Import-Module .\MSAL.PS.psd1 If you are querying Active Directory for orphaned keys, install the Remote Server Administrator Tools (RSAT): Active Directory Domain Services and Lightweight Directory Services Tools Install via Settings (Windows 10, version 1809 or later)
Or Install via PowerShell PS> dism /online /Add-Capability /CapabilityName:Rsat.ActiveDirectory.DS-LDS.Tools~~~~0.0.1.0 Or install via download
|
Run the WHfBTools PowerShell Module
If your environment has Azure Active Directory joined or hybrid Azure Active Directory joined devices, follow the Azure Active Directory steps to identify and remove keys. The key removals in Azure will sync to Active Directory through Azure AD Connect.
If your environment is on-premises only, follow the Active Directory steps to identify and remove keys.
|
Querying for orphaned keys and keys affected by CVE-2017-15361 (ROCA) |
|
Query for keys in Azure Active Directory using the following command: PS> Get-AzureADWHfBKeys -Logging -Report -Tenant contoso.com -All | Export-Csv C:\AzureKeys.csv This command will query the “contoso.com” tenant for all registered Windows Hello for Business public keys and will output that information to C:\AzureKeys.csv. Replace contoso.com with your tenant name to query your tenant. The Csv output, AzureKeys.csv, will contain the following information for each key:
Get-AzureADWHfBKeys will also output a summary of the keys that were queried. This summary provides the following information:
Note There may be stale devices in your Azure AD tenant with Windows Hello for Business keys associated with them. These keys will not be reported as orphaned even though those devices are not being actively used. We recommend following How To: Manage stale devices in Azure AD to clean up stale devices before querying for orphaned keys.
Query for keys in Active Directory using the following command: PS> Get-ADWHfBKeys -Logging -Report -Domain contoso | Export-Csv C:\ADKeys.csv This command will query the “contoso” domain for all registered Windows Hello for Business public keys and will output that information to C:\ADKeys.csv. Replace contoso with your domain name to query your domain. The Csv output, ADKeys.csv, will contain the following information for each key:
Get-ADWHfBKeys will also output a summary of the keys that were queried. This summary provides the following information:
Note: If you have a hybrid environment with Azure AD joined devices and run “Get-ADWHfBKeys” in your on-premises domain, the number of orphaned keys may not be accurate. This is because Azure AD joined devices are not present in Active Directory and keys associated with Azure AD joined devices may show up as orphaned. |
|
Remove orphaned, ROCA vulnerable keys from the directory |
|
Remove keys in Azure Active Directory using the following steps:
PS> Import-Csv C:\ROCAKeys.csv | Remove-AzureADWHfBKey -Tenant contoso.com -Logging This command imports the list of orphaned, ROCA vulnerable keys and removes them from the contoso.com tenant. Replace contoso.com with your tenant name to remove keys from your tenant. N ote If you delete ROCA vulnerable WHfB keys that are not orphaned yet, it will cause disruption to your users. You should ensure that these keys are orphaned before removing them from the directory.
Remove keys in Active Directory using the following steps: Note Removing orphaned keys from Active Directory in hybrid environments will result in the keys being recreated as part of the Azure AD Connect sync process. If you are in a hybrid environment, remove keys only from Azure AD
PS> Import-Csv C:\ROCAKeys.csv | Remove-ADWHfBKey -Logging This command imports the list of orphaned, ROCA vulnerable keys and removes them from your domain. Note If you delete ROCA vulnerable WHfB keys that are not orphaned yet, it will cause disruption to your users. You should ensure that these keys are orphaned before removing them from the directory. |
