GPRegistryPolicy.psm1

###########################################################
#
#  Group Policy - Registry Policy module
#
#  Copyright (c) Microsoft Corporation, 2016
#
###########################################################

data LocalizedData
{
    # culture="en-US"
    ConvertFrom-StringData @'
    InvalidHeader = File '{0}' has an invalid header.
    InvalidVersion = File '{0}' has an invalid version. It should be 1.
    InvalidFormatBracket = File '{0}' has an invalid format. A [ or ] was expected at location {1}.
    InvalidFormatSemicolon = File '{0}' has an invalid format. A ; was expected at location {1}.
    OnlyCreatingKey = Some values are null. Only the registry key is created.
    Progress = Progress: {0,8:p}
    InvalidPath = Path {0} doesn't point to an existing registry key/property.
    InternalError = Internal error while creating a registry entry for {0}
'@
}

Import-LocalizedData  LocalizedData -filename GPRegistryPolicy.Strings.psd1
Import-Module "$PSScriptRoot\GPRegistryPolicyParser.psm1" -DisableNameChecking

$script:SystemAndAdminAccounts = @(
    'NT AUTHORITY\SYSTEM',
    'BUILTIN\Administrators'
)

$script:WellKnownSids = @(
    'APPLICATION PACKAGE AUTHORITY\ALL APPLICATION PACKAGES'
)

$script:DefaultEntries = @(
    "Software\Policies"
)

<# 
.SYNOPSIS
Applies a registry policy.

.DESCRIPTION
Applies a registry policy. The division to which the contents must be applied has to be defined
as one of the three available values: LocalMachine, CurrentUser, and Users.

.PARAMETER RegistryPolicy
Specifies the registry policy that has to be applied: Key, Value, Type, Size and Data

.PARAMETER Division
The destination registry division to which the policy has to be applied.

.PARAMETER KeyPrefix
A prefix that will be prepended to the given key.

