utils

Documentation

Index

• Constants
• Variables
• func Annotations(labels []string) (bundle string, userAnnotations map[string]string)
• func CleanPath(path string) string
• func CloseExecFrom(minFd int) error
• func EnsureProcHandle(fh *os.File) error
• func ExitStatus(status unix.WaitStatus) int
• func IsLexicallyInRoot(root, path string) bool
• func MkdirAllInRoot(root, unsafePath string, mode uint32) error
• func MkdirAllInRootOpen(root, unsafePath string, mode uint32) (_ *os.File, Err error)
• func NewSockPair(name string) (parent, child *os.File, err error)
• func RecvFile(socket *os.File) (_ *os.File, Err error)
• func SearchLabels(labels []string, key string) (string, bool)
• func SendFile(socket *os.File, file *os.File) error
• func SendRawFd(socket *os.File, msg string, fd uintptr) error
• func UnsafeCloseFrom(minFd int) error
• func WithProcfd(root, unsafePath string, fn func(procfd string) error) error
• func WriteJSON(w io.Writer, v interface{}) error
• type ProcThreadSelfCloser
  • func ProcThreadSelf(subpath string) (string, ProcThreadSelfCloser)
  • func ProcThreadSelfFd(fd uintptr) (string, ProcThreadSelfCloser)

Constants

const MaxNameLen = 4096

MaxNameLen is the maximum length of the name of a file descriptor being sent using SendFile. The name of the file handle returned by RecvFile will never be larger than this value.

Variables

var NativeEndian binary.ByteOrder

NativeEndian is the native byte order of the host system.

Functions

func Annotations

func Annotations(labels []string) (bundle string, userAnnotations map[string]string)

Annotations returns the bundle path and user defined annotations from the libcontainer state. We need to remove the bundle because that is a label added by libcontainer.

func CleanPath

func CleanPath(path string) string

CleanPath makes a path safe for use with filepath.Join. This is done by not only cleaning the path, but also (if the path is relative) adding a leading '/' and cleaning it (then removing the leading '/'). This ensures that a path resulting from prepending another path will always resolve to lexically be a subdirectory of the prefixed path. This is all done lexically, so paths that include symlinks won't be safe as a result of using CleanPath.

func CloseExecFrom

func CloseExecFrom(minFd int) error

CloseExecFrom sets the O_CLOEXEC flag on all file descriptors greater or equal to minFd in the current process.

func EnsureProcHandle

func EnsureProcHandle(fh *os.File) error

EnsureProcHandle returns whether or not the given file handle is on procfs.

func ExitStatus

func ExitStatus(status unix.WaitStatus) int

ExitStatus returns the correct exit status for a process based on if it was signaled or exited cleanly

func IsLexicallyInRoot

func IsLexicallyInRoot(root, path string) bool

IsLexicallyInRoot is shorthand for strings.HasPrefix(path+"/", root+"/"), but properly handling the case where path or root are "/".

NOTE: The return value only make sense if the path doesn't contain "..".

func MkdirAllInRoot

func MkdirAllInRoot(root, unsafePath string, mode uint32) error

MkdirAllInRoot is a wrapper around MkdirAllInRootOpen which closes the returned handle, for callers that don't need to use it.

func MkdirAllInRootOpen

func MkdirAllInRootOpen(root, unsafePath string, mode uint32) (_ *os.File, Err error)

MkdirAllInRootOpen attempts to make

path, _ := securejoin.SecureJoin(root, unsafePath)
os.MkdirAll(path, mode)
os.Open(path)

safer against attacks where components in the path are changed between SecureJoin returning and MkdirAll (or Open) being called. In particular, we try to detect any symlink components in the path while we are doing the MkdirAll.

NOTE: Unlike os.MkdirAll, mode is not Go's os.FileMode, it is the unix mode (the suid/sgid/sticky bits are not the same as for os.FileMode).

NOTE: If unsafePath is a subpath of root, we assume that you have already called SecureJoin and so we use the provided path verbatim without resolving any symlinks (this is done in a way that avoids symlink-exchange races). This means that the path also must not contain ".." elements, otherwise an error will occur.

This is a somewhat less safe alternative to <https://github.com/cyphar/filepath-securejoin/pull/13>, but it should detect attempts to trick us into creating directories outside of the root. We should migrate to securejoin.MkdirAll once it is merged.

func NewSockPair

func NewSockPair(name string) (parent, child *os.File, err error)

NewSockPair returns a new SOCK_STREAM unix socket pair.

func RecvFile

func RecvFile(socket *os.File) (_ *os.File, Err error)

RecvFile waits for a file descriptor to be sent over the given AF_UNIX socket. The file name of the remote file descriptor will be recreated locally (it is sent as non-auxiliary data in the same payload).

func SearchLabels

func SearchLabels(labels []string, key string) (string, bool)

SearchLabels searches through a list of key=value pairs for a given key, returning its value, and the binary flag telling whether the key exist.

func SendFile

func SendFile(socket *os.File, file *os.File) error

SendFile sends a file over the given AF_UNIX socket. file.Name() is also included so that if the other end uses RecvFile, the file will have the same name information.

func SendRawFd

func SendRawFd(socket *os.File, msg string, fd uintptr) error

SendRawFd sends a specific file descriptor over the given AF_UNIX socket.

func UnsafeCloseFrom

func UnsafeCloseFrom(minFd int) error

UnsafeCloseFrom closes all file descriptors greater or equal to minFd in the current process, except for those critical to Go's runtime (such as the netpoll management descriptors).

NOTE: That this function is incredibly dangerous to use in most Go code, as closing file descriptors from underneath *os.File handles can lead to very bad behaviour (the closed file descriptor can be re-used and then any *os.File operations would apply to the wrong file). This function is only intended to be called from the last stage of runc init.

func WithProcfd

func WithProcfd(root, unsafePath string, fn func(procfd string) error) error

WithProcfd runs the passed closure with a procfd path (/proc/self/fd/...) corresponding to the unsafePath resolved within the root. Before passing the fd, this path is verified to have been inside the root -- so operating on it through the passed fdpath should be safe. Do not access this path through the original path strings, and do not attempt to use the pathname outside of the passed closure (the file handle will be freed once the closure returns).

func WriteJSON

func WriteJSON(w io.Writer, v interface{}) error

WriteJSON writes the provided struct v to w using standard json marshaling without a trailing newline. This is used instead of json.Encoder because there might be a problem in json decoder in some cases, see: https://github.com/docker/docker/issues/14203#issuecomment-174177790

Types

type ProcThreadSelfCloser

type ProcThreadSelfCloser func()

func ProcThreadSelf

func ProcThreadSelf(subpath string) (string, ProcThreadSelfCloser)

ProcThreadSelf returns a string that is equivalent to /proc/thread-self/<subpath>, with a graceful fallback on older kernels where /proc/thread-self doesn't exist. This method DOES NOT use SecureJoin, meaning that the passed string needs to be trusted. The caller _must_ call the returned procThreadSelfCloser function (which is runtime.UnlockOSThread) *only once* after it has finished using the returned path string.

func ProcThreadSelfFd

func ProcThreadSelfFd(fd uintptr) (string, ProcThreadSelfCloser)

ProcThreadSelfFd is small wrapper around ProcThreadSelf to make it easier to create a /proc/thread-self handle for given file descriptor.

It is basically equivalent to ProcThreadSelf(fmt.Sprintf("fd/%d", fd)), but without using fmt.Sprintf to avoid unneeded overhead.