winutil

Documentation

Overview

Package winutil contains misc Windows/Win32 helper functions.

Index

• Constants
• Variables
• func CreateAppMutex(name string) (windows.Handle, error)
• func DeleteRegValue(name string) error
• func EnableCurrentThreadPrivilege(name string) error
• func GetDesktopPID() (uint32, error)
• func GetPolicyInteger(name string, defval uint64) uint64
• func GetPolicyString(name, defval string) string
• func GetRegInteger(name string, defval uint64) uint64
• func GetRegString(name, defval string) string
• func GetRegStrings(name string, defval []string) []string
• func IsCurrentProcessElevated() bool
• func IsSIDValidPrincipal(uid string) bool
• func IsTokenLimited(token windows.Token) (bool, error)
• func LogSupportInfo(logf logger.Logf)
• func LogSvcState(logf logger.Logf, rootSvcName string)
• func LookupPseudoUser(uid string) (*user.User, error)
• func OpenKeyWait(k registry.Key, path RegistryPath, access uint32) (registry.Key, error)
• func SetRegStrings(name string, values []string) error
• func StartProcessAsChild(parentPID uint32, exePath string, extraEnv []string) error
• func StartProcessAsCurrentGUIUser(exePath string, extraEnv []string) error
• func WTSGetActiveConsoleSessionId() uint32
• type RegistryPath
• type RegistryPathPrefix
  • func (p RegistryPathPrefix) WithSuffix(suf string) RegistryPath
• type UserSIDs
  • func GetCurrentUserSIDs() (*UserSIDs, error)

Constants

