< Back
Test-CPermission
Post
NAME Test-CPermission
SYNOPSIS
Tests if permissions are set on a file, directory, registry key, or certificate's private key/key container.
SYNTAX
Test-CPermission [-Path] <String> [-Identity] <String> [-Permission] <String[]> [[-ApplyTo] {Container |
SubContainers | ContainerAndSubContainers | Leaves | ContainerAndLeaves | SubContainersAndLeaves |
ContainerAndSubContainersAndLeaves | ChildContainers | ContainerAndChildContainers | ChildLeaves |
ContainerAndChildLeaves | ChildContainersAndChildLeaves | ContainerAndChildContainersAndChildLeaves}] [-Inherited]
[-Exact] [<CommonParameters>]
DESCRIPTION
Sometimes, you don't want to use `Grant-CPermission` on a big tree. In these situations, use `Test-CPermission`
to see if permissions are set on a given path.
This function supports file system, registry, and certificate private key/key container permissions. You can also
test the inheritance and propogation flags on containers, in addition to the permissions, with the `ApplyTo`
parameter. See [Grant-CPermission](Grant-CPermission.html) documentation for an explanation of the `ApplyTo`
parameter.
Inherited permissions on *not* checked by default. To check inherited permission, use the `-Inherited` switch.
By default, the permission check is not exact, i.e. the user may have additional permissions to what you're
checking. If you want to make sure the user has *exactly* the permission you want, use the `-Exact` switch.
Please note that by default, NTFS will automatically add/grant `Synchronize` permission on an item, which is
handled by this function.
When checking for permissions on certificate private keys/key containers, if a certificate doesn't have a private
key, `$true` is returned.
PARAMETERS
-Path <String>
The path on which the permissions should be checked. Can be a file system or registry path.
Required? true
Position? 1
Default value
Accept pipeline input? false
Accept wildcard characters? false
-Identity <String>
The user or group whose permissions to check.
Required? true
Position? 2
Default value
Accept pipeline input? false
Accept wildcard characters? false
-Permission <String[]>
The permission to test for: e.g. FullControl, Read, etc. For file system items, use values from [System.Securi
ty.AccessControl.FileSystemRights](http://msdn.microsoft.com/en-us/library ... rol.filesy
stemrights.aspx). For registry items, use values from [System.Security.AccessControl.RegistryRights](http://ms
dn.microsoft.com/en-us/library/system.security.accesscontrol.registryrights.aspx).
Required? true
Position? 3
Default value
Accept pipeline input? false
Accept wildcard characters? false
-ApplyTo
The container and inheritance flags to check. Ignored if `Path` is a file. These are ignored if not supplied.
See `Grant-CPermission` for detailed explanation of this parameter. 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.
Required? false
Position? 4
Default value
Accept pipeline input? false
Accept wildcard characters? false
-Inherited [<SwitchParameter>]
Include inherited permissions in the check.
Required? false
Position? named
Default value False
Accept pipeline input? false
Accept wildcard characters? false
-Exact [<SwitchParameter>]
Check for the exact permissions, inheritance flags, and propagation flags, i.e. make sure the identity has
*only* the permissions you specify.
Required? false
Position? named
Default value False
Accept pipeline input? false
Accept wildcard characters? false
<CommonParameters>
This cmdlet supports the common parameters: Verbose, Debug,
ErrorAction, ErrorVariable, WarningAction, WarningVariable,
OutBuffer, PipelineVariable, and OutVariable. For more information, see
about_CommonParameters (https:/go.microsoft.com/fwlink/?LinkID=113216).
INPUTS
OUTPUTS
System.Boolean.
-------------------------- EXAMPLE 1 --------------------------
PS C:\\>Test-CPermission -Identity 'STARFLEET\\JLPicard' -Permission 'FullControl' -Path 'C:\\Enterprise\\Bridge'
Demonstrates how to check that Jean-Luc Picard has `FullControl` permission on the `C:\\Enterprise\\Bridge`.
-------------------------- EXAMPLE 2 --------------------------
PS C:\\>Test-CPermission -Identity 'STARFLEET\\GLaForge' -Permission 'WriteKey' -Path
'HKLM:\\Software\\Enterprise\\Engineering'
Demonstrates how to check that Geordi LaForge can write registry keys at `HKLM:\\Software\\Enterprise\\Engineering`.
-------------------------- EXAMPLE 3 --------------------------
PS C:\\>Test-CPermission -Identity 'STARFLEET\\Worf' -Permission 'Write' -ApplyTo 'Container' -Path
'C:\\Enterprise\\Brig'
Demonstrates how to test for inheritance/propogation flags, in addition to permissions.
-------------------------- EXAMPLE 4 --------------------------
PS C:\\>Test-CPermission -Identity 'STARFLEET\\Data' -Permission 'GenericWrite' -Path
'cert:\\LocalMachine\\My\\1234567890ABCDEF1234567890ABCDEF12345678'
Demonstrates how to test for permissions on a certificate's private key/key container. If the certificate doesn't
have a private key, returns `$true`.
RELATED LINKS
Carbon_Permission
ConvertTo-CContainerInheritanceFlags
Disable-CAclInheritance
Enable-CAclInheritance
Get-CPermission
Grant-CPermission
Revoke-CPermission
http://msdn.microsoft.com/en-us/library ... ights.aspx
http://msdn.microsoft.com/en-us/library ... ights.aspx
http://msdn.microsoft.com/en-us/library ... ights.aspx
SYNOPSIS
Tests if permissions are set on a file, directory, registry key, or certificate's private key/key container.
SYNTAX
Test-CPermission [-Path] <String> [-Identity] <String> [-Permission] <String[]> [[-ApplyTo] {Container |
SubContainers | ContainerAndSubContainers | Leaves | ContainerAndLeaves | SubContainersAndLeaves |
ContainerAndSubContainersAndLeaves | ChildContainers | ContainerAndChildContainers | ChildLeaves |
ContainerAndChildLeaves | ChildContainersAndChildLeaves | ContainerAndChildContainersAndChildLeaves}] [-Inherited]
[-Exact] [<CommonParameters>]
DESCRIPTION
Sometimes, you don't want to use `Grant-CPermission` on a big tree. In these situations, use `Test-CPermission`
to see if permissions are set on a given path.
This function supports file system, registry, and certificate private key/key container permissions. You can also
test the inheritance and propogation flags on containers, in addition to the permissions, with the `ApplyTo`
parameter. See [Grant-CPermission](Grant-CPermission.html) documentation for an explanation of the `ApplyTo`
parameter.
Inherited permissions on *not* checked by default. To check inherited permission, use the `-Inherited` switch.
By default, the permission check is not exact, i.e. the user may have additional permissions to what you're
checking. If you want to make sure the user has *exactly* the permission you want, use the `-Exact` switch.
Please note that by default, NTFS will automatically add/grant `Synchronize` permission on an item, which is
handled by this function.
When checking for permissions on certificate private keys/key containers, if a certificate doesn't have a private
key, `$true` is returned.
PARAMETERS
-Path <String>
The path on which the permissions should be checked. Can be a file system or registry path.
Required? true
Position? 1
Default value
Accept pipeline input? false
Accept wildcard characters? false
-Identity <String>
The user or group whose permissions to check.
Required? true
Position? 2
Default value
Accept pipeline input? false
Accept wildcard characters? false
-Permission <String[]>
The permission to test for: e.g. FullControl, Read, etc. For file system items, use values from [System.Securi
ty.AccessControl.FileSystemRights](http://msdn.microsoft.com/en-us/library ... rol.filesy
stemrights.aspx). For registry items, use values from [System.Security.AccessControl.RegistryRights](http://ms
dn.microsoft.com/en-us/library/system.security.accesscontrol.registryrights.aspx).
Required? true
Position? 3
Default value
Accept pipeline input? false
Accept wildcard characters? false
-ApplyTo
The container and inheritance flags to check. Ignored if `Path` is a file. These are ignored if not supplied.
See `Grant-CPermission` for detailed explanation of this parameter. 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.
Required? false
Position? 4
Default value
Accept pipeline input? false
Accept wildcard characters? false
-Inherited [<SwitchParameter>]
Include inherited permissions in the check.
Required? false
Position? named
Default value False
Accept pipeline input? false
Accept wildcard characters? false
-Exact [<SwitchParameter>]
Check for the exact permissions, inheritance flags, and propagation flags, i.e. make sure the identity has
*only* the permissions you specify.
Required? false
Position? named
Default value False
Accept pipeline input? false
Accept wildcard characters? false
<CommonParameters>
This cmdlet supports the common parameters: Verbose, Debug,
ErrorAction, ErrorVariable, WarningAction, WarningVariable,
OutBuffer, PipelineVariable, and OutVariable. For more information, see
about_CommonParameters (https:/go.microsoft.com/fwlink/?LinkID=113216).
INPUTS
OUTPUTS
System.Boolean.
-------------------------- EXAMPLE 1 --------------------------
PS C:\\>Test-CPermission -Identity 'STARFLEET\\JLPicard' -Permission 'FullControl' -Path 'C:\\Enterprise\\Bridge'
Demonstrates how to check that Jean-Luc Picard has `FullControl` permission on the `C:\\Enterprise\\Bridge`.
-------------------------- EXAMPLE 2 --------------------------
PS C:\\>Test-CPermission -Identity 'STARFLEET\\GLaForge' -Permission 'WriteKey' -Path
'HKLM:\\Software\\Enterprise\\Engineering'
Demonstrates how to check that Geordi LaForge can write registry keys at `HKLM:\\Software\\Enterprise\\Engineering`.
-------------------------- EXAMPLE 3 --------------------------
PS C:\\>Test-CPermission -Identity 'STARFLEET\\Worf' -Permission 'Write' -ApplyTo 'Container' -Path
'C:\\Enterprise\\Brig'
Demonstrates how to test for inheritance/propogation flags, in addition to permissions.
-------------------------- EXAMPLE 4 --------------------------
PS C:\\>Test-CPermission -Identity 'STARFLEET\\Data' -Permission 'GenericWrite' -Path
'cert:\\LocalMachine\\My\\1234567890ABCDEF1234567890ABCDEF12345678'
Demonstrates how to test for permissions on a certificate's private key/key container. If the certificate doesn't
have a private key, returns `$true`.
RELATED LINKS
Carbon_Permission
ConvertTo-CContainerInheritanceFlags
Disable-CAclInheritance
Enable-CAclInheritance
Get-CPermission
Grant-CPermission
Revoke-CPermission
http://msdn.microsoft.com/en-us/library ... ights.aspx
http://msdn.microsoft.com/en-us/library ... ights.aspx
http://msdn.microsoft.com/en-us/library ... ights.aspx