PowerShell - Grant-Permission

The Grant-Permission functions grants permissions to files, directories, registry keys, and certificate private key/key containers. It detects what you are setting permissions on by inspecting the path of the item. If the path is relative, it uses the current location to determine if file system, registry, or private keys permissions should be set.

The Permissions attribute should be a list of FileSystemRights, RegistryRights, or CryptoKeyRights, for files/directories, registry keys, and certificate private keys, respectively. These commands will show you the values for the appropriate permissions for your object:

[Enum]::GetValues([Security.AccessControl.FileSystemRights])
[Enum]::GetValues([Security.AccessControl.RegistryRights])
[Enum]::GetValues([Security.AccessControl.CryptoKeyRights])

Beginning with Carbon 2.0, permissions are only granted if they don't exist on an item (inherited permissions are ignored). If you always want to grant permissions, use the Force switch.

Before Carbon 2.0, this function returned any new/updated access rules set on Path. In Carbon 2.0 and later, use the PassThru switch to get an access rule object back (you'll always get one regardless if the permissions changed or not).

By default, permissions allowing access are granted. Beginning in Carbon 2.3.0, you can grant permissions denying access by passing Deny as the value of the Type parameter.

Directories and Registry Keys

When setting permissions on a container (directory/registry key) you can control inheritance and propagation flags using the ApplyTo parameter. This parameter is designed to hide the complexities of the Windows' inheritance and propagation flags. There are 13 possible combinations.

Given this tree

    C
   / \
  CC CL
 /  \
GC  GL

where

C is the Container permissions are getting set on
CC is a Child Container
CL is a Child Leaf
GC is a Grandchild Container and includes all sub-containers below it
GL is a Grandchild Leaf

The ApplyTo parameter takes one of the following 13 values and applies permissions to:

Container - The container itself and nothing below it.
SubContainers - All sub-containers under the container, e.g. CC and GC.
Leaves - All leaves under the container, e.g. CL and GL.
ChildContainers - Just the container's child containers, e.g. CC.
ChildLeaves - Just the container's child leaves, e.g. CL.
ContainerAndSubContainers - The container and all its sub-containers, e.g. C, CC, and GC.
ContainerAndLeaves - The container and all leaves under it, e.g. C and CL.
SubContainerAndLeaves - All sub-containers and leaves, but not the container itself, e.g. CC, CL, GC, and GL.
ContainerAndChildContainers - The container and all just its child containers, e.g. C and CC.
ContainerAndChildLeaves - The container and just its child leaves, e.g. C and CL.
ContainerAndChildContainersAndChildLeaves - The container and just its child containers/leaves, e.g. C, CC, and CL.
ContainerAndSubContainersAndLeaves - Everything, full inheritance/propogation, e.g. C, CC, GC, GL. This is the default.
ChildContainersAndChildLeaves - Just the container's child containers/leaves, e.g. CC and CL.

The following table maps ContainerInheritanceFlags values to the actual InheritanceFlags and PropagationFlags values used:

ContainerInheritanceFlags                   InheritanceFlags                 PropagationFlags
-------------------------                   ----------------                 ----------------
Container                                   None                             None
SubContainers                               ContainerInherit                 InheritOnly
Leaves                                      ObjectInherit                    InheritOnly
ChildContainers                             ContainerInherit                 InheritOnly,
                                                                             NoPropagateInherit
ChildLeaves                                 ObjectInherit                    InheritOnly
ContainerAndSubContainers                   ContainerInherit                 None
ContainerAndLeaves                          ObjectInherit                    None
SubContainerAndLeaves                       ContainerInherit,ObjectInherit   InheritOnly
ContainerAndChildContainers                 ContainerInherit                 None
ContainerAndChildLeaves                     ObjectInherit                    None
ContainerAndChildContainersAndChildLeaves   ContainerInherit,ObjectInherit   NoPropagateInherit
ContainerAndSubContainersAndLeaves          ContainerInherit,ObjectInherit   None
ChildContainersAndChildLeaves               ContainerInherit,ObjectInherit   InheritOnly

The above information adapated from Manage Access to Windows Objects with ACLs and the .NET Framework, published in the November 2004 copy of MSDN Magazine.

If you prefer to speak in InheritanceFlags or PropagationFlags, you can use the ConvertTo-ContainerInheritaceFlags function to convert your flags into Carbon's flags.

Certificate Private Keys/Key Containers

When setting permissions on a certificate's private key/key container, if a certificate doesn't have a private key, it is ignored and no permissions are set. Since certificate's are always leaves, the ApplyTo parameter is ignored.

When using the -Clear switch, note that the local Administrators account will always remain. In testing on Windows 2012 R2, we noticed that when Administrators access was removed, you couldn't read the key anymore.

Related Commands

Parameters

Return Values

EXAMPLE 1

Grants the Enterprise's engineering group full control on the engine room. Very important if you want to get anywhere.

EXAMPLE 2

Grants the Enterprise's interns access to read about the warp drive. They need to learn someday, but at least they can't change anything.

EXAMPLE 3

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, 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. For file system items, use values from System.Security.AccessControl.FileSystemRights. For registry items, use values from System.Security.AccessControl.RegistryRights.	true	false
ApplyTo	ContainerInheritanceFlags	How to apply container permissions. This controls the inheritance and propagation flags. Default is full inheritance, e.g. `ContainersAndSubContainersAndLeaves`. This parameter is ignored if `Path` is to a leaf item.	false	false	ContainerAndSubContainersAndLeaves
Type	AccessControlType	The type of rule to apply, either `Allow` or `Deny`. The default is `Allow`, which will allow access to the item. The other option is `Deny`, which will deny access to the item. This parameter was added in Carbon 2.3.0.	false	false	Allow
Clear	SwitchParameter	Removes all non-inherited permissions on the item.	false	false	False
PassThru	SwitchParameter	Returns an object representing the permission created or set on the `Path`. The returned object will have a `Path` propery added to it so it can be piped to any cmdlet that uses a path. The `PassThru` switch is new in Carbon 2.0.	false	false	False
Force	SwitchParameter	Grants permissions, even if they are already present.	false	false	False
WhatIf	SwitchParameter		false	false
Confirm	SwitchParameter		false	false
CommonParameters		This cmdlet supports common parameters. For more information type `Get-Help about_CommonParameters`.

Grants the Enterprise's engineering group full control on the engine room. Any non-inherited, existing access rules are removed from C:\EngineRoom.

EXAMPLE 4

Grants the Enterprise's engineering group full control on the 1234567890ABCDEF1234567890ABCDEF12345678 certificate's private key/key container.

EXAMPLE 5

Demonstrates how to grant deny permissions on an objecy with the Type parameter.

Grant-Permission

Syntax

Description