const (
	IPv4TCPIPBase RegistryPath = `SYSTEM\CurrentControlSet\Services\Tcpip\Parameters`
	IPv6TCPIPBase RegistryPath = `SYSTEM\CurrentControlSet\Services\Tcpip6\Parameters`
	NetBTBase     RegistryPath = `SYSTEM\CurrentControlSet\Services\NetBT\Parameters`

	IPv4TCPIPInterfacePrefix RegistryPathPrefix = `SYSTEM\CurrentControlSet\Services\Tcpip\Parameters\Interfaces\`
	IPv6TCPIPInterfacePrefix RegistryPathPrefix = `SYSTEM\CurrentControlSet\Services\Tcpip6\Parameters\Interfaces\`
	NetBTInterfacePrefix     RegistryPathPrefix = `SYSTEM\CurrentControlSet\Services\NetBT\Parameters\Interfaces\Tcpip_`
)

const RegBase = regBase

RegBase is the registry path inside HKEY_LOCAL_MACHINE where registry settings are stored. This constant is a non-empty string only when GOOS=windows.

Variables

var ErrKeyWaitTimeout = errors.New("timeout waiting for registry key")

ErrKeyWaitTimeout is returned by OpenKeyWait when calls timeout.

var ErrNoShell = errors.New("no Shell process is present")

ErrNoShell is returned when the shell process is not found.

Functions

func CreateAppMutex

func CreateAppMutex(name string) (windows.Handle, error)

CreateAppMutex creates a named Windows mutex, returning nil if the mutex is created successfully or an error if the mutex already exists or could not be created for some other reason.

func DeleteRegValue

func DeleteRegValue(name string) error

DeleteRegValue removes a registry value in the local machine path.

func EnableCurrentThreadPrivilege

func EnableCurrentThreadPrivilege(name string) error

EnableCurrentThreadPrivilege enables the named privilege in the current thread access token.

func GetDesktopPID

func GetDesktopPID() (uint32, error)

GetDesktopPID searches the PID of the process that's running the currently active desktop. Returns ErrNoShell if the shell is not present. Usually the PID will be for explorer.exe.

func GetPolicyInteger

func GetPolicyInteger(name string, defval uint64) uint64

GetPolicyInteger looks up a registry value in the local machine's path for system policies, or returns the given default if it can't. Use this function to read values that may be set by sysadmins via the MSI installer or via GPO. For registry settings that you do *not* want to be visible to sysadmin tools, use GetRegInteger instead.

This function will only work on GOOS=windows. Trying to run it on any other OS will always return the default value.

func GetPolicyString

func GetPolicyString(name, defval string) string

GetPolicyString looks up a registry value in the local machine's path for system policies, or returns the given default if it can't. Use this function to read values that may be set by sysadmins via the MSI installer or via GPO. For registry settings that you do *not* want to be visible to sysadmin tools, use GetRegString instead.

This function will only work on GOOS=windows. Trying to run it on any other OS will always return the default value.

func GetRegInteger

func GetRegInteger(name string, defval uint64) uint64

GetRegInteger looks up a registry path in the local machine path, or returns the given default if it can't.

This function will only work on GOOS=windows. Trying to run it on any other OS will always return the default value.

func GetRegString

func GetRegString(name, defval string) string

GetRegString looks up a registry path in the local machine path, or returns the given default if it can't.

This function will only work on GOOS=windows. Trying to run it on any other OS will always return the default value.

func GetRegStrings

func GetRegStrings(name string, defval []string) []string

GetRegStrings looks up a registry value in the local machine path, or returns the given default if it can't.

func IsCurrentProcessElevated

func IsCurrentProcessElevated() bool

IsCurrentProcessElevated returns true when the current process is running with an elevated token, implying Administrator access.

func IsSIDValidPrincipal

func IsSIDValidPrincipal(uid string) bool

IsSIDValidPrincipal determines whether the SID contained in uid represents a type that is a valid security principal under Windows. This check helps us work around a bug in the standard library's Windows implementation of LookupId in os/user. See https://github.com/tailscale/tailscale/issues/869

This function will only work on GOOS=windows. Trying to run it on any other OS will always return false.

func IsTokenLimited

func IsTokenLimited(token windows.Token) (bool, error)

IsTokenLimited returns whether token is a limited UAC token.

func LogSupportInfo

func LogSupportInfo(logf logger.Logf)

LogSupportInfo obtains information useful for troubleshooting and support, and writes it to the log as a JSON-encoded object.

func LogSvcState

func LogSvcState(logf logger.Logf, rootSvcName string)

LogSvcState obtains the state of the Windows service named rootSvcName and all of its dependencies, and then emits that state to logf.

func LookupPseudoUser

func LookupPseudoUser(uid string) (*user.User, error)

LookupPseudoUser attempts to resolve the user specified by uid by checking against well-known pseudo-users on Windows. This is a temporary workaround until https://github.com/golang/go/issues/49509 is resolved and shipped.

This function will only work on GOOS=windows. Trying to run it on any other OS will always return an error.

func OpenKeyWait

func OpenKeyWait(k registry.Key, path RegistryPath, access uint32) (registry.Key, error)

OpenKeyWait opens a registry key, waiting for it to appear if necessary. It returns the opened key, or ErrKeyWaitTimeout if the key does not appear within 20s. The caller must call Close on the returned key.

func SetRegStrings

func SetRegStrings(name string, values []string) error

SetRegStrings sets a MULTI_SZ value in the in the local machine path to the strings specified by values.

func StartProcessAsChild

func StartProcessAsChild(parentPID uint32, exePath string, extraEnv []string) error

StartProcessAsChild starts exePath process as a child of parentPID. StartProcessAsChild copies parentPID's environment variables into the new process, along with any optional environment variables in extraEnv.

func StartProcessAsCurrentGUIUser

func StartProcessAsCurrentGUIUser(exePath string, extraEnv []string) error

StartProcessAsCurrentGUIUser is like StartProcessAsChild, but if finds current logged in user desktop process (normally explorer.exe), and passes found PID to StartProcessAsChild.

func WTSGetActiveConsoleSessionId

func WTSGetActiveConsoleSessionId() uint32

TODO(crawshaw): replace with x/sys/windows... one day. https://go-review.googlesource.com/c/sys/+/331909

Types

type RegistryPath

type RegistryPath string

RegistryPath represents a path inside a root registry.Key.

type RegistryPathPrefix

type RegistryPathPrefix string

RegistryPathPrefix specifies a RegistryPath prefix that must be suffixed with another RegistryPath to make a valid RegistryPath.

func (RegistryPathPrefix) WithSuffix

func (p RegistryPathPrefix) WithSuffix(suf string) RegistryPath

WithSuffix returns a RegistryPath with the given suffix appended.

type UserSIDs

type UserSIDs struct {
	User         *windows.SID
	PrimaryGroup *windows.SID
}

UserSIDs contains the SIDs for a Windows NT token object's associated user as well as its primary group.

func GetCurrentUserSIDs

func GetCurrentUserSIDs() (*UserSIDs, error)

GetCurrentUserSIDs returns a UserSIDs struct containing SIDs for the current process' user and primary group.