Set‑CertificatePrivateKeySecurityDescriptor

SYNOPSIS

Sets the exact DACL of a supported certificate private key.

SYNTAX

Certificate (Default)

Set-CertificatePrivateKeySecurityDescriptor -Certificate <X509Certificate2> -ProviderName <String>
 -KeyName <String> -Sddl <String> [-ConcurrencyToken <String>] [-ExpectedCanonicalTarget <String>] [-PassThru]
 [-WhatIf] [-Confirm] [<CommonParameters>]

Key

Set-CertificatePrivateKeySecurityDescriptor -ProviderName <String> -KeyName <String> -KeyScope <String>
 -Sddl <String> [-ConcurrencyToken <String>] [-ExpectedCanonicalTarget <String>] [-PassThru]
 [-WhatIf] [-Confirm] [<CommonParameters>]

DESCRIPTION

Persists one caller-supplied DACL on the persisted CNG key under a canonical write lock. This is the explicit escape hatch for a complete desired-state descriptor. It still enforces the software-only provider, the critical-binding refusal, the plain-ACE and no-new-deny rules, and the SYSTEM, Administrators, and service-grant preservation gates, and it rolls the key back exactly when the write cannot be verified.

Only the access section is written. The owner and group of the key are never read or changed, so an owner or group in Sddl is ignored rather than applied.

EXAMPLES

EXAMPLE 1

$certificate = Get-Item 'Cert:\LocalMachine\My\0123456789ABCDEF'
Set-CertificatePrivateKeySecurityDescriptor -Certificate $certificate `
    -ProviderName 'Microsoft Software Key Storage Provider' `
    -KeyName 'WorkloadKey' -Sddl 'D:P(A;;FA;;;SY)(A;;FA;;;BA)' -WhatIf

Previews replacing the private-key DACL with the exact desired state.

EXAMPLE 2

Set-CertificatePrivateKeySecurityDescriptor `
    -ProviderName 'Microsoft Software Key Storage Provider' `
    -KeyName 'WorkloadKey' -KeyScope Machine `
    -Sddl 'D:P(A;;FA;;;SY)(A;;FA;;;BA)' -Confirm:$false

Writes the same desired state without a certificate, which is how a restore and a desired-state resource address the key.

PARAMETERS

-Certificate

An exact X509Certificate2 object with the private key to change. The command does not dispose the caller-owned certificate.

Type: X509Certificate2
Parameter Sets: Certificate
Aliases:

Required: True
Position: Named
Default value: None
Accept pipeline input: True (ByValue)
Accept wildcard characters: False

-ConcurrencyToken

The ConcurrencyToken of an earlier Get-CertificatePrivateKeySecurityDescriptor result. The write is rejected when the stored DACL changed after that read.

Type: String
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-ExpectedCanonicalTarget

The canonical key identity an earlier read resolved. The write is rejected when the provider and key name now resolve to a different key container, which a delete and recreate under the same key name produces.

Type: String
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-KeyName

The exact expected persisted CNG key name.

Type: String
Parameter Sets: (All)
Aliases:

Required: True
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-KeyScope

Selects the machine or current-user key store when the key is addressed without a certificate. Every gate still applies.

Type: String
Parameter Sets: Key
Aliases:

Required: True
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-PassThru

Returns the stored private-key descriptor after persistence.

Type: SwitchParameter
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False

-ProviderName

The exact expected CNG provider.

Type: String
Parameter Sets: (All)
Aliases:

Required: True
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-Sddl

The complete desired DACL in SDDL form.

Type: String
Parameter Sets: (All)
Aliases:

Required: True
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-Confirm

Prompts you for confirmation before running the cmdlet.

Type: SwitchParameter
Parameter Sets: (All)
Aliases: cf

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-WhatIf

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

Type: SwitchParameter
Parameter Sets: (All)
Aliases: wi

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

CommonParameters

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

INPUTS

System.Security.Cryptography.X509Certificates.X509Certificate2

OUTPUTS

None

WindowsAccessControl.CertificatePrivateKeySecurityDescriptor

NOTES

RELATED LINKS