New-HgsGuardian

Module:

HgsClient Module

Creates a Host Guardian Service guardian.

Syntax

AcceptCertificates

New-HgsGuardian
    [-Name] <String>
    -SigningCertificate <String>
    -EncryptionCertificate <String>
    [-SigningCertificatePassword <SecureString>]
    [-EncryptionCertificatePassword <SecureString>]
    [-AllowExpired]
    [-AllowUntrustedRoot]
    [-WhatIf]
    [-Confirm]
    [<CommonParameters>]

ByThumbprints

New-HgsGuardian
    [-Name] <String>
    -SigningCertificateThumbprint <String>
    -EncryptionCertificateThumbprint <String>
    [-AllowExpired]
    [-AllowUntrustedRoot]
    [-WhatIf]
    [-Confirm]
    [<CommonParameters>]

GenerateCertificates

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" -GenerateCertificates

This 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 $SecureStringPassword02

The 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.

Parameter properties

Type:	SwitchParameter
Default value:	None
Supports wildcards:	False
DontShow:	False

Parameter sets

AcceptCertificates

Position:	Named
Mandatory:	False
Value from pipeline:	False
Value from pipeline by property name:	False
Value from remaining arguments:	False

ByThumbprints

Position:	Named
Mandatory:	False
Value from pipeline:	False
Value from pipeline by property name:	False
Value from remaining arguments:	False

-AllowUntrustedRoot

Indicates that this cmdlet can create a guardian by using self-signed certificates.

Parameter properties

Type:	SwitchParameter
Default value:	None
Supports wildcards:	False
DontShow:	False

Parameter sets

AcceptCertificates

Position:	Named
Mandatory:	False
Value from pipeline:	False
Value from pipeline by property name:	False
Value from remaining arguments:	False

ByThumbprints

Position:	Named
Mandatory:	False
Value from pipeline:	False
Value from pipeline by property name:	False
Value from remaining arguments:	False

-Confirm

Prompts you for confirmation before running the cmdlet.

Parameter properties

Type:	SwitchParameter
Default value:	False
Supports wildcards:	False
DontShow:	False
Aliases:	cf

Parameter sets

(All)

Position:	Named
Mandatory:	False
Value from pipeline:	False
Value from pipeline by property name:	False
Value from remaining arguments:	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.

Parameter properties

Type:	String
Default value:	None
Supports wildcards:	False
DontShow:	False

Parameter sets

AcceptCertificates

Position:	Named
Mandatory:	True
Value from pipeline:	False
Value from pipeline by property name:	False
Value from remaining arguments:	False

-EncryptionCertificatePassword

Specifies the password to decrypt the .pfx file that contains the encryption certificate.

Parameter properties

Type:	SecureString
Default value:	None
Supports wildcards:	False
DontShow:	False

Parameter sets

AcceptCertificates

Position:	Named
Mandatory:	False
Value from pipeline:	False
Value from pipeline by property name:	False
Value from remaining arguments:	False

-EncryptionCertificateThumbprint

Specifies the encryption certificate thumbprint.

Parameter properties

Type:	String
Default value:	None
Supports wildcards:	False
DontShow:	False

Parameter sets

ByThumbprints

Position:	Named
Mandatory:	True
Value from pipeline:	False
Value from pipeline by property name:	False
Value from remaining arguments:	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.

Parameter properties

Type:	SwitchParameter
Default value:	None
Supports wildcards:	False
DontShow:	False

Parameter sets

GenerateCertificates

Position:	Named
Mandatory:	True
Value from pipeline:	False
Value from pipeline by property name:	False
Value from remaining arguments:	False

-Name

Specifies a name for the new guardian.

Parameter properties

Type:	String
Default value:	None
Supports wildcards:	False
DontShow:	False

Parameter sets

(All)

Position:	1
Mandatory:	True
Value from pipeline:	True
Value from pipeline by property name:	False
Value from remaining arguments:	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.

Parameter properties

Type:	String
Default value:	None
Supports wildcards:	False
DontShow:	False

Parameter sets

AcceptCertificates

Position:	Named
Mandatory:	True
Value from pipeline:	False
Value from pipeline by property name:	False
Value from remaining arguments:	False

-SigningCertificatePassword

Specifies the password necessary to decrypt the signing certificate .pfx file.

Parameter properties

Type:	SecureString
Default value:	None
Supports wildcards:	False
DontShow:	False

Parameter sets

AcceptCertificates

Position:	Named
Mandatory:	False
Value from pipeline:	False
Value from pipeline by property name:	False
Value from remaining arguments:	False

-SigningCertificateThumbprint

Specifies the thumbprint of a signing certificate located in the local computer certificate store.

Parameter properties

Type:	String
Default value:	None
Supports wildcards:	False
DontShow:	False

Parameter sets

ByThumbprints

Position:	Named
Mandatory:	True
Value from pipeline:	False
Value from pipeline by property name:	False
Value from remaining arguments:	False

-WhatIf

Shows what would happen if the cmdlet runs. The cmdlet is not run.

Parameter properties

Type:	SwitchParameter
Default value:	False
Supports wildcards:	False
DontShow:	False
Aliases:	wi

Parameter sets

(All)

Position:	Named
Mandatory:	False
Value from pipeline:	False
Value from pipeline by property name:	False
Value from remaining arguments:	False

CommonParameters

This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.

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.

Related Links

• Export-HgsGuardian
• Get-HgsGuardian
• Import-HgsGuardian
• Remove-HgsGuardian