wgroot

README

wgroot

The code in this package runs in a root-mode process, and is responsible for manipulating Wireguard state.

There is an accompanying user-mode process that talks to this module via a unix socket.

This design allows us to run the user-mode process in a lower privilege state.

Documentation

Index

• Constants
• func DropPrivileges(username string) error
• func GetUserHome(username string) (string, error)
• func IsRunningAsUser(username string) bool
• func LaunchRootModeSubProcess() (e error, secret string)
• func Main()
• func RelaunchSelf(args, env []string) (*exec.Cmd, error)
• func StripArgs(args []string, stripFlags, stripParameters []string) []string
• type PrivilegeLimiter
  • func NewPrivilegeLimiter(username string, flags PrivilegeLimiterFlags) (*PrivilegeLimiter, error)
  • func (p *PrivilegeLimiter) Drop() error
  • func (p *PrivilegeLimiter) Elevate() error
• type PrivilegeLimiterFlags

Constants

const Debug = false

const (
	// Change HOME and USER environment to the lower privilege user when first initializing,
	// but do not change them back when elevating permissions
	PrivilegeLimiterFlagSetEnvVars = 1 << iota
)

Functions

func DropPrivileges

func DropPrivileges(username string) error

Drop privileges of this process to the specified username, so that we reduce our attack surface. Returns the home directory of 'username'

func GetUserHome

func GetUserHome(username string) (string, error)

Retrieve the home directory of the given user

func IsRunningAsUser

func IsRunningAsUser(username string) bool

Return true if we are running as the given username

func LaunchRootModeSubProcess

func LaunchRootModeSubProcess() (e error, secret string)

Launch a copy of this process, but with the --kernelwg command line argument. This other process will run with root privileges, because it needs to be able to create and/or alter Wireguard interfaces.

This is one of the first things we do when starting up the cyclops server or the HTTPS proxy server.

Returns a secret that is used to authenticate ourselves to the root-mode spawned process.

func Main

func Main()

func RelaunchSelf

func RelaunchSelf(args, env []string) (*exec.Cmd, error)

This is used after dropping privileges, to make sure that our process has all the hallmarks of a normal user process. The reason this was created was so that NCNN could read from /proc/self/auxv to detect CPU features.

func StripArgs

func StripArgs(args []string, stripFlags, stripParameters []string) []string

Strip out command line arguments that are not needed by the child process. stripFlags is a list of options, such as "--kernelwg", which do not have any arguments after them. stripParameters is a list of options, such as "--username", which have an associated argument after them (such as "cyclops", in our example).

Types

type PrivilegeLimiter

type PrivilegeLimiter struct {
	ElevatedGid int
	ElevatedUid int
	LoweredGid  int
	LoweredUid  int
	LoweredHome string // Home directory of lower privileged user
}

PrivilegeLimiter is used to raise/lower privileges of the current process. This uses seteuid/setegid instead of setuid/setgid, to change only the effective user/group. This is useful when the process periodically needs to raise privileges, but keep them low most of the of the time.

func NewPrivilegeLimiter

func NewPrivilegeLimiter(username string, flags PrivilegeLimiterFlags) (*PrivilegeLimiter, error)

Save the current user credentials, and drop privileges to the specified username, with the ability to restore them again.

func (*PrivilegeLimiter) Drop

func (p *PrivilegeLimiter) Drop() error

Drop privileges to the lower privilege user

func (*PrivilegeLimiter) Elevate

func (p *PrivilegeLimiter) Elevate() error

Elevate privileges to the higher privilege user

type PrivilegeLimiterFlags

type PrivilegeLimiterFlags int