Add‑CertificatePrivateKeyAccessRule

SYNOPSIS

Adds typed allow rules to a supported certificate private-key DACL.

SYNTAX

Certificate (Default)

Add-CertificatePrivateKeyAccessRule -Certificate <X509Certificate2> -ProviderName <String> -KeyName <String>
 -Account <Object[]> -AccessRights <WindowsCryptoKeyRights> [-ConcurrencyToken <String>] [-PassThru]
 [-WhatIf] [-Confirm] [<CommonParameters>]

Key

Add-CertificatePrivateKeyAccessRule -ProviderName <String> -KeyName <String> -KeyScope <String>
 -Account <Object[]> -AccessRights <WindowsCryptoKeyRights> [-ConcurrencyToken <String>] [-PassThru]
 [-WhatIf] [-Confirm] [<CommonParameters>]

DESCRIPTION

Resolves and deduplicates every account, stages the requested allow ACEs on the current private-key DACL, and persists the result once under a canonical write lock. The write is refused when the provider is not a software-only key storage provider, when the same private key serves a critical binding, when the candidate contains an ACE that is not a plain allow or deny, or when the result would remove SYSTEM, Administrators, or an existing service grant.

Only allow rules can be added. A deny ACE naming a group that contains SYSTEM or Administrators would lock the key with no per-account check able to detect it, so a new deny ACE is rejected at the write boundary.

EXAMPLES

EXAMPLE 1

$certificate = Get-Item 'Cert:\LocalMachine\My\0123456789ABCDEF'
Add-CertificatePrivateKeyAccessRule -Certificate $certificate `
    -ProviderName 'Microsoft Software Key Storage Provider' `
    -KeyName 'WorkloadKey' -Account 'CONTOSO\WebService' -AccessRights Read

Grants the workload identity read access to the private key.

PARAMETERS

-AccessRights

Private-key rights to add, such as Read or FullControl.

Type: WindowsCryptoKeyRights
Parameter Sets: (All)
Aliases:
Accepted values: ReadData, WriteData, AppendData, ReadExtendedAttributes, WriteExtendedAttributes, Execute, ReadAttributes, WriteAttributes, Delete, ReadPermissions, ChangePermissions, TakeOwnership, Synchronize, Read, ReadAndExecute, Write, FullControl, GenericAll, GenericExecute, GenericWrite, GenericRead

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

-Account

One or more account names, SIDs, identity references, or module identities.

Type: Object[]
Parameter Sets: (All)
Aliases: IdentityReference, ID

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

-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

-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 explicit private-key access rules 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

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

NOTES

RELATED LINKS