winutil

package
v1.56.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 13, 2023 License: BSD-3-Clause Imports: 4 Imported by: 10

Documentation

Overview

Package winutil contains misc Windows/Win32 helper functions.

Index

Constants

View Source 
const (
	// 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.
	RegBase = regBase

	// RegPolicyBase is the registry path inside HKEY_LOCAL_MACHINE where registry
	// policies are stored. This constant is a non-empty string only when
	// GOOS=windows.
	RegPolicyBase = regPolicyBase
)
View Source 
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_`
)

Variables

View Source 
var (
	ErrDefunctProcess        = errors.New("process is defunct")
	ErrProcessNotRestartable = errors.New("process is not restartable")
)
View Source 
var ErrKeyWaitTimeout = errors.New("timeout waiting for registry key")

ErrKeyWaitTimeout is returned by OpenKeyWait when calls timeout.

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

ErrNoShell is returned when the shell process is not found.

View Source 
var ErrNoValue = registry.ErrNotExist

ErrNoValue is returned when the value doesn't exist in the registry.

Functions

func CreateAppMutex added in v1.22.0 

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 added in v1.26.0 

func DeleteRegValue(name string) error

DeleteRegValue removes a registry value in the local machine path.

func EnableCurrentThreadPrivilege added in v1.22.0 

func EnableCurrentThreadPrivilege(name string) (disable func(), err error)

EnableCurrentThreadPrivilege enables the named privilege in the current thread's access token. The current goroutine is also locked to the OS thread (runtime.LockOSThread). Callers must call the returned disable function when done with the privileged task.

func EnableCurrentThreadPrivileges added in v1.56.0 

func EnableCurrentThreadPrivileges(names []string) (disable func(), err error)

EnableCurrentThreadPrivileges enables the named privileges in the current thread's access token. The current goroutine is also locked to the OS thread (runtime.LockOSThread). Callers must call the returned disable function when done with the privileged task.

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 added in v1.22.0 

func GetPolicyInteger(name string) (uint64, error)

GetPolicyInteger looks up a registry value in the local machine's path for system policies, or returns 0 and the associated error. 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 0 and ErrNoValue. If value does not exist or another error happens, returns 0 and error.

func GetPolicyString added in v1.22.0 

func GetPolicyString(name string) (string, error)

GetPolicyString looks up a registry value in the local machine's path for system policies, or returns empty string and the error. 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 an empty string and ErrNoValue. If value does not exist or another error happens, returns empty string and error.

func GetRegInteger added in v1.16.0 

func GetRegInteger(name string) (uint64, error)

GetRegInteger looks up a registry path in the local machine path, or returns 0 and the error.

This function will only work on GOOS=windows. Trying to run it on any other OS will always return 0 and ErrNoValue. If value does not exist or another error happens, returns 0 and error.

func GetRegString added in v1.8.0 

func GetRegString(name string) (string, error)

GetRegString looks up a registry path in the local machine path, or returns an empty string and error.

This function will only work on GOOS=windows. Trying to run it on any other OS will always return an empty string and ErrNoValue. If value does not exist or another error happens, returns empty string and error.

func GetRegStrings added in v1.26.0 

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 added in v1.26.0 

func IsCurrentProcessElevated() bool

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

func IsSIDValidPrincipal added in v1.22.0 

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 added in v1.44.3 

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

IsTokenLimited returns whether token is a limited UAC token.

func LogSvcState added in v1.32.0 

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 LogonSessionID added in v1.56.0 

func LogonSessionID(token windows.Token) (logonSessionID windows.LUID, err error)

LogonSessionID obtains the logon session ID associated with token.

func LookupPseudoUser added in v1.34.0 

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 added in v1.30.0 

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 ProcessImageName added in v1.56.0 

func ProcessImageName(process windows.Handle) (string, error)

ProcessImageName returns the fully-qualified path to the executable image associated with process.

func RegisterForRestart added in v1.50.0 

func RegisterForRestart(opts RegisterForRestartOpts) error

RegisterForRestart registers the current process' restart preferences with the Windows Restart Manager. This enables the OS to intelligently restart the calling executable as requested via opts. This should be called by any programs which need to be restarted by the installer post-update.

This function may be called multiple times; the opts from the most recent call will override those from any previous invocations.

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

func RunProcessInSession added in v1.56.0 

func RunProcessInSession(sessID SessionID, cmdLineInfo CommandLineInfo, timeout time.Duration) (uint32, error)

RunProcessInSession creates a new process and waits up to timeout for that child process to complete its execution. The process is created using cmdLineInfo and will reside inside the session identified by sessID, with the security token whose logon is associated with sessID. The child process's environment will be inherited from the session token's environment.

func SetRegStrings added in v1.26.0 

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 added in v1.22.0 

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 added in v1.22.0 

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 StartProcessInSession added in v1.56.0 

func StartProcessInSession(sessID SessionID, cmdLineInfo CommandLineInfo) error

StartProcessInSession creates a new process using cmdLineInfo that will reside inside the session identified by sessID, with the security token whose logon is associated with sessID. The child process's environment will be inherited from the session token's environment.

func StartProcessInSessionWithHandler added in v1.56.0 

func StartProcessInSessionWithHandler(sessID SessionID, cmdLineInfo CommandLineInfo, handler PostCreateProcessHandler) error

StartProcessInSessionWithHandler creates a new process using cmdLineInfo that will reside inside the session identified by sessID, with the security token whose logon is associated with sessID. The child process's environment will be inherited from the session token's environment. When the child process has been successfully created, handler is invoked with the windows.ProcessInformation that was returned by the OS.

func TSSessionID added in v1.56.0 

func TSSessionID(token windows.Token) (tsSessionID uint32, err error)

TSSessionID obtains the Terminal Services (RDP) session ID associated with token.

func TSSessionIDToLogonSessionID added in v1.56.0 

func TSSessionIDToLogonSessionID(tsSessionID uint32) (logonSessionID windows.LUID, err error)

TSSessionIDToLogonSessionID retrieves the logon session ID associated with tsSessionId, which is a Terminal Services / RDP session ID. The calling process must be running as LocalSystem.

func WTSGetActiveConsoleSessionId added in v1.12.0 

func WTSGetActiveConsoleSessionId() uint32

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

Types

type CommandLineInfo added in v1.56.0 

type CommandLineInfo struct {
	// ExePath must be a fully-qualified path to a Windows executable binary.
	ExePath string
	// Args must be any arguments supplied to the process, excluding the
	// path to the binary itself. Args must be properly quoted according to
	// Windows path rules. To create a properly quoted Args from scratch, call the
	// SetArgs method instead.
	Args string `json:",omitempty"`
}

CommandLineInfo manages the necessary information for creating a Win32 process using a specific command line.

func (*CommandLineInfo) Resolve added in v1.56.0 

func (cli *CommandLineInfo) Resolve() (exePath *uint16, cmdLine *uint16, cmdLineStr string, err error)

Resolve converts the information in cli to a format compatible with the Win32 CreateProcess* family of APIs, as pointers to C-style UTF-16 strings. It also returns the full command line as a Go string for logging purposes.

func (*CommandLineInfo) SetArgs added in v1.56.0 

func (cli *CommandLineInfo) SetArgs(args []string)

SetArgs converts args to a string quoted as necessary to satisfy the rules for Win32 command lines, and sets cli.Args to that string.

func (*CommandLineInfo) Validate added in v1.56.0 

func (cli *CommandLineInfo) Validate() error

Validate ensures that cli.ExePath contains an absolute path.

type PostCreateProcessHandler added in v1.56.0 

type PostCreateProcessHandler func(pi *windows.ProcessInformation)

PostCreateProcessHandler is a function that is invoked by StartProcessInSessionWithHandler when the child process has been successfully created. It is the responsibility of the handler to close the pi.Thread and pi.Process handles.

type RegisterForRestartOpts added in v1.50.0 

type RegisterForRestartOpts struct {
	RestartOnCrash   bool     // When true, this program will be restarted after a crash.
	RestartOnHang    bool     // When true, this program will be restarted after a hang.
	RestartOnUpgrade bool     // When true, this program will be restarted after an upgrade.
	RestartOnReboot  bool     // When true, this program will be restarted after a reboot.
	UseCmdLineArgs   bool     // When true, CmdLineArgs will be used as the program's arguments upon restart. Otherwise no arguments will be provided.
	CmdLineArgs      []string // When UseCmdLineArgs == true, contains the command line arguments, excluding the executable name itself. If nil or empty, the arguments from the current process will be re-used.
}

RegisterForRestartOpts supplies options to RegisterForRestart.

type RegistryPath added in v1.30.0 

type RegistryPath string

RegistryPath represents a path inside a root registry.Key.

type RegistryPathPrefix added in v1.30.0 

type RegistryPathPrefix string

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

func (RegistryPathPrefix) WithSuffix added in v1.30.0 

func (p RegistryPathPrefix) WithSuffix(suf string) RegistryPath

WithSuffix returns a RegistryPath with the given suffix appended.

type RestartManagerSession added in v1.56.0 

type RestartManagerSession interface {
	io.Closer
	// AddPaths adds the fully-qualified paths in fqPaths to the set of binaries
	// that will be monitored by this restart manager session. NOTE: This
	// method is expensive to call, so it is better to make a single call with
	// a larger slice than to make multiple calls with smaller slices.
	AddPaths(fqPaths []string) error
	// AffectedProcesses returns the UniqueProcess information for all running
	// processes that utilize the binaries previously specified by calls to
	// AddPaths.
	AffectedProcesses() ([]UniqueProcess, error)
	// Key returns the session key associated with this instance.
	Key() string
}

RestartManagerSession represents an open Restart Manager session.

func AttachRestartManagerSession added in v1.56.0 

func AttachRestartManagerSession(logf logger.Logf, sessionKey string) (RestartManagerSession, error)

AttachRestartManagerSession opens a connection to an existing session specified by sessionKey, using logf for logging.

func NewRestartManagerSession added in v1.56.0 

func NewRestartManagerSession(logf logger.Logf) (RestartManagerSession, error)

NewRestartManagerSession creates a new RestartManagerSession that utilizes logf for logging.

type RestartableProcess added in v1.56.0 

type RestartableProcess struct {
	// Process uniquely identifies the existing process.
	Process UniqueProcess
	// SessionInfo uniquely identifies the Terminal Services (RDP) and logon
	// sessions the existing process is running under.
	SessionInfo SessionID
	// CommandLineInfo contains the command line information necessary for restarting.
	CommandLineInfo CommandLineInfo
	// LogonSID contains the stringified SID of the existing process's token's logon session.
	LogonSID string
	// UserSID contains the stringified SID of the existing process's token's user.
	UserSID string
	// contains filtered or unexported fields
}

RestartableProcess contains the necessary information to uniquely identify an existing process, as well as the necessary information to be able to terminate it and later start a new instance in the identical logon session to the previous instance.

func (*RestartableProcess) Close added in v1.56.0 

func (rp *RestartableProcess) Close() error

type RestartableProcesses added in v1.56.0 

type RestartableProcesses map[uint32]*RestartableProcess

RestartableProcesses is a map of PID to *RestartableProcess instance.

func NewRestartableProcesses added in v1.56.0 

func NewRestartableProcesses() RestartableProcesses

NewRestartableProcesses instantiates a new RestartableProcesses.

func (RestartableProcesses) Add added in v1.56.0 

func (rps RestartableProcesses) Add(rp *RestartableProcess)

Add inserts rp into rps.

func (RestartableProcesses) Close added in v1.56.0 

func (rps RestartableProcesses) Close() error

Close invokes (*RestartableProcess).Close on every value in rps, and then clears rps.

func (RestartableProcesses) Delete added in v1.56.0 

func (rps RestartableProcesses) Delete(rp *RestartableProcess)

Delete removes rp from rps.

func (RestartableProcesses) Terminate added in v1.56.0 

func (rps RestartableProcesses) Terminate(logf logger.Logf, exitCode uint32, timeout time.Duration) error

Terminate forcibly terminates all processes in rps using exitCode, and then waits for their process handles to signal, up to timeout.

type SessionID added in v1.56.0 

type SessionID struct {
	// LogonSession is the NT logon session ID.
	LogonSession windows.LUID
	// TSSession is the terminal services session ID.
	TSSession uint32
}

SessionID encapsulates the necessary information for uniquely identifying sessions. In particular, SessionID contains enough information to detect reuse of Terminal Service session IDs.

func (*SessionID) ContainsToken added in v1.56.0 

func (sessID *SessionID) ContainsToken(token windows.Token) (bool, error)

ContainsToken determines whether token is contained within sessID.

func (*SessionID) OpenToken added in v1.56.0 

func (sessID *SessionID) OpenToken() (windows.Token, error)

OpenToken obtains the security token associated with sessID.

type UniqueProcess added in v1.56.0 

type UniqueProcess struct {

	// CanReceiveGUIMsgs is true when the process has open top-level windows.
	CanReceiveGUIMsgs bool
	// contains filtered or unexported fields
}

UniqueProcess contains the necessary information to uniquely identify a process in the face of potential PID reuse.

func (*UniqueProcess) AsRestartableProcess added in v1.56.0 

func (up *UniqueProcess) AsRestartableProcess() (*RestartableProcess, error)

AsRestartableProcess obtains a RestartableProcess populated using the information obtained from up.

type UserSIDs added in v1.26.0 

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 added in v1.26.0 

func GetCurrentUserSIDs() (*UserSIDs, error)

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

Source Files

View all Source files

Directories

Path Synopsis
Package policy contains higher-level abstractions for accessing Windows enterprise policies.
 Package policy contains higher-level abstractions for accessing Windows enterprise policies.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.