Merge pull request #3 from webmd-health-services/feature/remove-certi…

…ficate-functionality

Removing private key functionality as it has been migrated to Carbon.Cryptography

CHANGELOG.md

@@ -4,7 +4,37 @@
 
 ### Upgrade Instructions
 
-Replaces usages of the `Grant-CPermission` and `Test-CPermission` functions' `ApplyTo` parameter with new parameter
+This is not the upgrade path you want, if switching from Carbon. The `Get-CPermission`, `Grant-CPermission`,
+`Revoke-CPermission`, and `Test-CPermission` functions were migrated to the following modules with the following
+function names.
+
+`Carbon.FileSystem`:
+
+* `Get-CNtfsPermission`
+* `Grant-CNtfsPermission`
+* `Revoke-CNtfsPermission`
+* `Test-CNtfsPermission`
+
+`Carbon.Registry`:
+
+* `Get-CRegistryPermission`
+* `Grant-CRegistryPermission`
+* `Revoke-CRegistryPermission`
+* `Test-CRegistryPermission`:
+
+`Carbon.Cryptography`:
+
+* `Get-CPrivateKey`
+* `Get-CPrivateKeyPermission`
+* `Grant-CPrivateKeyPermission`
+* `Resolve-CPrivateKeyPath`
+* `Revoke-CPrivateKeyPermission`
+* `Test-CPrivateKeyPath`
+
+You *must* switch to `Carbon.Cryptography` if managing permissions on private keys/key containers. `Carbon.Permissions`
+only manages permissions on files, directories, and registry keys.
+
+Replace usages of the `Grant-CPermission` and `Test-CPermission` functions' `ApplyTo` parameter with new parameter
 values and a new `OnlyApplyToChildren` switch:
 
 | Old Parameters                                     | New Parameters
@@ -44,7 +74,9 @@ Supports getting only specific sections/parts of the security descriptor, too.
 
 ### Removed
 
-* The `ApplyTo` function on `Grant-CPermission` and `Test-CPermission`. Use the new `InheritanceFlag` and
-`PropagationFlag` parameters to set a permission's inheritance and propagation flags.
 * Alias `Get-Permissions`. Use `Get-CPermission` instead.
 * Alias `Grant-Permissions`. Use `Grant-CPermission` instead.
+* Private key/key container support from `Get-CPermission`, `Grant-CPermission`, `Revoke-CPermission`, and
+`Test-CPermission`. Switch to the `Carbon.Cryptography` module's `Get-CPrivateKey`, `Get-CPrivateKeyPermission`,
+`Grant-CPrivateKeyPermission`, `Resolve-CPrivateKeyPath`, `Revoke-CPrivateKeyPermission`, and `Test-CPrivateKeyPath`
+instead.

Carbon.Permissions/Functions/Get-CAcl.ps1

@@ -55,7 +55,7 @@ function Get-CAcl
         if ($InputObject -isnot [FileSystemInfo])
         {
             $msg = "Failed to get ACL for ""${InputObject}"" because it doesn't have a ""GetAccessControl"" member " +
-                   "and is not a FileInfo or DirectoryInfo object."
+                   "and is a [$($InputObject.GetType().FullName)] object and not a FileInfo or DirectoryInfo object."
             Write-Error -Message $msg -ErrorAction $ErrorActionPreference
             return
         }

Carbon.Permissions/Functions/Get-CPermission.ps1