.PARAMETER SID
The SID that defines which key in Users division is going to be used.
#>
function Apply-GPRegistryPolicy
{
    [OutputType([array])]
    param (
		[Parameter(Mandatory = $true)]
        [GPRegistryPolicy]
        $RegistryPolicy,

        [ValidateSet("LocalMachine", "CurrentUser", "Users")]
        [string]
        $Division = "LocalMachine",

        [string]
        [ValidateNotNullOrEmpty()]
        $KeyPrefix,

        [string]
        [ValidateNotNullOrEmpty()]
        $SID
    )

    switch ($Division) 
    { 
        'LocalMachine' { $Hive = [Microsoft.Win32.Registry]::LocalMachine } 
        'CurrentUser'  { $Hive = [Microsoft.Win32.Registry]::CurrentUser } 
        'Users'        { $Hive = [Microsoft.Win32.Registry]::Users } 
    }

    $targetKeyName = $RegistryPolicy.KeyName

    # if we have a prefix, prepend that to the key name
    if ($PSBoundParameters.ContainsKey('KeyPrefix'))
    {
        $targetKeyName = $KeyPrefix + '\' + $targetKeyName
    }

    # if we have a SID in Users division, prepend that to the key name
    if (($Division -ieq "Users") -and ($PSBoundParameters.ContainsKey('SID')))
    {
        $targetKeyName = $SID + '\' + $targetKeyName
    }

    try
    {
        # Create a new subkey or open an existing subkey for write access
        $key = $Hive.CreateSubKey($targetKeyName)

        # If value, type, size, or data are missing or zero, only the registry key is created.
        $keyOnly = ([System.String]::IsNullOrEmpty($RegistryPolicy.ValueName)) -or
                   ([System.String]::IsNullOrEmpty($RegistryPolicy.ValueType)) -or
                   ([System.String]::IsNullOrEmpty($RegistryPolicy.ValueLength)) -or
                   ([System.String]::IsNullOrEmpty($RegistryPolicy.ValueData))


        if ( $KeyOnly )
        {
            return
        }

        if ( $RegistryPolicy.ValueName -ieq "**DeleteValues" )
        {
            $ValueNames = ($RegistryPolicy.ValueData).Split(';')
            # TODO: Assert on type being REG_SZ
            Assert ($RegistryPolicy.ValueType -eq [RegType]::REG_SZ) "Failed"
            foreach($valueName in $ValueNames)
            {
                if (-not ([System.String]::IsNullOrEmpty($valueName)))
                {
                    try
                    {
                        $key.DeleteValue($valueName)
                    }
                    catch
                    {
                        # Do nothing
                    }
                }
            }
        }
        elseif ( ($RegistryPolicy.ValueName).StartsWith("**Del.") )
        {
            $ValueName = ($RegistryPolicy.ValueName).Substring( ($RegistryPolicy.ValueName).IndexOf('.')+1 )
            # TODO: Assert on type being REG_SZ
            # TODO: Assert on data being ' '
            $key.DeleteValue($valueName)
        }
        elseif ( $RegistryPolicy.ValueName -ieq "**DelVals." )
        {
            $ValueNames = $Key.GetValueNames()
            # TODO: Assert on type being REG_SZ
            # TODO: Assert on data being ' '
            foreach($valueName in $ValueNames)
            {
                $key.DeleteValue($valueName)
            }
        }
        elseif ( $RegistryPolicy.ValueName -ieq "**DeleteKeys" )
        {
            $SubKeys = ($RegistryPolicy.ValueData).Split(';')
            # TODO: Assert on type being REG_SZ
            foreach($subkey in $SubKeys)
            {
                if (-not ([System.String]::IsNullOrEmpty($subkey)))
                {
                    try
                    {
                        $key.DeleteSubKeyTree($subkey)
                    }
                    catch
                    {
                        # Do nothing
                    }
                }
            }
        }
        elseif ( $RegistryPolicy.ValueName -ieq "**SecureKey" )
        {
            $AccessLevel = [System.Int32] $RegistryPolicy.ValueData
            # TODO: Assert on type being REG_DWORD
            $AccessControl = $key.GetAccessControl()
            $AccessRules = $AccessControl.GetAccessRules($true,$true,[System.Security.Principal.NTAccount])

            foreach ($Access in $AccessRules)
            {
                if ($script:SystemAndAdminAccounts.Contains($Access.IdentityReference.ToString()))
                {
                    [System.Security.AccessControl.RegistryAccessRule] $NewAccessRule = [System.Security.AccessControl.RegistryAccessRule]::new(
                        $Access.IdentityReference,
                        [System.Security.AccessControl.RegistryRights]::FullControl,
                        $Access.InheritanceFlags,
                        $Access.PropagationFlags,
                        $Access.AccessControlType
                    )
                }
                elseif ($script:WellKnownSids.Contains($access.IdentityReference.ToString()))
                {
                    $strSID = $access.IdentityReference.ToString()
                    $groupName = $strSID.Substring($strSID.IndexOf('\')+1)
                    [System.Security.AccessControl.RegistryAccessRule] $NewAccessRule = [System.Security.AccessControl.RegistryAccessRule]::new(
                        $groupName,
                        [System.Security.AccessControl.RegistryRights]::ReadKey,
                        $access.InheritanceFlags,
                        $access.PropagationFlags,
                        $access.AccessControlType
                    )
                }
                else
                {
                    [System.Security.AccessControl.RegistryAccessRule] $NewAccessRule = [System.Security.AccessControl.RegistryAccessRule]::new(
                        $access.IdentityReference,
                        [System.Security.AccessControl.RegistryRights]::ReadKey,
                        $access.InheritanceFlags,
                        $access.PropagationFlags,
                        $access.AccessControlType
                    )
                }

                $AccessControl.RemoveAccessRule($Access)
                $AccessControl.SetAccessRule($NewAccessRule)
            }
        }   
        elseif ( ($RegistryPolicy.ValueName).StartsWith("**soft.") )
        {
            $CurrentValueNames = $Key.GetValueNames()
            $ValueName = ($RegistryPolicy.ValueName).Substring( ($RegistryPolicy.ValueName).IndexOf('.')+1 )
            if ( -not ($CurrentValueNames.Contains($ValueName)) )
            {
                $type = Get-RegType -Type $RegistryPolicy.ValueType
                $key.SetValue($RegistryPolicy.ValueName, $RegistryPolicy.ValueData, $type)
            }
        }
        else
        {
            # This is not a special value. So just update the value.
            if ($RegistryPolicy.ValueType -eq [RegType]::REG_MULTI_SZ)
            {
                [string[]] $data = ($RegistryPolicy.ValueData).Split("`0",[System.StringSplitOptions]::RemoveEmptyEntries)
            }
            elseif ($RegistryPolicy.ValueType -eq [RegType]::REG_MULTI_SZ)
            {
                [byte[]] $data = [System.Text.Encoding]::Unicode.GetBytes($RegistryPolicy.ValueData)
            }
            elseif ($RegistryPolicy.ValueType -eq [RegType]::REG_BINARY)
            {
                [byte[]] $data = $RegistryPolicy.ValueData
            }
            else
            {
                $data = $RegistryPolicy.ValueData
            }
        
            $key.SetValue($RegistryPolicy.ValueName, $data, $RegistryPolicy.ValueType)
        }
    }
    finally
    {
        if ($key)
        {
            if ($PSVersionTable.PSEdition -ieq 'Core')
            {
                $key.Flush()
                $key.Dispose()
            }
            else
            {
                $key.Close()
            }
        }
    }
}

<# 
.SYNOPSIS
Reads a .pol file containing group policy registry entries and applies its contents to the machine.

.DESCRIPTION
Reads a .pol file containing group policy registry entries and applies its contents to the machine.
The division to which the contents must be applied to has to be defined using one of the three available
options for **LocalMachine**, **CurrentUser**, or **Username**.

.PARAMETER Path
Specifies the path to the .pol file to be imported.

.PARAMETER LocalMachine
A switch that sets the Local Machine as the destination registry division.

.PARAMETER CurrentUser
A switch that sets the Current User as the destination registry division.

.PARAMETER Username
A string that selects the target user in the Users registry division.

.PARAMETER KeyPrefix
A prefix that will be prepended to the given key.

.EXAMPLE
C:\PS> Import-GPRegistryPolicy -Path "C:\Registry.pol" -LocalMachine

.EXAMPLE
C:\PS> Import-GPRegistryPolicy -Path "C:\Registry.pol" -CurrentUser

.EXAMPLE
C:\PS> Import-GPRegistryPolicy -Path "C:\Registry.pol" -Username testdomain\testuser

.EXAMPLE
C:\PS> Import-GPRegistryPolicy -Path "C:\Registry.pol" -Username localtestuser

.EXAMPLE
C:\PS> Import-GPRegistryPolicy -Path "C:\Registry.pol" -LocalMachine -KeyPrefix 'Software\TestKeys'

.OUTPUT
None.
#>
function Import-GPRegistryPolicy
{
    [CmdletBinding(DefaultParameterSetName='LocalMachine')]
    param (
		[Parameter(Mandatory = $true,Position=0)]
        [ValidateNotNullOrEmpty()]
        [string]
        $Path,

		[Parameter(ParameterSetName = 'LocalMachine')]
        [switch]
        $LocalMachine = $true,

		[Parameter(ParameterSetName = 'CurrentUser')]
        [switch]
        $CurrentUser = $false,

		[Parameter(ParameterSetName = 'Users')]
        [ValidateNotNullOrEmpty()]
        [string]
        $Username = "$($env:USERDOMAIN)\$($env:USERNAME)",

        [string]
        [ValidateNotNullOrEmpty()]
        $KeyPrefix
    )

    $Parameters = @{}

    switch ($PsCmdlet.ParameterSetName) 
    { 
        'LocalMachine' 
        { 
            $Parameters.Add('Division', 'LocalMachine')
        } 

        'CurrentUser'
        {
            $Parameters.Add('Division', 'CurrentUser')
        } 
        
        'Users'  {
            $Parameters.Add('Division', 'Users')

            # Translate the username into SID
            $objUser = New-Object System.Security.Principal.NTAccount($Username)
            $strSID = $objUser.Translate([System.Security.Principal.SecurityIdentifier])
            $Parameters.Add('SID', $strSID.Value)
        } 
    }

    if ($PSBoundParameters.ContainsKey('KeyPrefix'))
    {
        $Parameters.Add('KeyPrefix', $KeyPrefix)
    }

    $RegistryPolicies = Parse-PolFile -Path $Path

    foreach ($rp in $RegistryPolicies)
    {
        if ($rp -ne $null)
        {
            Apply-GPRegistryPolicy -RegistryPolicy $rp @Parameters
        }
    }
}

<# 
.SYNOPSIS
Reads registry entries and write them in a .pol file.

.DESCRIPTION
Reads registry entries and write them in a .pol file. By default, the root key from which the registry
entries are read is 'Software\Policies'. However, if Entries are assinged in input, then this function
will export those instead. The division from which the contents must be read has to be defined using one
of the three available options for **LocalMachine**, **CurrentUser**, or **Username**.

.PARAMETER Path
Specifies the path to the destination .pol file.

.PARAMETER LocalMachine
A switch that sets the Local Machine as the source registry division.

.PARAMETER CurrentUser
A switch that sets the Current User as the source registry division.

.PARAMETER Username
A string that selects the target user in the Users registry division.

.PARAMTER Entries
Specifies the list of registry keys to be exported. The default value is set to 'Software\Policies'.

.PARAMETER Username
A string that selects the target user in the Users registry division.

.EXAMPLE
C:\PS> Export-GPRegistryPolicy -Path "C:\Registry.pol" -LocalMachine

.EXAMPLE
C:\PS> Export-GPRegistryPolicy -Path "C:\Registry.pol" -CurrentUser

.EXAMPLE
C:\PS> Export-GPRegistryPolicy -Path "C:\Registry.pol" -Username testdomain\testuser

.EXAMPLE
C:\PS> Export-GPRegistryPolicy -Path "C:\Registry.pol" -Username localtestuser

.EXAMPLE
C:\PS> Export-GPRegistryPolicy -Path "C:\Registry.pol" -LocalMachine -Entries @('Software\Policies\Microsoft\Windows', 'Software\Policies\Microsoft\WindowsFirewall')

.INPUTS
None. You cannot pipe objects to Import-GPRegistryPolicy.

.OUTPUT
None.
#>
function Export-GPRegistryPolicy
{
    [CmdletBinding(DefaultParameterSetName='LocalMachine')]
    param (
		[Parameter(Mandatory = $true,Position=0)]
        [ValidateNotNullOrEmpty()]
        [string]
        $Path,
        
		[Parameter(Position=1)]
        [string[]]
        $Entries = $script:DefaultEntries,

		[Parameter(Mandatory = $true, ParameterSetName = 'LocalMachine')]
        [switch]
        $LocalMachine = $true,

		[Parameter(Mandatory = $true, ParameterSetName = 'CurrentUser')]
        [switch]
        $CurrentUser = $false,

		[Parameter(ParameterSetName = 'Users')]
        [ValidateNotNullOrEmpty()]
        [string]
        $Username = "$($env:USERDOMAIN)\$($env:USERNAME)"
    )

    switch ($PsCmdlet.ParameterSetName) 
    { 
        'LocalMachine' 
        { 
            $Division = 'LocalMachine'
        } 

        'CurrentUser'
        {
            $Division = 'CurrentUser'
        } 
        
        'Users'  {
            $Division = 'Users'

            # Translate the username into SID
            $objUser = New-Object System.Security.Principal.NTAccount($Username)
            $strSID = $objUser.Translate([System.Security.Principal.SecurityIdentifier])
            $SID = $strSID.Value

            # Modify the entries and prepend the SID of the selected user to all of them.
            $Entries = $Entries | % { $SID+'\'+$_ }
        } 
    }

    $RegistryPolicies = Read-RegistryPolicies -Entries $Entries -Division $Division
    
    Create-GPRegistryPolicyFile -Path $Path

    Append-RegistryPolicies -RegistryPolicies $RegistryPolicies -Path $Path
}



<# 
.SYNOPSIS
Reads a .pol file containing group policy registry entries and tests its contents against current registry.

.DESCRIPTION
Reads a .pol file containing group policy registry entries and tests its contents against current registry.
The division to which the contents must be applied has to be defined using one of the three available options 
for **LocalMachine**, **CurrentUser**, or **Username**.

.PARAMETER Path
Specifies the path to the .pol file to be tested.

.PARAMETER LocalMachine
A switch that sets the Local Machine as the destination registry division.

.PARAMETER CurrentUser
A switch that sets the Current User as the destination registry division.

.PARAMETER Username
A string that selects the target user in the Users registry division.

.PARAMTER Entries
Specifies the list of registry keys to be exported. The default value is set to 'Software\Policies'.

.EXAMPLE
C:\PS> Test-GPRegistryPolicy -Path "C:\Registry.pol" -LocalMachine

.EXAMPLE
C:\PS> Test-GPRegistryPolicy -Path "C:\Registry.pol" -CurrentUser

.EXAMPLE
C:\PS> Test-GPRegistryPolicy -Path "C:\Registry.pol" -Username testdomain\testuser

.EXAMPLE
C:\PS> Test-GPRegistryPolicy -Path "C:\Registry.pol" -Username localtestuser

.EXAMPLE
C:\PS> Test-GPRegistryPolicy -Path "C:\Registry.pol" -LocalMachine -Entries @('Software\Policies\Microsoft\Windows', 'Software\Policies\Microsoft\WindowsFirewall')

.INPUTS
None. You cannot pipe objects to Test-GPRegistryPolicy.

.OUTPUT
None.
#>
function Test-GPRegistryPolicy
{
    [CmdletBinding(DefaultParameterSetName='LocalMachine')]
    param (
		[Parameter(Mandatory = $true,Position=0)]
        [ValidateNotNullOrEmpty()]
        [string]
        $Path,
        
		[Parameter(Position=1)]
        [string[]]
        $Entries = $script:DefaultEntries,

		[Parameter(ParameterSetName = 'LocalMachine')]
        [switch]
        $LocalMachine = $true,

		[Parameter(ParameterSetName = 'CurrentUser')]
        [switch]
        $CurrentUser = $false,

		[Parameter(ParameterSetName = 'Users')]
        [ValidateNotNullOrEmpty()]
        [string]
        $Username = "$($env:USERDOMAIN)\$($env:USERNAME)"
    )

    $Parameters = @{}

    switch ($PsCmdlet.ParameterSetName) 
    { 
        'LocalMachine'  { 
            $Parameters.Add('LocalMachine', $true)
            $Hive = [Microsoft.Win32.Registry]::LocalMachine
        }
        'CurrentUser'  { 
            $Parameters.Add('CurrentUser', $true)
            $Hive = [Microsoft.Win32.Registry]::CurrentUser
        } 
        'Users'  { 
            $Parameters.Add('Username', $Username)
            $Hive = [Microsoft.Win32.Registry]::Users
        } 
    }

    $tempID = New-Guid
    $tempFile = Join-Path -Path $env:TEMP -ChildPath "$tempID.pol"
    $tempFileActual = Join-Path -Path $env:TEMP -ChildPath "$tempID.actual.pol"
    $tempFileExpected = Join-Path -Path $env:TEMP -ChildPath "$tempID.expected.pol"
    $tempRegKey = "Software\$tempID"
    
    # Export the target registry entries into a temp file
    Export-GPRegistryPolicy -Path $tempFile -Entries $Entries @Parameters -ErrorAction SilentlyContinue

    # Import the target registry entries into a temp location on registry
    Import-GPRegistryPolicy -Path $tempFile -KeyPrefix $tempRegKey @Parameters

    # Export the the temp registry key into a file to get actual settings
    Export-GPRegistryPolicy -Path $tempFileActual -Entries @($tempRegKey) @Parameters -ErrorAction SilentlyContinue

    # Import and apply the target .pol file into the temp location on registry
    Import-GPRegistryPolicy -Path $Path -KeyPrefix $tempRegKey @Parameters

    # Export the the temp registry key into a file to get expected settings
    Export-GPRegistryPolicy -Path $tempFileExpected -Entries @($tempRegKey) @Parameters
    
    $ActualRP = Parse-PolFile -Path $tempFileActual
    $ExpectedRP = Parse-PolFile -Path $tempFileExpected
    
    $ActualRPInJSON = ConvertTo-Json -InputObject $ActualRP
    $ExpectedRPInJSON = ConvertTo-Json -InputObject $ExpectedRP
    

    if (($ActualRPInJSON -ne $null) -and ($ExpectedRPInJSON -ne $null))
    {
        $DiffResults = Compare-Object `
            -ReferenceObject ($ActualRPInJSON) `
            -DifferenceObject ($ExpectedRPInJSON)
    }
    else
    {
        $DiffResults = 'FAILED' # Anything but a null value for $DiffResults indicates a failure.
    }

    # Clean up
    Remove-Item -Path $tempFile -Force -ErrorAction SilentlyContinue
    Remove-Item -Path $tempFileActual -Force -ErrorAction SilentlyContinue
    Remove-Item -Path $tempFileExpected -Force -ErrorAction SilentlyContinue
    $Hive.DeleteSubKeyTree($tempRegKey)

    return ([string]::IsNullOrEmpty($DiffResults))    
}

Function Get-AllKeys
{
    [OutputType([Array])]
    param (
        [Parameter(Mandatory)]
        [System.Object[]]
        $RegistryPolicies
    )

    $Result = @()

    foreach( $RP in $RegistryPolicies)
    {
        if (-not $Result.Contains($RP.keyName))
        {
            $Result += ,$RP.keyName
        }
    }

    return $Result
}

Function Assert
{
    param (
        [Parameter(Mandatory)]
        $Condition,

        [Parameter(Mandatory)]
        [ValidateNotNullOrEmpty()]
        [string]
        $ErrorMessage
    )

    if (!$Condition) 
    {
        throw $ErrorMessage;
    }
}

#Export-ModuleMember -Function 'Import-GPRegistryPolicy','Export-GPRegistryPolicy','Test-GPRegistryPolicy'
#Export-ModuleMember -Function 'Parse-PolFile','Read-RegistryPolicies','Create-RegistrySettingsEntry','Create-GPRegistryPolicyFile','Append-RegistryPolicies'
Export-ModuleMember -Function 'Import-GPRegistryPolicy','Export-GPRegistryPolicy','Test-GPRegistryPolicy','Parse-PolFile','Read-RegistryPolicies','Create-RegistrySettingsEntry','Create-GPRegistryPolicyFile','Append-RegistryPolicies'