Carbon_Permission

DSC resource for managing permissions on files, directories, registry keys, or a certificate's private key.

Syntax

Carbon_Permission [String] #ResourceName
{
    Identity = [string]
    Path = [string]
    [ApplyTo = [string]{ ChildContainers | ChildContainersA
ndChildLeaves | ChildLeaves | Container | ContainerAndChildContainers | ContainerAndChildContainersAndChildLeaves | ContainerAndChildLeaves | ContainerAndLeaves | ContainerAndSubContainers | ContainerAndSubContainersAndLeaves | Leaves | SubContainers | SubContainersAndLeaves }]
    [DependsOn = [string[]]]
    [Ensure = [string]{ Absent | Present }]
    [Permission = [string[]]]
    [PsDscRunAsCredential = [PSCredential]]
}

Description

The Carbon_Permission resource can grant or revoke permissions on a file, a directory, a registry key, or a certificate's private key.

Granting Permission

Permissions are granted when the Ensure property is set to Present.

When granting permissions, you must supply a value for the Permission property. Valid values are:

The ApplyTo property is only used when setting permissions on a directory or a registry key. Valid values are:

Revoking Permission

Permissions are revoked when the Ensure property is set to Absent. All a user or group's permissions are revoked. You can't revoke part of a principal's access. If you want to revoke part of a principal's access, set the Ensure property to Present and the Permissions property to the list of properties you want the principal to have.

Carbon_Permission is new in Carbon 2.0.

Related Commands

Parameters

Name Type Description Required? Pipeline Input Default Value
Path String

The path on which the permissions should be granted. Can be a file system, registry path, or certificate path.

 true false
Identity String

The user or group getting the permissions.

 true false
Permission String[]

The permission: e.g. FullControl, Read, etc. Mandatory when granting permission. Valid values are CreateFiles, AppendData, CreateSubKey, EnumerateSubKeys, CreateLink, Delete, ChangePermissions, ExecuteFile, DeleteSubdirectoriesAndFiles, FullControl, GenericRead, GenericAll, GenericExecute, QueryValues, ReadAttributes, ReadData, ReadExtendedAttributes, GenericWrite, Notify, ReadPermissions, Read, ReadAndExecute, Modify, SetValue, ReadKey, TakeOwnership, WriteAttributes, Write, Synchronize, WriteData, WriteExtendedAttributes, WriteKey.

 false false
ApplyTo String

How to apply container permissions. This controls the inheritance and propagation flags. Default is full inheritance, e.g. ContainersAndSubContainersAndLeaves. This parameter is only used when Path is a directory or registry key. Valid values are Container, SubContainers, ContainerAndSubContainers, Leaves, ContainerAndLeaves, SubContainersAndLeaves, ContainerAndSubContainersAndLeaves, ChildContainers, ContainerAndChildContainers, ChildLeaves, ContainerAndChildLeaves, ChildContainersAndChildLeaves, ContainerAndChildContainersAndChildLeaves.

 false false
Ensure String

If set to Present, permissions are set. If Absent, all permissions to $Path removed.

 false false Present

EXAMPLE 1

Demonstrates how to grant permissions to an item on the file system.

Carbon_Permission GrantPermission
{
    Path = 'C:\Projects\Carbon';
    Identity = 'CarbonServiceUser';
    Permission = 'ReadAndExecute';
}

This will grant ReadAndExecute permission to the CarbonServiceUser on the C:\Projects\Carbon directory.

EXAMPLE 2

Demonstrates how to grant permissions to a registry key.

Carbon_Permission GrantPermission
{
    Path = 'hklm:\SOFTWARE\Carbon';
    Identity = 'CarbonServiceUser';
    Permission = 'ReadKey';
}

This will grant ReadKey permission to the CarbonServiceUser on the C:\Projects\Carbon directory.

EXAMPLE 3

Demonstrates how to grant permissions to a certificate's private key and how to grant multiple permissions.

Carbon_Permission GrantPermission
{
    Path = 'cert:\LocalMachine\My\1234567890ABCDEF1234567890ABCDEF12345678';
    Identity = 'CarbonServiceUser';
    Permission = 'GenericRead','ReadKey';
}

This will grant GenericRead and ReadKey permissions to the CarbonServiceUser on the C:\Projects\Carbon directory.

EXAMPLE 4

Demonstrates how to revoke permissions.

Carbon_Permission GrantPermission
{
    Path = 'C:\Projects\Carbon';
    Identity = 'CarbonServiceUser';
    Ensure = 'Absent';
}

This will revoke all of the CarbonServiceUser user's permissions on the C:\Projects\Carbon.

Copyright 2012 - 2018 Aaron Jensen.