@@ -3,12 +3,11 @@ function Get-CPermission
 {
     <#
     .SYNOPSIS
-    Gets the permissions (access control rules) for a file, directory, registry key, or certificate private key/key
-    container.
+    Gets the permissions (access control rules) for a file, directory, or registry key.
 
     .DESCRIPTION
-    The `Get-CPermission` function gets the permissions, as access control rule objects, for a file, directory, registry
-    key, or a certificate private key/key container. Using this function and module are not recommended. Instead,
+    The `Get-CPermission` function gets the permissions, as access control rule objects, for a file, directory, or
+    registry key. Using this function and module are not recommended. Instead,
 
     * for file directory permissions, use `Get-CNtfsPermission` in the `Carbon.FileSystem` module.
     * for registry permissions, use `Get-CRegistryPermission` in the `Carbon.Registry` module.
@@ -18,10 +17,7 @@ function Get-CPermission
     Pass the path to the `Path` parameter. By default, all non-inherited permissions on that item are returned. To
     return inherited permissions, use the `Inherited` switch.
 
-    To return the permissions for a specific identity, pass the identity's name to the `Identity` parameter.
-
-    Certificate permissions are only returned if a certificate has a private key/key container. If a certificate doesn't
-    have a private key, `$null` is returned.
+    To return the permissions for a specific user or group, pass the account's name to the `Identity` parameter.
 
     .OUTPUTS
     System.Security.AccessControl.AccessRule.
@@ -55,23 +51,16 @@ function Get-CPermission
 
     Returns `System.Security.AccessControl.FileSystemAccessRule` objects for all the `Administrators'` rules on
     `C:\windows`.
-
-    .EXAMPLE
-    Get-CPermission -Path 'Cert:\LocalMachine\1234567890ABCDEF1234567890ABCDEF12345678'
-
-    Returns `System.Security.AccessControl.CryptoKeyAccesRule` objects for certificate's
-    `Cert:\LocalMachine\1234567890ABCDEF1234567890ABCDEF12345678` private key/key container. If it doesn't have a
-    private key, `$null` is returned.
     #>
     [CmdletBinding()]
     [OutputType([System.Security.AccessControl.AccessRule])]
     param(
-        # The path whose permissions (i.e. access control rules) to return. File system, registry, or certificate paths
-        # supported. Wildcards supported. For certificate private keys, pass a certificate provider path, e.g. `cert:`.
+        # The path whose permissions (i.e. access control rules) to return. File system or registry paths supported.
+        # Wildcards supported.
         [Parameter(Mandatory)]
         [String] $Path,
 
-        # The identity whose permissiosn (i.e. access control rules) to return.
+        # The user/group name whose permissiosn (i.e. access control rules) to return.
         [String] $Identity,
 
         # Return inherited permissions in addition to explicit permissions.
@@ -81,57 +70,26 @@ function Get-CPermission
     Set-StrictMode -Version 'Latest'
     Use-CallerPreference -Cmdlet $PSCmdlet -Session $ExecutionContext.SessionState
 
-    $account = $null
-    if( $Identity )
+    $rArgs = Resolve-Arg -Path $Path -Identity $Identity -Action 'get'
+    if (-not $rArgs)
     {
-        $account = Test-CIdentity -Name $Identity -PassThru
-        if( $account )
-        {
-            $Identity = $account.FullName
-        }
-    }
-
-    if( -not (Test-Path -Path $Path) )
-    {
-        Write-Error ('Path ''{0}'' not found.' -f $Path)
         return
     }
 
-    & {
-            foreach ($item in (Get-Item -Path $Path -Force))
-            {
-                if( $item.PSProvider.Name -ne 'Certificate' )
-                {
-                    $item | Get-CAcl -IncludeSection ([AccessControlSections]::Access) | Write-Output
-                    continue
-                }
-
-                if (-not $item.HasPrivateKey)
-                {
-                    continue
-                }
-
-                if ($item.PrivateKey -and ($item.PrivateKey | Get-Member 'CspKeyContainerInfo'))
-                {
-                    $item.PrivateKey.CspKeyContainerInfo.CryptoKeySecurity | Write-Output
-                    continue
-                }
-
-                $item | Resolve-CPrivateKeyPath | Get-Acl | Write-Output
-            }
-        } |
+    Get-Item -Path $Path -Force |
+        Get-CAcl -IncludeSection ([AccessControlSections]::Access) |
         Select-Object -ExpandProperty 'Access' |
         Where-Object {
-            if( $Inherited )
+            if ($Inherited)
             {
                 return $true
             }
             return (-not $_.IsInherited)
         } |
         Where-Object {
-            if( $Identity )
+            if ($Identity)
             {
-                return ($_.IdentityReference.Value -eq $Identity)
+                return ($_.IdentityReference.Value -eq $rArgs.AccountName)
             }
 
             return $true