-
Notifications
You must be signed in to change notification settings - Fork 0
/
Grant-Permission.html
272 lines (230 loc) · 16.2 KB
/
Grant-Permission.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>PowerShell - Grant-Permission - Carbon</title>
<link href="silk.css" type="text/css" rel="stylesheet" />
<link href="styles.css" type="text/css" rel="stylesheet" />
</head>
<body>
<ul id="SiteNav">
<li><a href="index.html">Get-Carbon</a></li>
<li><a href="about_Carbon_Installation.html">-Install</a></li>
<li><a href="documentation.html">-Documentation</a></li>
<li><a href="about_Carbon_Support.html">-Support</a></li>
<li><a href="releasenotes.html">-ReleaseNotes</a></li>
<li><a href="http://pshdo.com">-Blog</a></li>
<li><a href="https://github.com/webmd-health-services/Carbon/">-Project</a></li>
</ul>
<h1>Grant-Permission</h1>
<div class="Synopsis">
<p>Grants permission on a file, directory, registry key, or certificate's private key/key container.</p>
</div>
<h2>Syntax</h2>
<pre class="Syntax"><code>Grant-Permission [-Path] <String> [-Identity] <String> [-Permission] <String[]> [[-ApplyTo] {Container | SubContainers | ContainerAndSubContainers | Leaves | ContainerAndLeaves | SubContainersAndLeaves | ContainerAndSubContainersAndLeaves | ChildContainers | ContainerAndChildContainers | ChildLeaves | ContainerAndChildLeaves | ChildContainersAndChildLeaves | ContainerAndChildContainersAndChildLeaves}] [[-Type] {Allow | Deny}] [-Clear] [-PassThru] [-Force] [-WhatIf] [-Confirm] [<CommonParameters>]</code></pre>
<h2>Description</h2>
<div class="Description">
<p>The <code>Grant-Permission</code> 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.</p>
<p>The <code>Permissions</code> attribute should be a list of <a href="http://msdn.microsoft.com/en-us/library/system.security.accesscontrol.filesystemrights.aspx">FileSystemRights</a>, <a href="http://msdn.microsoft.com/en-us/library/system.security.accesscontrol.registryrights.aspx">RegistryRights</a>, or <a href="http://msdn.microsoft.com/en-us/library/system.security.accesscontrol.cryptokeyrights.aspx">CryptoKeyRights</a>, for files/directories, registry keys, and certificate private keys, respectively. These commands will show you the values for the appropriate permissions for your object:</p>
<pre><code>[Enum]::GetValues([Security.AccessControl.FileSystemRights])
[Enum]::GetValues([Security.AccessControl.RegistryRights])
[Enum]::GetValues([Security.AccessControl.CryptoKeyRights])
</code></pre>
<p>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 <code>Force</code> switch. </p>
<p>Before Carbon 2.0, this function returned any new/updated access rules set on <code>Path</code>. In Carbon 2.0 and later, use the <code>PassThru</code> switch to get an access rule object back (you'll always get one regardless if the permissions changed or not).</p>
<p>By default, permissions allowing access are granted. Beginning in Carbon 2.3.0, you can grant permissions denying access by passing <code>Deny</code> as the value of the <code>Type</code> parameter.</p>
<h2>Directories and Registry Keys</h2>
<p>When setting permissions on a container (directory/registry key) you can control inheritance and propagation flags using the <code>ApplyTo</code> parameter. This parameter is designed to hide the complexities of the Windows' inheritance and propagation flags. There are 13 possible combinations.</p>
<p>Given this tree</p>
<pre><code> C
/ \
CC CL
/ \
GC GL
</code></pre>
<p>where</p>
<ul>
<li>C is the <strong>C</strong>ontainer permissions are getting set on </li>
<li>CC is a <strong>C</strong>hild <strong>C</strong>ontainer </li>
<li>CL is a <strong>C</strong>hild <strong>L</strong>eaf </li>
<li>GC is a <strong>G</strong>randchild <strong>C</strong>ontainer and includes all sub-containers below it </li>
<li>GL is a <strong>G</strong>randchild <strong>L</strong>eaf </li>
</ul>
<p>The <code>ApplyTo</code> parameter takes one of the following 13 values and applies permissions to:</p>
<ul>
<li><strong>Container</strong> - The container itself and nothing below it.</li>
<li><strong>SubContainers</strong> - All sub-containers under the container, e.g. CC and GC. </li>
<li><strong>Leaves</strong> - All leaves under the container, e.g. CL and GL.</li>
<li><strong>ChildContainers</strong> - Just the container's child containers, e.g. CC.</li>
<li><strong>ChildLeaves</strong> - Just the container's child leaves, e.g. CL.</li>
<li><strong>ContainerAndSubContainers</strong> - The container and all its sub-containers, e.g. C, CC, and GC.</li>
<li><strong>ContainerAndLeaves</strong> - The container and all leaves under it, e.g. C and CL.</li>
<li><strong>SubContainerAndLeaves</strong> - All sub-containers and leaves, but not the container itself, e.g. CC, CL, GC, and GL.</li>
<li><strong>ContainerAndChildContainers</strong> - The container and all just its child containers, e.g. C and CC.</li>
<li><strong>ContainerAndChildLeaves</strong> - The container and just its child leaves, e.g. C and CL.</li>
<li><strong>ContainerAndChildContainersAndChildLeaves</strong> - The container and just its child containers/leaves, e.g. C, CC, and CL.</li>
<li><strong>ContainerAndSubContainersAndLeaves</strong> - Everything, full inheritance/propogation, e.g. C, CC, GC, GL. <strong>This is the default.</strong></li>
<li><strong>ChildContainersAndChildLeaves</strong> - Just the container's child containers/leaves, e.g. CC and CL.</li>
</ul>
<p>The following table maps <code>ContainerInheritanceFlags</code> values to the actual <code>InheritanceFlags</code> and <code>PropagationFlags</code> values used:</p>
<pre><code>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
</code></pre>
<p>The above information adapated from <a href="http://msdn.microsoft.com/en-us/magazine/cc163885.aspx#S3">Manage Access to Windows Objects with ACLs and the .NET Framework</a>, published in the November 2004 copy of <em>MSDN Magazine</em>.</p>
<p>If you prefer to speak in <code>InheritanceFlags</code> or <code>PropagationFlags</code>, you can use the <code>ConvertTo-ContainerInheritaceFlags</code> function to convert your flags into Carbon's flags.</p>
<h2>Certificate Private Keys/Key Containers</h2>
<p>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 <code>ApplyTo</code> parameter is ignored.</p>
<p>When using the <code>-Clear</code> switch, note that the local <code>Administrators</code> account will always remain. In testing on Windows 2012 R2, we noticed that when <code>Administrators</code> access was removed, you couldn't read the key anymore.</p>
</div>
<h2>Related Commands</h2>
<ul class="RelatedCommands">
<li>Carbon_Permission</li>
<li><a href="ConvertTo-ContainerInheritanceFlags.html">ConvertTo-ContainerInheritanceFlags</a></li>
<li><a href="Disable-AclInheritance.html">Disable-AclInheritance</a></li>
<li><a href="Enable-AclInheritance.html">Enable-AclInheritance</a></li>
<li><a href="Get-Permission.html">Get-Permission</a></li>
<li><a href="Revoke-Permission.html">Revoke-Permission</a></li>
<li><a href="Test-Permission.html">Test-Permission</a></li>
<li><a href="http://msdn.microsoft.com/en-us/library/system.security.accesscontrol.filesystemrights.aspx">http://msdn.microsoft.com/en-us/library/system.security.accesscontrol.filesystemrights.aspx</a></li>
<li><a href="http://msdn.microsoft.com/en-us/library/system.security.accesscontrol.registryrights.aspx">http://msdn.microsoft.com/en-us/library/system.security.accesscontrol.registryrights.aspx</a></li>
<li><a href="http://msdn.microsoft.com/en-us/library/system.security.accesscontrol.cryptokeyrights.aspx">http://msdn.microsoft.com/en-us/library/system.security.accesscontrol.cryptokeyrights.aspx</a></li>
<li><a href="http://msdn.microsoft.com/en-us/magazine/cc163885.aspx#S3">http://msdn.microsoft.com/en-us/magazine/cc163885.aspx#S3</a></li>
</ul>
<h2> Parameters </h2>
<table id="Parameters">
<tr>
<th>Name</th>
<th>Type</th>
<th>Description</th>
<th>Required?</th>
<th>Pipeline Input</th>
<th>Default Value</th>
</tr>
<tr valign='top'>
<td>Path</td>
<td><a href="http://msdn.microsoft.com/en-us/library/system.string.aspx">String</a></td>
<td class="ParamDescription"><p>The path on which the permissions should be granted. Can be a file system, registry, or certificate path.</p></td>
<td>true</td>
<td>false</td>
<td></td>
</tr>
<tr valign='top'>
<td>Identity</td>
<td><a href="http://msdn.microsoft.com/en-us/library/system.string.aspx">String</a></td>
<td class="ParamDescription"><p>The user or group getting the permissions.</p></td>
<td>true</td>
<td>false</td>
<td></td>
</tr>
<tr valign='top'>
<td>Permission</td>
<td><a href="http://msdn.microsoft.com/en-us/library/system.string.aspx">String[]</a></td>
<td class="ParamDescription"><p>The permission: e.g. FullControl, Read, etc. For file system items, use values from <a href="http://msdn.microsoft.com/en-us/library/system.security.accesscontrol.filesystemrights.aspx">System.Security.AccessControl.FileSystemRights</a>. For registry items, use values from <a href="http://msdn.microsoft.com/en-us/library/system.security.accesscontrol.registryrights.aspx">System.Security.AccessControl.RegistryRights</a>.</p></td>
<td>true</td>
<td>false</td>
<td></td>
</tr>
<tr valign='top'>
<td>ApplyTo</td>
<td>ContainerInheritanceFlags</td>
<td class="ParamDescription"><p>How to apply container permissions. This controls the inheritance and propagation flags. Default is full inheritance, e.g. <code>ContainersAndSubContainersAndLeaves</code>. This parameter is ignored if <code>Path</code> is to a leaf item.</p></td>
<td>false</td>
<td>false</td>
<td>ContainerAndSubContainersAndLeaves</td>
</tr>
<tr valign='top'>
<td>Type</td>
<td><a href="http://msdn.microsoft.com/en-us/library/system.security.accesscontrol.accesscontroltype.aspx">AccessControlType</a></td>
<td class="ParamDescription"><p>The type of rule to apply, either <code>Allow</code> or <code>Deny</code>. The default is <code>Allow</code>, which will allow access to the item. The other option is <code>Deny</code>, which will deny access to the item.</p>
<p>This parameter was added in Carbon 2.3.0.</p></td>
<td>false</td>
<td>false</td>
<td>Allow</td>
</tr>
<tr valign='top'>
<td>Clear</td>
<td><a href="http://msdn.microsoft.com/en-us/library/system.management.automation.switchparameter.aspx">SwitchParameter</a></td>
<td class="ParamDescription"><p>Removes all non-inherited permissions on the item.</p></td>
<td>false</td>
<td>false</td>
<td>False</td>
</tr>
<tr valign='top'>
<td>PassThru</td>
<td><a href="http://msdn.microsoft.com/en-us/library/system.management.automation.switchparameter.aspx">SwitchParameter</a></td>
<td class="ParamDescription"><p>Returns an object representing the permission created or set on the <code>Path</code>. The returned object will have a <code>Path</code> propery added to it so it can be piped to any cmdlet that uses a path. </p>
<p>The <code>PassThru</code> switch is new in Carbon 2.0.</p></td>
<td>false</td>
<td>false</td>
<td>False</td>
</tr>
<tr valign='top'>
<td>Force</td>
<td><a href="http://msdn.microsoft.com/en-us/library/system.management.automation.switchparameter.aspx">SwitchParameter</a></td>
<td class="ParamDescription"><p>Grants permissions, even if they are already present.</p></td>
<td>false</td>
<td>false</td>
<td>False</td>
</tr>
<tr valign='top'>
<td>WhatIf</td>
<td><a href="http://msdn.microsoft.com/en-us/library/system.management.automation.switchparameter.aspx">SwitchParameter</a></td>
<td class="ParamDescription"></td>
<td>false</td>
<td>false</td>
<td></td>
</tr>
<tr valign='top'>
<td>Confirm</td>
<td><a href="http://msdn.microsoft.com/en-us/library/system.management.automation.switchparameter.aspx">SwitchParameter</a></td>
<td class="ParamDescription"></td>
<td>false</td>
<td>false</td>
<td></td>
</tr>
<tr valign="top">
<td><a href="http://technet.microsoft.com/en-us/library/dd315352.aspx">CommonParameters</a></td>
<td></td>
<td>This cmdlet supports common parameters. For more information type <br> <code>Get-Help about_CommonParameters</code>.</td>
<td></td>
<td></td>
<td></td>
</tr>
</table>
<h2>Return Values</h2>
<div class="ReturnValues">
<p><a href="http://msdn.microsoft.com/en-us/library/system.security.accesscontrol.accessrule.aspx">System.Security.AccessControl.AccessRule</a>. When setting permissions on a file or directory, a <code>System.Security.AccessControl.FileSystemAccessRule</code> is returned. When setting permissions on a registry key, a <code>System.Security.AccessControl.RegistryAccessRule</code> returned. When setting permissions on a private key, a <code>System.Security.AccessControl.CryptoKeyAccessRule</code> object is returned.</p>
</div>
<h2>EXAMPLE 1</h2>
<pre><code>Grant-Permission -Identity ENTERPRISE\Engineers -Permission FullControl -Path C:\EngineRoom</code></pre>
<p>Grants the Enterprise's engineering group full control on the engine room. Very important if you want to get anywhere.</p>
<h2>EXAMPLE 2</h2>
<pre><code>Grant-Permission -Identity ENTERPRISE\Interns -Permission ReadKey,QueryValues,EnumerateSubKeys -Path rklm:\system\WarpDrive</code></pre>
<p>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.</p>
<h2>EXAMPLE 3</h2>
<pre><code>Grant-Permission -Identity ENTERPRISE\Engineers -Permission FullControl -Path C:\EngineRoom -Clear</code></pre>
<p>Grants the Enterprise's engineering group full control on the engine room. Any non-inherited, existing access rules are removed from <code>C:\EngineRoom</code>.</p>
<h2>EXAMPLE 4</h2>
<pre><code>Grant-Permission -Identity ENTERPRISE\Engineers -Permission FullControl -Path 'cert:\LocalMachine\My\1234567890ABCDEF1234567890ABCDEF12345678'</code></pre>
<p>Grants the Enterprise's engineering group full control on the <code>1234567890ABCDEF1234567890ABCDEF12345678</code> certificate's private key/key container.</p>
<h2>EXAMPLE 5</h2>
<pre><code>Grant-Permission -Identity BORG\Locutus -Permission FullControl -Path 'C:\EngineRoom' -Type Deny</code></pre>
<p>Demonstrates how to grant deny permissions on an objecy with the <code>Type</code> parameter.</p>
<div class="Footer">
Copyright 2012 - 2018 <a href="http://pshdo.com">Aaron Jensen</a>.
</div>
</body>
</html>