Invoke-Win32Api.ps1

# Copyright: (c) 2018, Jordan Borean (@jborean93) <jborean93@gmail.com>
# MIT License (see LICENSE or https://opensource.org/licenses/MIT)


Function Invoke-Win32Api {
    <#
    .SYNOPSIS
    Call a native Win32 API or a function exported in a DLL.

    .DESCRIPTION
    This method allows you to call a native Win32 API or DLL function
    without compiling C# code using Add-Type. The advantages of this over
    using Add-Type is that this is all generated in memory and no temporary
    files are created.

    The code has been created with great help from various sources. The main
    sources I used were;
    # http://www.leeholmes.com/blog/2007/10/02/managing-ini-files-with-powershell/
    # https://blogs.technet.microsoft.com/heyscriptingguy/2013/06/27/use-powershell-to-interact-with-the-windows-api-part-3/

    .PARAMETER DllName
    [String] The DLL to import the method from.

    .PARAMETER MethodName
    [String] The name of the method.

    .PARAMETER ReturnType
    [Type] The type of the return object returned by the method.

    .PARAMETER ParameterTypes
    [Type[]] Array of types that define the parameter types required by the
    method. The type index should match the index of the value in the
    Parameters parameter.

    If the parameter is a reference or an out parameter, use [Ref] as the type
    for that parameter.

    .PARAMETER Parameters
    [Object[]] Array of objects to supply for the parameter values required by
    the method. The value index should match the index of the value in the
    ParameterTypes parameter.

    If the parameter is a reference or an out parameter, the object should be a
    [Ref] of the parameter.

    .PARAMETER SetLastError
    [Bool] Whether to apply the SetLastError Dll attribute on the method,
    default is $false

    .PARAMETER CharSet
    [Runtime.InteropServices.CharSet] The charset to apply to the CharSet Dll
    attribute on the method, default is [Runtime.InteropServices.CharSet]::Auto

    .OUTPUTS
    [Object] The return result from the method, the type of this value is based
    on the ReturnType parameter.

    .EXAMPLE
    # Use the Win32 APIs to open a file handle
    $handle = Invoke-Win32Api -DllName kernel32.dll `
        -MethodName CreateFileW `
        -ReturnType Microsoft.Win32.SafeHandles.SafeFileHandle `
        -ParameterTypes @([String], [System.Security.AccessControl.FileSystemRights], [System.IO.FileShare], [IntPtr], [System.IO.FileMode], [UInt32], [IntPtr]) `
        -Parameters @(
            "\\?\C:\temp\test.txt",
            [System.Security.AccessControl.FileSystemRights]::FullControl,
            [System.IO.FileShare]::ReadWrite,
            [IntPtr]::Zero,
            [System.IO.FileMode]::OpenOrCreate,
            0,
            [IntPtr]::Zero) `
        -SetLastError $true `
        -CharSet Unicode
    if ($handle.IsInvalid) {
        $last_err = [System.Runtime.InteropServices.Marshal]::GetLastWin32Error()
        throw [System.ComponentModel.Win32Exception]$last_err
    }
    $handle.Close()

    # Lookup the account name from a SID
    $sid_string = "S-1-5-18"
    $sid = New-Object -TypeName System.Security.Principal.SecurityIdentifier -ArgumentList $sid_string
    $sid_bytes = New-Object -TypeName byte[] -ArgumentList $sid.BinaryLength
    $sid.GetBinaryForm($sid_bytes, 0)

    $name = New-Object -TypeName System.Text.StringBuilder
    $name_length = 0
    $domain_name = New-Object -TypeName System.Text.StringBuilder
    $domain_name_length = 0

    $invoke_args = @{
        DllName = "Advapi32.dll"
        MethodName = "LookupAccountSidW"
        ReturnType = [bool]
        ParameterTypes = @([String], [byte[]], [System.Text.StringBuilder], [Ref], [System.Text.StringBuilder], [Ref], [Ref])
        Parameters = @(
            $null,
            $sid_bytes,
            $name,
            [Ref]$name_length,
            $domain_name,
            [Ref]$domain_name_length,
            [Ref][IntPtr]::Zero
        )
        SetLastError = $true
        CharSet = "Unicode"
    }

    $res = Invoke-Win32Api @invoke_args
    $name.EnsureCapacity($name_length)
    $domain_name.EnsureCapacity($domain_name_length)
    $res = Invoke-Win32Api @invoke_args
    if (-not $res) {
        $last_err = [System.Runtime.InteropServices.Marshal]::GetLastWin32Error()
        throw [System.ComponentModel.Win32Exception]$last_err
    }
    Write-Output "SID: $sid_string, Domain: $($domain_name.ToString()), Name: $($name.ToString())"

    .NOTES
    The parameters to use for a method dynamically based on the method that is
    called. There is no cut and fast way to automatically convert the interface
    listed on the Microsoft docs. There are great resources to help you create
    the "P/Invoke" definition like pinvoke.net.
    #>
    [CmdletBinding()]
    [OutputType([Object])]
    param(
        [Parameter(Position = 0, Mandatory = $true)] [String]$DllName,
        [Parameter(Position = 1, Mandatory = $true)] [String]$MethodName,
        [Parameter(Position = 2, Mandatory = $true)] [Type]$ReturnType,
        [Parameter(Position = 3)] [Type[]]$ParameterTypes = [Type[]]@(),
        [Parameter(Position = 4)] [Object[]]$Parameters = [Object[]]@(),
        [Parameter()] [Bool]$SetLastError = $false,
        [Parameter()] [Runtime.InteropServices.CharSet]$CharSet = [Runtime.InteropServices.CharSet]::Auto
    )
    if ($ParameterTypes.Length -ne $Parameters.Length) {
        throw [System.ArgumentException]"ParameterType Count $($ParameterTypes.Length) not equal to Parameter Count $($Parameters.Length)"
    }

    # First step is to define the dynamic assembly in the current AppDomain
    $assembly = New-Object -TypeName System.Reflection.AssemblyName -ArgumentList "Win32ApiAssembly"
    $AssemblyBuilder = [System.Reflection.Assembly].Assembly.GetTypes() | Where-Object { $_.Name -eq 'AssemblyBuilder' }
    $dynamic_assembly = $AssemblyBuilder::DefineDynamicAssembly($assembly, [Reflection.Emit.AssemblyBuilderAccess]::Run)


    # Second step is to create the dynamic module and type/class that contains
    # the P/Invoke definition
    $dynamic_module = $dynamic_assembly.DefineDynamicModule("Win32Module", $false)
    $dynamic_type = $dynamic_module.DefineType("Win32Type", [Reflection.TypeAttributes]"Public, Class")

    # Need to manually get the reference type if the ParameterType is [Ref], we
    # define this based on the Parameter type at the same index
    $parameter_types = $ParameterTypes.Clone()
    for ($i = 0; $i -lt $ParameterTypes.Length; $i++) {
        if ($ParameterTypes[$i] -eq [Ref]) {
            $parameter_types[$i] = $Parameters[$i].Value.GetType().MakeByRefType()
        }
    }

    # Next, the method is created where we specify the name, parameters and
    # return type that is expected
    $dynamic_method = $dynamic_type.DefineMethod(
        $MethodName,
        [Reflection.MethodAttributes]"Public, Static",
        $ReturnType,
        $parameter_types
    )

    # Build the attributes (DllImport) part of the method where the DLL
    # SetLastError and CharSet are applied
    $constructor = [Runtime.InteropServices.DllImportAttribute].GetConstructor([String])
    $method_fields = [Reflection.FieldInfo[]]@(
        [Runtime.InteropServices.DllImportAttribute].GetField("SetLastError"),
        [Runtime.InteropServices.DllImportAttribute].GetField("CharSet")
    )
    $method_fields_values = [Object[]]@($SetLastError, $CharSet)
    $custom_attributes = New-Object -TypeName Reflection.Emit.CustomAttributeBuilder -ArgumentList @(
        $constructor,
        $DllName,
        $method_fields,
        $method_fields_values
    )
    $dynamic_method.SetCustomAttribute($custom_attributes)

    # Create the custom type/class based on what was configured above
    $win32_type = $dynamic_type.CreateType()

    # Invoke the method with the parameters supplied and return the result
    $result = $win32_type::$MethodName.Invoke($Parameters)
    return $result
}