microsoft / guardedfabrictools

PowerShell tools for managing a Hyper-V guarded fabric and shielded virtual machines

Guarded Fabric Tools

A PowerShell module containing tools to make deploying shielded virtual machines and managing a guarded fabric easier.

Included tools:

• New-ShieldedVM helps you deploy a shielded VM from PowerShell using a template disk and shielding data file. This function is intended for use on a guarded host.
• ConvertTo-ShieldedVM allows you to quickly add a virtual TPM and security policy to an existing VM. This function is intended for use on a guarded host.
• New-ShieldingDataAnswerFile generates answer files (also called unattend files) that automate configuration of Windows or Linux in a shielded VM. These answer files are compliant with System Center Virtual Machine Manager and New-ShieldedVM. This function is intended for use on the machine where you are preparing a shielding data file.
• Get-HgsAttestationReport queries the event log on an HGS server for information about recent attestation attempts to help you understand which hosts have tried attesting and whether or not they passed. This function is intended for use on an HGS server. Additional documentation
• Add-AccessRule and its accompanying extensions to the X509Certificate2 class in PowerShell allow you to manage the access control list (ACL) on certificate private keys through PowerShell. This function is intended for use on an HGS server when granting the group managed service account access to use the HGS encryption and signing keys. Additional documentation

Check out the official documentation for more information about shielded virtual machines in Windows Server.

Installing

To use the Guarded Fabric Tools in a production environment, download and install the digitally signed module from the PowerShell Gallery. See Guarded Fabric Tools on the PowerShell Gallery.

Run the following command in PowerShell to install the module.

Install-Module -Name GuardedFabricTools

If the computer where you're installing the module does not have internet connectivity, use Save-Module to download the files and copy them manually to C:\Program Files\WindowsPowerShell\Modules on the target machine.

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com.

When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.

guardedfabrictools's Issues

ShieldedVMProvisioning Supporting Module

There seems to be a lack of documentation around the ShieldedVMProvisioning supporting module that this module utilizes. I also cannot find where to actually get the ShieldedVMProvisioning module to fully utilize this module.

As an example just running the new-shieldedvm cmdlet will error on:

Get-KeyProtectorFromShieldingDataFile : The term 'Get-KeyProtectorFromShieldingDataFile' is not recognized as the name of a cmdlet, function, script file, or operable program. Check the spelling of the name, or if a path was included, verify that the path is correct and try again.

Can you provide further clarification around the ShieldedVMProvisioning module and where to actually get this from.

https://docs.microsoft.com/en-us/powershell/module/shieldedvmprovisioning/?view=win10-ps#shieldedvmprovisioning

Running this module on guarded hosts that has CI Policy lockdown isn't possible if you don't publish the public key/cert this was signed with

Running this module on guarded hosts that has CI Policy lockdown isn't possible if you don't publish the public key/cert this was signed with. Please consider adding the cert with the public key so we can trust this code in our CI policy

New-ShieldedVM should enable live migration encryption by default

PDKs with "encryption supported" policy do not require live migration traffic to be encrypted, but New-ShieldedVM should enable it anyways to promote secure defaults. "Shielded" policies will already enforce this requirement.

Deleting Cert didn't invalidate Handlecache

Hi,

I've used the module to backup ACLs of a cert, delete it with option -deletekey and reimport it via certutil to a different CSP/KSP (HSM), after that I tried to restore the ACLs. That failed with the following exception:
Exception setting "Acl": "Exception setting "Acl": "The system cannot find the file specified""

If I invalidate the handle after importing the cert with certutil with this code

$handle=$global:ContosoCertificateManagementHandleCache[$cert.GetHashCode()]
$handle.dispose()

it works.

Is it possible to automatically invalidate the handle if the cert get's deleted?

greetings
Carsten

PS: Do you have any good tipps how to import a certificates privatekey to a CSP/KSP without using certutil using only powershell?

Add Add-Type references case for PowerShell Core support

Trying out this module in PowerShell Core earlier, I ran into the following:

> Install-Module GuardedFabricTools
# Success
> Import-Module GuardedFabricTools

Add-Type : (157,17): error CS0246: The type or namespace name 'SafeNCryptKeyHandle' could not be found (are you missing a using directive or an assembly reference?)
            out SafeNCryptKeyHandle phCryptProvOrNCryptKey,
                ^
At C:\Users\Administrator\Documents\PowerShell\Modules\GuardedFabricTools\1.0.0\CertificateManagement\CertificateManagement.psm1:633 char:5
+     Add-Type -TypeDefinition $source -Language CSharp -ReferencedAsse ...
+     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ CategoryInfo          : InvalidData: ((157,17): error...bly reference?):CSDiagnostic) [Add-Type], Exception
+ FullyQualifiedErrorId : SOURCE_CODE_ERROR,Microsoft.PowerShell.Commands.AddTypeCommand

ipmo : The given assembly name or codebase was invalid. (Exception from HRESULT: 0x80131047)
At line:1 char:1
+ ipmo GuardedFabricTools
+ ~~~~~~~~~~~~~~~~~~~~~~~
+ CategoryInfo          : NotSpecified: (:) [Import-Module], FileLoadException
+ FullyQualifiedErrorId : System.IO.FileLoadException,Microsoft.PowerShell.Commands.ImportModuleCommand

I had a quick look into the the relevant part of the module:
https://github.com/Microsoft/GuardedFabricTools/blob/c62650db8fc02b5273c272477594762b59d68d19/CertificateManagement/CertificateManagement.psm1#L18-L38

(The above sets up the references used by Add-Type below)

I edited the file and replaced the code above with this:

if (Test-Nano)
{
    Write-Verbose "Running on Nano, using API sets."
    $securityDll = "api-ms-win-security-base-l1-2-0"
    $capiDll = "api-ms-win-security-cryptoapi-l1-1-0"
    $PrepareConstrainedRegions = "";
    $references =   "System.Security.Cryptography.X509Certificates.dll", `
                    "System.Security.Cryptography.Cng.dll", `
                    "System.IO.FileSystem.AccessControl.dll", `
                    "System.Runtime.Handles.dll", `
                    "System.Security.AccessControl.dll", `
                    "Microsoft.Win32.Primitives.dll" | % { Join-Path "C:\Windows\system32\DotNetCore\v1.0\" $_ }
}
elseif ($PSEdition -eq 'Core')
{
    $securityDll = "advapi32.dll"
    $capiDll = "advapi32.dll"
    $PrepareConstrainedRegions = ""
    $references = "System.Security.Cryptography.X509Certificates.dll", `
                  "System.Security.Cryptography.Cng.dll", `
                  "System.IO.FileSystem.AccessControl.dll", `
                  "System.Runtime.Handles.dll", `
                  "System.Security.AccessControl.dll", `
                  "Microsoft.Win32.Primitives.dll" | % { Join-Path $PSHome $_ }
}
else
{
    Write-Verbose "Not running on Nano, using default Win32 binaries."
    $securityDll = "advapi32.dll"
    $capiDll = "advapi32.dll"
    $references = @()
    $PrepareConstrainedRegions = "RuntimeHelpers.PrepareConstrainedRegions();"
}

That allowed me to load the module.

I'm not sure if that's the right fix, so I haven't opened a PR yet. But if we decide this is the way to go (and that this is a wanted change), I can easily do so.

Update module in PSGallery

The version of these tools published to PSGallery are outdated and missing fixes, especially the ones around Static IPs