UEFI.psm1
|
# ----------------------------------------------------------------------------- # UEFI PowerShell module # Author: Michael Niehaus # Description: # A sample module to show how to interact with UEFI variables using # PowerShell. Provided as-is with no support. See https://oofhours.com # for related information. # ----------------------------------------------------------------------------- # ----------------------------------------------------------------------------- # One-time initialization # ----------------------------------------------------------------------------- $definition = @' using System; using System.Runtime.InteropServices; using System.Text; public class UEFINative { [DllImport("kernel32.dll", SetLastError = true)] public static extern UInt32 GetFirmwareEnvironmentVariableA(string lpName, string lpGuid, [Out] Byte[] lpBuffer, UInt32 nSize); [DllImport("kernel32.dll", SetLastError = true)] public static extern UInt32 SetFirmwareEnvironmentVariableA(string lpName, string lpGuid, Byte[] lpBuffer, UInt32 nSize); } '@ $uefiNative = Add-Type $definition -PassThru # Global constants $global:UEFIGlobal = "{8BE4DF61-93CA-11D2-AA0D-00E098032B8C}" $global:UEFIWindows = "{77FA9ABD-0359-4D32-BD60-28F4E78F784B}" $global:UEFISurface = "{D2E0B9C9-9860-42CF-B360-F906D5E0077A}" $global:UEFITesting = "{1801FBE3-AEF7-42A8-B1CD-FC4AFAE14716}" # ----------------------------------------------------------------------------- # One-time initialization # ----------------------------------------------------------------------------- function Get-UEFIVariable { <# .SYNOPSIS Gets the value of the specified UEFI firmware variable. .DESCRIPTION Gets the value of the specified UEFI firmware variable. This must be executed in an elevated process (requires admin rights). .PARAMETER Namespace A GUID string that specifies the specific UEFI namespace for the specified variable. Some predefined namespace global variables are defined in this module. If not specified, the UEFI global namespace ($UEFIGlobal) will be used. .PARAMETER VariableName The name of the variable to be retrieved. This parameter is mandatory. An error will be returned if the variable does not exist. .PARAMETER AsByteArray Switch to specify that the value of the specified UEFI variable should be returned as a byte array instead of as a string. .EXAMPLE Get-UEFIVariable -VariableName PlatformLang .EXAMPLE Get-UEFIVariable -VariableName BootOrder -AsByteArray .EXAMPLE Get-UEFIVariable -VariableName Blah -Namespace $UEFITesting .OUTPUTS A string or byte array containing the current value of the specified UEFI variable. .LINK https://oofhours.com/2019/09/02/geeking-out-with-uefi/ https://docs.microsoft.com/en-us/windows/win32/api/winbase/nf-winbase-getfirmwareenvironmentvariablea #Requires -Version 2.0 #> [cmdletbinding()] Param( [Parameter()] [String]$Namespace = $global:UEFIGlobal, [Parameter(Mandatory=$true)] [String]$VariableName, [Parameter()] [Switch]$AsByteArray = $false ) BEGIN { $rc = Set-LHSTokenPrivilege -Privilege SeSystemEnvironmentPrivilege } PROCESS { $size = 1024 $result = New-Object Byte[](1024) $rc = $uefiNative[0]::GetFirmwareEnvironmentVariableA($VariableName, $Namespace, $result, $size) if ($rc -eq 0) { Write-Error "Unable to retrieve variable $VariableName from namespace $Namespace" return "" } else { Write-Verbose "Variable $VariableName retrieved with $rc bytes" if ($AsByteArray) { [System.Array]::Resize([ref] $result, $rc) return $result } else { $enc = [System.Text.Encoding]::ASCII return $enc.GetString($result) } } } END { $rc = Set-LHSTokenPrivilege -Privilege SeSystemEnvironmentPrivilege -Disable } } # ----------------------------------------------------------------------------- # One-time initialization # ----------------------------------------------------------------------------- function Set-UEFIVariable { <# .SYNOPSIS Sets the value of the specified UEFI firmware variable. .DESCRIPTION Sets the value of the specified UEFI firmware variable. This must be executed in an elevated process (requires admin rights). .PARAMETER Namespace A GUID string that specifies the specific UEFI namespace for the specified variable. Some predefined namespace global variables are defined in this module. If not specified, the UEFI global namespace ($UEFIGlobal) will be used. .PARAMETER VariableName The name of the variable to be set. This parameter is mandatory. An error will be retrieved if trying to define a new variable in the UEFI global namespace (as per the UEFI design). .PARAMETER Value The string value that should be used to set the variable value. .PARAMETER ByteArray The byte array that should be used to set the variable value. .EXAMPLE Set-UEFIVariable -VariableName Blah -Namespace $UEFITesting -Value Blah .EXAMPLE $bytes = New-Object Byte[](8) Set-UEFIVariable -VariableName BlahBytes -Namespace $UEFITesting -ByteArray $bytes .LINK https://oofhours.com/2019/09/02/geeking-out-with-uefi/ https://docs.microsoft.com/en-us/windows/win32/api/winbase/nf-winbase-setfirmwareenvironmentvariablea #Requires -Version 2.0 #> [cmdletbinding()] Param( [Parameter()] [String]$Namespace = "{8BE4DF61-93CA-11D2-AA0D-00E098032B8C}", [Parameter(Mandatory=$true)] [String]$VariableName, [Parameter()] [String]$Value = "", [Parameter()] [Byte[]]$ByteArray = $null ) BEGIN { $rc = Set-LHSTokenPrivilege -Privilege SeSystemEnvironmentPrivilege } PROCESS { if ($Value -ne "") { $enc = [System.Text.Encoding]::ASCII $bytes = $enc.GetBytes($Value) Write-Verbose "Setting variable $VariableName to a string value with $($bytes.Length) characters" $rc = $uefiNative[0]::SetFirmwareEnvironmentVariableA($VariableName, $Namespace, $bytes, $bytes.Length) } else { Write-Verbose "Setting variable $VariableName to a byte array with $($ByteArray.Length) bytes" $rc = $uefiNative[0]::SetFirmwareEnvironmentVariableA($VariableName, $Namespace, $ByteArray, $ByteArray.Length) } if ($rc -eq 0) { Write-Error "Unable to set variable $VariableName from namespace $Namespace" } } END { $rc = Set-LHSTokenPrivilege -Privilege SeSystemEnvironmentPrivilege -Disable } } # The following functions enable and disable the required SeSystemEnvironmentPrivilege. It was pulled from # Lee Holmes' blog at http://www.leeholmes.com/blog/2010/09/24/adjusting-token-privileges-in-powershell/. This # is tremendously useful when dealing with Windows priviledges. function Set-LHSTokenPrivilege { <# .SYNOPSIS Enables or disables privileges in a specified access token. .DESCRIPTION Enables or disables privileges in a specified access token. .PARAMETER Privilege The privilege to adjust. This set is taken from http://msdn.microsoft.com/en-us/library/bb530716(VS.85).aspx .PARAMETER ProcessId The process on which to adjust the privilege. Defaults to the current process. .PARAMETER Disable Switch to disable the privilege, rather than enable it. .EXAMPLE Set-LHSTokenPrivilege -Privilege SeRestorePrivilege To set the 'Restore Privilege' for the current Powershell Process. .EXAMPLE Set-LHSTokenPrivilege -Privilege SeRestorePrivilege -Disable To disable 'Restore Privilege' for the current Powershell Process. .EXAMPLE Set-LHSTokenPrivilege -Privilege SeShutdownPrivilege -ProcessId 4711 To set the 'Shutdown Privilege' for the Process with Process ID 4711 .INPUTS None to the pipeline .OUTPUTS System.Boolean, True if the privilege could be enabled .NOTES to check privileges use whoami PS:\> whoami /priv PRIVILEGES INFORMATION ---------------------- Privilege Name Description State ============================= ==================================== ======== SeShutdownPrivilege Shut down the system Disabled SeChangeNotifyPrivilege Bypass traverse checking Enabled SeUndockPrivilege Remove computer from docking station Disabled SeIncreaseWorkingSetPrivilege Increase a process working set Disabled AUTHOR: Pasquale Lantella LASTEDIT: KEYWORDS: Token Privilege .LINK http://www.leeholmes.com/blog/2010/09/24/adjusting-token-privileges-in-powershell/ The privilege to adjust. This set is taken from http://msdn.microsoft.com/en-us/library/bb530716(VS.85).aspx pinvoke AdjustTokenPrivileges (advapi32) http://www.pinvoke.net/default.aspx/advapi32.AdjustTokenPrivileges #Requires -Version 2.0 #> [cmdletbinding( ConfirmImpact = 'low', SupportsShouldProcess = $false )] [OutputType('System.Boolean')] Param( [Parameter(Position=0,Mandatory=$True,ValueFromPipeline=$False,HelpMessage='An Token Privilege.')] [ValidateSet( "SeAssignPrimaryTokenPrivilege", "SeAuditPrivilege", "SeBackupPrivilege", "SeChangeNotifyPrivilege", "SeCreateGlobalPrivilege", "SeCreatePagefilePrivilege", "SeCreatePermanentPrivilege", "SeCreateSymbolicLinkPrivilege", "SeCreateTokenPrivilege", "SeDebugPrivilege", "SeEnableDelegationPrivilege", "SeImpersonatePrivilege", "SeIncreaseBasePriorityPrivilege", "SeIncreaseQuotaPrivilege", "SeIncreaseWorkingSetPrivilege", "SeLoadDriverPrivilege", "SeLockMemoryPrivilege", "SeMachineAccountPrivilege", "SeManageVolumePrivilege", "SeProfileSingleProcessPrivilege", "SeRelabelPrivilege", "SeRemoteShutdownPrivilege", "SeRestorePrivilege", "SeSecurityPrivilege", "SeShutdownPrivilege", "SeSyncAgentPrivilege", "SeSystemEnvironmentPrivilege", "SeSystemProfilePrivilege", "SeSystemtimePrivilege", "SeTakeOwnershipPrivilege", "SeTcbPrivilege", "SeTimeZonePrivilege", "SeTrustedCredManAccessPrivilege", "SeUndockPrivilege", "SeUnsolicitedInputPrivilege")] [String]$Privilege, [Parameter(Position=1)] $ProcessId = $pid, [Switch]$Disable ) BEGIN { Set-StrictMode -Version Latest ${CmdletName} = $Pscmdlet.MyInvocation.MyCommand.Name ## Taken from P/Invoke.NET with minor adjustments. $definition = @' using System; using System.Runtime.InteropServices; public class AdjPriv { [DllImport("advapi32.dll", ExactSpelling = true, SetLastError = true)] internal static extern bool AdjustTokenPrivileges(IntPtr htok, bool disall, ref TokPriv1Luid newst, int len, IntPtr prev, IntPtr relen); [DllImport("advapi32.dll", ExactSpelling = true, SetLastError = true)] internal static extern bool OpenProcessToken(IntPtr h, int acc, ref IntPtr phtok); [DllImport("advapi32.dll", SetLastError = true)] internal static extern bool LookupPrivilegeValue(string host, string name, ref long pluid); [StructLayout(LayoutKind.Sequential, Pack = 1)] internal struct TokPriv1Luid { public int Count; public long Luid; public int Attr; } internal const int SE_PRIVILEGE_ENABLED = 0x00000002; internal const int SE_PRIVILEGE_DISABLED = 0x00000000; internal const int TOKEN_QUERY = 0x00000008; internal const int TOKEN_ADJUST_PRIVILEGES = 0x00000020; public static bool EnablePrivilege(long processHandle, string privilege, bool disable) { bool retVal; TokPriv1Luid tp; IntPtr hproc = new IntPtr(processHandle); IntPtr htok = IntPtr.Zero; retVal = OpenProcessToken(hproc, TOKEN_ADJUST_PRIVILEGES | TOKEN_QUERY, ref htok); tp.Count = 1; tp.Luid = 0; if(disable) { tp.Attr = SE_PRIVILEGE_DISABLED; } else { tp.Attr = SE_PRIVILEGE_ENABLED; } retVal = LookupPrivilegeValue(null, privilege, ref tp.Luid); retVal = AdjustTokenPrivileges(htok, false, ref tp, 0, IntPtr.Zero, IntPtr.Zero); return retVal; } } '@ } # end BEGIN PROCESS { $processHandle = (Get-Process -id $ProcessId).Handle $type = Add-Type $definition -PassThru $type[0]::EnablePrivilege($processHandle, $Privilege, $Disable) } # end PROCESS END { Write-Verbose "Function ${CmdletName} finished." } } # end Function Set-LHSTokenPrivilege |