New-HgsGuardian
Creates a Host Guardian Service guardian.
Syntax
New-HgsGuardian
[-Name] <String>
-SigningCertificate <String>
[-SigningCertificatePassword <SecureString>]
-EncryptionCertificate <String>
[-EncryptionCertificatePassword <SecureString>]
[-AllowExpired]
[-AllowUntrustedRoot]
[-WhatIf]
[-Confirm]
[<CommonParameters>] New-HgsGuardian
[-Name] <String>
[-AllowExpired]
[-AllowUntrustedRoot]
-SigningCertificateThumbprint <String>
-EncryptionCertificateThumbprint <String>
[-WhatIf]
[-Confirm]
[<CommonParameters>] New-HgsGuardian
[-Name] <String>
[-GenerateCertificates]
[-WhatIf]
[-Confirm]
[<CommonParameters>] Description
The New-HgsGuardian cmdlet creates a cryptographic entity called a Host Guardian Service guardian. A guardian is a principal that you can grant access to the key that is contained in a key protector.
Examples
Example 1: Create a guardian
PS C:\> New-HgsGuardian -Name "Guardian11" -GenerateCertificatesThis command creates a Host Guardian Service guardian named Guardian11. This guardian can act as owner for a key protector. Because this command specifies the GenerateCertificates parameter, it generates signing and encryption certificates.
Example 2: Create a guardian by using existing certificates
PS C:\> $SecureStringPassword01 = ConvertTo-SecureString "<Password01>" -AsPlainText -Force
PS C:\> $SecureStringPassword02 = ConvertTo-SecureString "<Password02>" -AsPlainText -Force
PS C:\> New-HgsGuardian -Name "Guardian21" -SigningCertificate "C:\Keys\SigningCertificate.pfx" -SigningCertificatePassword $SecureStringPassword01 -EncryptionCertificate "C:\Keys\EncryptionCertificate.pfx" -EncryptionCertificatePassword $SecureStringPassword02The first two commands create passwords, as secure strings, by using the ConvertTo-SecureString cmdlet.
For more information, type Get-Help ConvertTo-SecureString.
The commands store the passwords in two variables.
The final command creates a guardian named Guardian21. The command specifies the necessary signing and encryption certificates as password protected .pfx files. The passwords stored in the $SecureStringPassword01 and $SecureStringPassword02 must match the passwords used to generate the .pfx files.
Parameters
-AllowExpired
Indicates that this cmdlet can create a guardian by using certificates that are expired.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-AllowUntrustedRoot
Indicates that this cmdlet can create a guardian by using self-signed certificates.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Confirm
Prompts you for confirmation before running the cmdlet.
| Type: | SwitchParameter |
| Aliases: | cf |
| Position: | Named |
| Default value: | False |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-EncryptionCertificate
Specifies the path of a .pfx file that contains a password protected encryption certificate for the guardian. This .pfx file contains the public and private keys.
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | True |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-EncryptionCertificatePassword
Specifies the password to decrypt the .pfx file that contains the encryption certificate.
| Type: | SecureString |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-EncryptionCertificateThumbprint
Specifies the encryption certificate thumbprint.
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | True |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-GenerateCertificates
Indicates that this cmdlet generates self-signed signing and encryption certificates for the guardian. The certificates contain the public and private keys.
If you specify this parameter, the new guardian does not have a trusted root. Therefore, you must also specify the AllowUntrustedRoot parameter.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | None |
| Required: | True |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Name
Specifies a name for the new guardian.
| Type: | String |
| Position: | 1 |
| Default value: | None |
| Required: | True |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
-SigningCertificate
Specifies the path of a .pfx file that contains a password protected signing certificate for the guardian. This .pfx file contains the public and private keys.
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | True |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-SigningCertificatePassword
Specifies the password necessary to decrypt the signing certificate .pfx file.
| Type: | SecureString |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-SigningCertificateThumbprint
Specifies the thumbprint of a signing certificate located in the local computer certificate store.
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | True |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-WhatIf
Shows what would happen if the cmdlet runs. The cmdlet is not run.
| Type: | SwitchParameter |
| Aliases: | wi |
| Position: | Named |
| Default value: | False |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
Outputs
CimInstance
The Microsoft.Management.Infrastructure.CimInstance object is a wrapper class that displays Windows Management Instrumentation (WMI) objects.
The path after the pound sign (#) provides the namespace and class name for the underlying WMI object.