README

Package cap is the libcap API for Linux Capabilities written in
Go. The official release announcement site for libcap is:

   https://sites.google.com/site/fullycapable/

Like libcap, the cap package is distributed with a "you choose"
License. Specifically: BSD three clause, or GPL2. See the License
file.

Andrew G. Morgan <morgan@kernel.org>
Expand ▾ Collapse ▴

Documentation

Overview

    Package cap provides all the Linux Capabilities userspace library API bindings in native Go.

    Capabilities are a feature of the Linux kernel that allow fine grain permissions to perform privileged operations. Privileged operations are required to do irregular system level operations from code. You can read more about how Capabilities are intended to work here:

    https://static.googleusercontent.com/media/research.google.com/en//pubs/archive/33528.pdf
    

    This package supports native Go bindings for all the features described in that paper as well as supporting subsequent changes to the kernel for other styles of inheritable Capability.

    Some simple things you can do with this package are:

    // Read and display the capabilities of the running process
    c := cap.GetProc()
    log.Printf("this process has these caps:", c)
    
    // Drop any privilege a process might have (including for root,
    // but note root 'owns' a lot of system files so a cap-limited
    // root can still do considerable damage to a running system).
    old := cap.GetProc()
    empty := cap.NewSet()
    if err := empty.SetProc(); err != nil {
        log.Fatalf("failed to drop privilege: %q -> %q: %v", old, empty, err)
    }
    now := cap.GetProc()
    if cf, _ := now.Compare(empty); cf != 0 {
        log.Fatalf("failed to fully drop privilege: have=%q, wanted=%q", now, empty)
    }
    

    The "cap" package operates with POSIX semantics for security state. That is all OS threads are kept in sync at all times. The package "kernel.org/pub/linux/libs/security/libcap/psx" is used to implement POSIX semantics system calls that manipulate thread state uniformly over the whole Go (and any CGo linked) process runtime.

    Note, if the Go runtime syscall interface contains the Linux variant syscall.AllThreadsSyscall() API (it debuted in go1.16 see https://github.com/golang/go/issues/1435 for its history) then the "libcap/psx" package will use that to invoke Capability setting system calls in pure Go binaries. With such an enhanced Go runtime, to force this behavior, use the CGO_ENABLED=0 environment variable.

    POSIX semantics are more secure than trying to manage privilege at a thread level when those threads share a common memory image as they do under Linux: it is trivial to exploit a vulnerability in one thread of a process to cause execution on any another thread. So, any imbalance in security state, in such cases will readily create an opportunity for a privilege escalation vulnerability.

    POSIX semantics also work well with Go, which deliberately tries to insulate the user from worrying about the number of OS threads that are actually running in their program. Indeed, Go can efficiently launch and manage tens of thousands of concurrent goroutines without bogging the program or wider system down. It does this by aggressively migrating idle threads to make progress on unblocked goroutines. So, inconsistent security state across OS threads can also lead to program misbehavior.

    The only exception to this process-wide common security state is the cap.Launcher related functionality. This briefly locks an OS thread to a goroutine in order to launch another executable - the robust implementation of this kind of support is quite subtle, so please read its documentation carefully, if you find that you need it.

    See https://sites.google.com/site/fullycapable/ for recent updates, some more complete walk-through examples of ways of using 'cap.Set's etc and information on how to file bugs.

    Copyright (c) 2019-21 Andrew G. Morgan <morgan@kernel.org>

    The cap and psx packages are licensed with a (you choose) BSD 3-clause or GPL2. See LICENSE file for details.

    Index

    Constants

    View Source
    const ExtMagic = uint32(0x5101c290)

      ExtMagic is the 32-bit (little endian) magic for an external capability set. It can be used to transmit capabilities in binary format in a Linux portable way. The format is: <ExtMagic><byte:length><length-bytes*3-of-cap-data>.

      View Source
      const LaunchSupported = true

        LaunchSupported indicates that is safe to return from a locked OS Thread and have that OS Thread be terminated by the runtime. The Launch functionality really needs to rely on the fact that an excess of runtime.LockOSThread() vs. runtime.UnlockOSThread() calls in a returning go routine will cause the underlying locked OSThread to terminate. That feature was added to the Go runtime in version 1.10.

        See these bugs for the discussion and feature assumed by the code in this Launch() functionality:

        https://github.com/golang/go/issues/20395
        https://github.com/golang/go/issues/20458
        

        A value of false for this constant causes the Launch functionality to fail with an error: cap.ErrNoLaunch. If this value is false you have two choices with respect to the Launch functionality:

        1) don't use cap.(*Launcher).Launch()
        2) upgrade your Go toolchain to 1.10+ (ie., do this one).
        
        View Source
        const NamedCount = 41

          NamedCount holds the number of capability values with official names known at the time this libcap/cap version, was released. The "../libcap/cap" package is fully able to manipulate higher numbered capability values by numerical value. However, if you find cap.NamedCount < cap.MaxBits(), it is probably time to upgrade this package on your system.

          FWIW the userspace tool '/sbin/capsh' also contains a runtime check for the condition that libcap is behind the running kernel in this way.

          Variables

          View Source
          var ErrAmbiguousAmbient = errors.New("use Launcher for ambient caps")

            ErrAmbiguousAmbient indicates that the Launcher is being used in addition to a callback supplied ambient set and the former should be used exclusively in a Launch call.

            View Source
            var ErrAmbiguousChroot = errors.New("use Launcher for chroot")

              ErrAmbiguousChroot indicates that the Launcher is being used in addition to a callback supplied Chroot. The former should be used exclusively for this.

              View Source
              var ErrAmbiguousIDs = errors.New("use Launcher for uids and gids")

                ErrAmbiguousIDs indicates that the Launcher is being used in addition to a callback supplied Credentials. The former should be used exclusively for this.

                View Source
                var ErrBadMagic = errors.New("unsupported magic")

                  ErrBadMagic indicates that the kernel preferred magic number for capability Set values is not supported by this package. This generally implies you are using an exceptionally old "../libcap/cap" package. An upgrade is needed, or failing that see https://sites.google.com/site/fullycapable/ for how to file a bug.

                  View Source
                  var ErrBadMode = errors.New("unsupported mode")

                    ErrBadMode is the error returned when an attempt is made to set an unrecognized libcap security mode.

                    View Source
                    var ErrBadPath = errors.New("file is not a regular executable")

                      ErrBadPath indicates a failed attempt to set a file capability on an irregular (non-executable) file.

                      View Source
                      var ErrBadSet = errors.New("bad capability set")

                        ErrBadSet indicates a nil pointer was used for a *Set, or the request of the Set is invalid in some way.

                        View Source
                        var ErrBadSize = errors.New("filecap bad size")

                          ErrBadSize indicates the the loaded file capability has an invalid number of bytes in it.

                          View Source
                          var ErrBadText = errors.New("bad text")

                            ErrBadText is returned if the text for a capability set cannot be parsed.

                            View Source
                            var ErrBadValue = errors.New("bad capability value")

                              ErrBadValue indicates a bad capability value was specified.

                              View Source
                              var ErrLaunchFailed = errors.New("launch failed")

                                ErrLaunchFailed is returned if a launch was aborted with no more specific error.

                                View Source
                                var ErrNoLaunch = errors.New("launch not supported")

                                  ErrNoLaunch indicates the go runtime available to this binary does not reliably support launching. See cap.LaunchSupported.

                                  Functions

                                  func Differs

                                  func Differs(cf uint, vec Flag) bool

                                    Differs processes the result of Compare and determines if the Flag's components were different.

                                    func DropBound

                                    func DropBound(val ...Value) error

                                      DropBound attempts to suppress bounding set Values. The kernel will never allow a bounding set Value bit to be raised once successfully dropped. However, dropping requires the current process is sufficiently capable (usually via cap.SETPCAP being raised in the Effective flag of the process' Set). Note, the drops are performed in order and if one bounding value cannot be dropped, the function returns immediately with an error which may leave the system in an ill-defined state. The caller can determine where things went wrong using GetBound().

                                      func GetAmbient

                                      func GetAmbient(val Value) (bool, error)

                                        GetAmbient determines if a specific capability is currently part of the local ambient set. On systems where the ambient set Value is not present, this function returns an error.

                                        func GetBound

                                        func GetBound(val Value) (bool, error)

                                          GetBound determines if a specific capability is currently part of the local bounding set. On systems where the bounding set Value is not present, this function returns an error.

                                          func Prctl

                                          func Prctl(prVal uintptr, args ...uintptr) (int, error)

                                            Prctl is a convenience function that performs a syscall.Prctl() that either reads state using a single OS thread, or performs a Prctl that is treated as a process wide setting. It is provided for symmetry reasons, but is equivalent to simply calling the corresponding syscall function.

                                            func Prctlw

                                            func Prctlw(prVal uintptr, args ...uintptr) (int, error)

                                              Prctlw is a convenience function for performing a syscall.Prctl() call that executes on all the threads of the process. It is called Prctlw because it is only appropriate to call this function when it is writing thread state that the caller wants to set on all OS threads of the process to observe POSIX semantics when Linux doesn't natively honor them. (Check prctl documentation for when it is appropriate to use this vs. a normal syscall.Prctl() call.)

                                              func ResetAmbient

                                              func ResetAmbient() error

                                                ResetAmbient attempts to ensure the Ambient set is fully cleared. It works by first reading the set and if it finds any bits raised it will attempt a reset. The test before attempting a reset behavior is a workaround for situations where the Ambient API is locked, but a reset is not actually needed. No Ambient bit not already raised in both the Permitted and Inheritable Set is allowed to be raised by the kernel.

                                                func SetAmbient

                                                func SetAmbient(enable bool, val ...Value) error

                                                  SetAmbient attempts to set a specific Value bit to the state, enable. This function will return an error if insufficient permission is available to perform this task. The settings are performed in order and the function returns immediately an error is detected. Use GetAmbient() to unravel where things went wrong. Note, the cap package manages an abstraction IAB that captures all three inheritable vectors in a single type. Consider using that.

                                                  func SetGroups

                                                  func SetGroups(gid int, suppl ...int) error

                                                    SetGroups is a convenience function for robustly setting the GID and all other variants of GID (EGID etc) to the specified value, as well as setting all of the supplementary groups. This function will raise cap.SETGID in order to achieve this operation, and will completely lower the Effective Flag of the process Set before returning.

                                                    func SetUID

                                                    func SetUID(uid int) error

                                                      SetUID is a convenience function for robustly setting the UID and all other variants of UID (EUID etc) to the specified value without dropping the privilege of the current process. This function will raise cap.SETUID in order to achieve this operation, and will completely lower the Effective vector of the process before returning. Unlike the traditional method of dropping privilege when changing from [E]UID=0 to some other UID, this function only performs a change of UID cap.SETUID is available, and the action does not alter the Permitted Flag of the process' Set.

                                                      Types

                                                      type Flag

                                                      type Flag uint

                                                        Flag is the type of one of the three Value dimensions held in a Set. It is also used in the (*IAB).Fill() method for changing the Bounding and Ambient Vectors.

                                                        const (
                                                        	Effective Flag = iota
                                                        	Permitted
                                                        	Inheritable
                                                        )

                                                          Effective, Permitted, Inheritable are the three Flags of Values held in a Set.

                                                          func (Flag) String

                                                          func (f Flag) String() string

                                                            String identifies a Flag value by its conventional "e", "p" or "i" string abbreviation.

                                                            type IAB

                                                            type IAB struct {
                                                            	// contains filtered or unexported fields
                                                            }

                                                              IAB holds a summary of all of the inheritable capability vectors: Inh, Amb and Bound. The Bound vector is the logical inverse (two's complement) of the process' Bounding set. That is, raising a Value in the Bound (think blocked) vector is equivalent to dropping that Value from the process' Bounding set. This convention is used to support the empty IAB as being mostly harmless.

                                                              func IABFromText

                                                              func IABFromText(text string) (*IAB, error)

                                                                IABFromText parses a string representing an IAB, as generated by IAB.String(), to generate an IAB.

                                                                func IABGetProc

                                                                func IABGetProc() *IAB

                                                                  IABGetProc summarizes the Inh, Amb and Bound capabilty vectors of the current process.

                                                                  func IABInit

                                                                  func IABInit() *IAB

                                                                    IABInit returns an empty IAB.

                                                                    func (*IAB) Fill

                                                                    func (iab *IAB) Fill(vec Vector, c *Set, flag Flag) error

                                                                      Fill fills one of the Inh, Amb and Bound capability vectors from one of the flag vectors of a Set. Note, filling the Inh vector will mask the Amb vector, and filling the Amb vector may raise entries in the Inh vector. Further, when filling the Bound vector, the bits are inverted from what you might expect - that is lowered bits from the Set will be raised in the Bound vector.

                                                                      func (*IAB) GetVector

                                                                      func (iab *IAB) GetVector(vec Vector, val Value) (bool, error)

                                                                        GetVector returns the raised state of the specific capability bit of the indicated vector.

                                                                        func (*IAB) SetProc

                                                                        func (iab *IAB) SetProc() error

                                                                          SetProc attempts to change the Inheritable, Ambient and Bounding capabilty vectors of the current process using the content, iab. The Bounding vector strongly affects the potential for setting other bits, so this function carefully performs the the combined operation in the most flexible manner.

                                                                          func (*IAB) SetVector

                                                                          func (iab *IAB) SetVector(vec Vector, raised bool, vals ...Value) error

                                                                            SetVector sets all of the vals in the specified vector to the raised value. Note, the Ambient vector cannot contain values not raised in the Inh vector, so setting values directly in one vector may have the side effect of mirroring the value in the other vector to maintain this constraint. Note, raising a Bound vector bit is equivalent to lowering the Bounding vector of the process (when successfully applied with (*IAB).SetProc()).

                                                                            func (*IAB) String

                                                                            func (iab *IAB) String() string

                                                                              String serializes an IAB to a string format.

                                                                              type Launcher

                                                                              type Launcher struct {
                                                                              	// contains filtered or unexported fields
                                                                              }

                                                                                Launcher holds a configuration for executing an optional callback function and/or launching a child process with capability state different from the parent.

                                                                                Note, go1.10 is the earliest version of the Go toolchain that can support this abstraction.

                                                                                func FuncLauncher

                                                                                func FuncLauncher(fn func(interface{}) error) *Launcher

                                                                                  FuncLauncher returns a new launcher whose purpose is to only execute fn in a disposable security context. This is a more bare bones variant of the more elaborate program launcher returned by cap.NewLauncher().

                                                                                  The properties of fn are similar to those supplied via (*Launcher).Callback(fn) method. However, this launcher is bare bones because, when launching, all privilege management performed by the fn() is fully discarded when the fn() completes exection.

                                                                                  func NewLauncher

                                                                                  func NewLauncher(path string, args []string, env []string) *Launcher

                                                                                    NewLauncher returns a new launcher for the specified program path and args with the specified environment.

                                                                                    func (*Launcher) Callback

                                                                                    func (attr *Launcher) Callback(fn func(*syscall.ProcAttr, interface{}) error)

                                                                                      Callback changes the callback function for Launch() to call before changing privilege. The only thing that is assumed is that the OS thread in use to call this callback function at launch time will be the one that ultimately calls fork to complete the launch of a path specified executable. Any returned error value of said function will terminate the launch process.

                                                                                      A nil fn causes there to be no callback function invoked during a Launch() sequence - it will remove any pre-existing callback.

                                                                                      If the non-nil fn requires any effective capabilities in order to run, they can be raised prior to calling .Launch() or inside the callback function itself.

                                                                                      If the specified callback fn should call any "cap" package functions that change privilege state, these calls will only affect the launch goroutine itself. While the launch is in progress, other (non-launch) goroutines will block if they attempt to change privilege state. These routines will unblock once there are no in-flight launches.

                                                                                      Note, the first argument provided to the callback function is the *syscall.ProcAttr value to be used when a process launch is taking place. A non-nil structure pointer can be modified by the callback to enhance the launch. For example, the .Files field can be overriden to affect how the launched process' stdin/out/err are handled.

                                                                                      Further, the 2nd argument to the callback function is provided at Launch() invocation and can communicate contextual info to and from the callback and the main process.

                                                                                      func (*Launcher) Launch

                                                                                      func (attr *Launcher) Launch(data interface{}) (int, error)

                                                                                        Launch performs a callback function and/or new program launch with a disposable security state. The data object, when not nil, can be used to communicate with the callback. It can also be used to return details from the callback functions execution.

                                                                                        If the attr was created with NewLauncher(), this present function will return the pid of the launched process, or -1 and a non-nil error.

                                                                                        If the attr was created with FuncLauncher(), this present function will return 0, nil if the callback function exits without error. Otherwise it will return -1 and the non-nil error of the callback return value.

                                                                                        Note, while the disposable security state thread makes some oprerations seem more isolated - they are *not securely isolated*. Launching is inherently violating the POSIX semantics maintained by the rest of the "libcap/cap" package, so think of launching as a convenience wrapper around fork()ing.

                                                                                        Advanced user note: if the caller of this function thinks they know what they are doing by using runtime.LockOSThread() before invoking this function, they should understand that the OS Thread invoking (*Launcher).Launch() is *not guaranteed* to be the one used for the disposable security state to perform the launch. If said caller needs to run something on the disposable security state thread, they should do it via the launch callback function mechanism. (The Go runtime is complicated and this is why this Launch mechanism provides the optional callback function.)

                                                                                        func (*Launcher) SetChroot

                                                                                        func (attr *Launcher) SetChroot(root string)

                                                                                          SetChroot specifies the chroot value to be used by the launched command. An empty value means no-change from the prevailing value.

                                                                                          func (*Launcher) SetGroups

                                                                                          func (attr *Launcher) SetGroups(gid int, groups []int)

                                                                                            SetGroups specifies the GID and supplementary groups for the launched command.

                                                                                            func (*Launcher) SetIAB

                                                                                            func (attr *Launcher) SetIAB(iab *IAB)

                                                                                              SetIAB specifies the AIB capability vectors to be inherited by the launched command. A nil value means the prevailing vectors of the parent will be inherited.

                                                                                              func (*Launcher) SetMode

                                                                                              func (attr *Launcher) SetMode(mode Mode)

                                                                                                SetMode specifies the libcap Mode to be used by the launched command.

                                                                                                func (*Launcher) SetUID

                                                                                                func (attr *Launcher) SetUID(uid int)

                                                                                                  SetUID specifies the UID to be used by the launched command.

                                                                                                  type Mode

                                                                                                  type Mode uint

                                                                                                    Mode summarizes a complicated secure-bits and capability mode in a libcap preferred way.

                                                                                                    const (
                                                                                                    	ModeUncertain Mode = iota
                                                                                                    	ModeNoPriv
                                                                                                    	ModePure1EInit
                                                                                                    	ModePure1E
                                                                                                    )

                                                                                                      ModeUncertain etc are how libcap summarizes security modes involving capabilities and secure-bits.

                                                                                                      func GetMode

                                                                                                      func GetMode() Mode

                                                                                                        GetMode assesses the current process state and summarizes it as a Mode. This function always succeeds. Unfamiliar modes are declared ModeUncertain.

                                                                                                        func (Mode) Set

                                                                                                        func (m Mode) Set() error

                                                                                                          Set attempts to enter the specified mode. An attempt is made to enter the mode, so if you prefer this operation to be a no-op if entering the same mode, call only if CurrentMode() disagrees with the desired mode.

                                                                                                          This function will raise cap.SETPCAP in order to achieve this operation, and will completely lower the Effective Flag of the process' Set before returning. This function may fail for lack of permission or because (some of) the Secbits are already locked for the current process.

                                                                                                          func (Mode) String

                                                                                                          func (m Mode) String() string

                                                                                                            String returns the libcap conventional string for this mode.

                                                                                                            type Secbits

                                                                                                            type Secbits uint

                                                                                                              Secbits capture the prctl settable secure-bits of a process.

                                                                                                              const (
                                                                                                              	SecbitNoRoot Secbits = 1 << iota
                                                                                                              	SecbitNoRootLocked
                                                                                                              	SecbitNoSetUIDFixup
                                                                                                              	SecbitNoSetUIDFixupLocked
                                                                                                              	SecbitKeepCaps
                                                                                                              	SecbitKeepCapsLocked
                                                                                                              	SecbitNoCapAmbientRaise
                                                                                                              	SecbitNoCapAmbientRaiseLocked
                                                                                                              )

                                                                                                                SecbitNoRoot etc are the bitmasks associated with the supported Secbit masks. Source: uapi/linux/securebits.h

                                                                                                                func GetSecbits

                                                                                                                func GetSecbits() Secbits

                                                                                                                  GetSecbits returns the current setting of the process' Secbits.

                                                                                                                  func (Secbits) Set

                                                                                                                  func (s Secbits) Set() error

                                                                                                                    Set attempts to force the process Secbits to a value. This function will raise cap.SETPCAP in order to achieve this operation, and will completely lower the Effective vector of the process returning.

                                                                                                                    type Set

                                                                                                                    type Set struct {
                                                                                                                    	// contains filtered or unexported fields
                                                                                                                    }

                                                                                                                      Set is an opaque capabilities container for a set of system capbilities. It holds individually addressable capability Value's for the three capability Flag's. See GetFlag() and SetFlag() for how to adjust them individually, and Clear() and ClearFlag() for how to do bulk operations.

                                                                                                                      For admin tasks associated with managing namespace specific file capabilities, Set can also support a namespace-root-UID value which defaults to zero. See GetNSOwner() and SetNSOwner().

                                                                                                                      func FromText

                                                                                                                      func FromText(text string) (*Set, error)

                                                                                                                        FromText converts the canonical text representation for a Set into a freshly allocated Set.

                                                                                                                        The format follows the following pattern: a set of space separated sequences. Each sequence applies over the previous sequence to build up a Set. The format of a sequence is:

                                                                                                                        [comma list of cap_values][[ops][flags]]*
                                                                                                                        

                                                                                                                        Examples:

                                                                                                                        "all=ep"
                                                                                                                        "cap_chown,cap_setuid=ip cap_setuid+e"
                                                                                                                        "=p cap_setpcap-p+i"
                                                                                                                        

                                                                                                                        Here "all" refers to all named capabilities known to the hosting kernel, and "all" is assumed if no capabilities are listed before an "=".

                                                                                                                        The ops values, "=", "+" and "-" imply "reset and raise", "raise" and "lower" respectively. The "e", "i" and "p" characters correspond to the capabilities of the corresponding Flag: "e" (Effective); "i" (Inheritable); "p" (Permitted).

                                                                                                                        This syntax is overspecified and there are many ways of building the same final Set state. Any sequence that includes a '=' resets the accumulated state of all Flags ignoring earlier sequences. On each of the following lines we give three or more examples of ways to specify a common Set. The last entry on each line is the one generated by (*cap.Set).String() from that Set.

                                                                                                                        "=p all+ei"  "all=pie"   "=pi all+e"   "=eip"
                                                                                                                        
                                                                                                                        "cap_setuid=p cap_chown=i"  "cap_chown=ip-p"   "cap_chown=i"
                                                                                                                        
                                                                                                                        "cap_chown=-p"   "all="   "cap_setuid=pie-pie"   "="
                                                                                                                        

                                                                                                                        Note: FromText() is tested at release time to completely match the import ability of the libcap:cap_from_text() function.

                                                                                                                        func GetFd

                                                                                                                        func GetFd(file *os.File) (*Set, error)

                                                                                                                          GetFd returns the file capabilities of an open (*os.File).Fd().

                                                                                                                          func GetFile

                                                                                                                          func GetFile(path string) (*Set, error)

                                                                                                                            GetFile returns the file capabilities of a named file.

                                                                                                                            func GetPID

                                                                                                                            func GetPID(pid int) (*Set, error)

                                                                                                                              GetPID returns the capability set associated with the target process id; pid=0 is an alias for current.

                                                                                                                              func GetProc

                                                                                                                              func GetProc() *Set

                                                                                                                                GetProc returns the capability Set of the current process. If the kernel is unable to determine the Set associated with the current process, the function panic()s.

                                                                                                                                func Import

                                                                                                                                func Import(d []byte) (*Set, error)

                                                                                                                                  Import imports a Set from a byte array where it has been stored in a portable (lossless) way.

                                                                                                                                  func NewSet

                                                                                                                                  func NewSet() *Set

                                                                                                                                    NewSet returns an empty capability set.

                                                                                                                                    func (*Set) Clear

                                                                                                                                    func (c *Set) Clear() error

                                                                                                                                      Clear fully clears a capability set.

                                                                                                                                      func (*Set) ClearFlag

                                                                                                                                      func (c *Set) ClearFlag(vec Flag) error

                                                                                                                                        ClearFlag clears a specific vector of Values associated with the specified Flag.

                                                                                                                                        func (*Set) Compare

                                                                                                                                        func (c *Set) Compare(d *Set) (uint, error)

                                                                                                                                          Compare returns 0 if c and d are identical in content. Otherwise, this function returns a non-zero value of 3 independent bits: (differE ? 1:0) | (differP ? 2:0) | (differI ? 4:0). The Differs() function can be used to test for a difference in a specific Flag.

                                                                                                                                          func (*Set) Dup

                                                                                                                                          func (c *Set) Dup() (*Set, error)

                                                                                                                                            Dup returns a copy of the specified capability set.

                                                                                                                                            func (*Set) Export

                                                                                                                                            func (c *Set) Export() ([]byte, error)

                                                                                                                                              Export exports a Set into a lossless byte array format where it is stored in a portable way. Note, any namespace owner in the Set content is not exported by this function.

                                                                                                                                              func (*Set) GetFlag

                                                                                                                                              func (c *Set) GetFlag(vec Flag, val Value) (bool, error)

                                                                                                                                                GetFlag determines if the requested bit is enabled in the Flag vector of the capability Set.

                                                                                                                                                func (*Set) GetNSOwner

                                                                                                                                                func (c *Set) GetNSOwner() (int, error)

                                                                                                                                                  GetNSOwner returns the namespace owner UID of the capability Set.

                                                                                                                                                  func (*Set) SetFd

                                                                                                                                                  func (c *Set) SetFd(file *os.File) error

                                                                                                                                                    SetFd attempts to set the file capabilities of an open (*os.File).Fd(). This function can also be used to delete a file's capabilities, by calling with c = nil.

                                                                                                                                                    Note, Linux does not store the full Effective Value Flag in the metadata for the file. Only a single Effective bit is stored in this metadata. This single bit is non-zero if the Effective vector has any overlapping bits with the Permitted or Inheritable vector of c. This may appear suboptimal, but the reasoning behind it is sound. Namely, the purpose of the Effective bit it to support capabability unaware binaries that will only work if they magically launch with the needed bits already raised (this bit is sometimes referred to simply as the 'legacy' bit). Without *full* support for capability manipulation, as it is provided in this "../libcap/cap" package, this was the only way for Go programs to make use of file capabilities.

                                                                                                                                                    The preferred way a binary will actually manipulate its file-acquired capabilities is to carefully and deliberately use this package (or libcap, assisted by libpsx, for threaded C/C++ family code).

                                                                                                                                                    func (*Set) SetFile

                                                                                                                                                    func (c *Set) SetFile(path string) error

                                                                                                                                                      SetFile attempts to set the file capabilities of the specfied filename. This function can also be used to delete a file's capabilities, by calling with c = nil.

                                                                                                                                                      Note, see the comment for SetFd() for some non-obvious behavior of Linux for the Effective Value vector on the modified file.

                                                                                                                                                      func (*Set) SetFlag

                                                                                                                                                      func (c *Set) SetFlag(vec Flag, enable bool, val ...Value) error

                                                                                                                                                        SetFlag sets the requested bits to the indicated enable state. This function does not perform any security checks, so values can be set out-of-order. Only when the Set is used to SetProc() etc., will the bits be checked for validity and permission by the kernel. If the function returns an error, the Set will not be modified.

                                                                                                                                                        func (*Set) SetNSOwner

                                                                                                                                                        func (c *Set) SetNSOwner(uid int)

                                                                                                                                                          SetNSOwner adds an explicit namespace owner UID to the capability Set. This is only honored when generating file capabilities, and is generally for use by a setup process when installing binaries that use file capabilities to become capable inside a namespace to be administered by that UID. If capability aware code within that namespace writes file capabilities without explicitly setting such a UID, the kernel will fix-up the capabilities to be specific to that owner. In this way, the kernel prevents filesystem capabilities from leaking out of that restricted namespace.

                                                                                                                                                          func (*Set) SetProc

                                                                                                                                                          func (c *Set) SetProc() error

                                                                                                                                                            SetProc attempts to set the capability Set of the current process. The kernel will perform permission checks and an error will be returned if the attempt fails. Should the attempt fail no process capabilities will have been modified.

                                                                                                                                                            Note, the general behavior of this call is to set the process-shared capabilities. However, when called from a callback function as part of a (*Launcher).Launch(), the call only sets the capabilities of the thread being used to perform the launch.

                                                                                                                                                            func (*Set) String

                                                                                                                                                            func (c *Set) String() string

                                                                                                                                                              String converts a full capability Set into a single short readable string representation (which may contain spaces). See the cap.FromText() function for an explanation of its return values.

                                                                                                                                                              Note (*cap.Set).String() may evolve to generate more compact strings representing the a given Set over time, but it should maintain compatibility with the libcap:cap_to_text() function for any given release. Further, it will always be an inverse of cap.FromText().

                                                                                                                                                              type Value

                                                                                                                                                              type Value uint

                                                                                                                                                                Value is the type of a single capability (or permission) bit.

                                                                                                                                                                const (
                                                                                                                                                                	// CHOWN allows a process to arbitrarily change the user and
                                                                                                                                                                	// group ownership of a file.
                                                                                                                                                                	CHOWN Value = iota
                                                                                                                                                                
                                                                                                                                                                	// DAC_OVERRIDE allows a process to override of all Discretionary
                                                                                                                                                                	// Access Control (DAC) access, including ACL execute
                                                                                                                                                                	// access. That is read, write or execute files that the
                                                                                                                                                                	// process would otherwise not have access to. This
                                                                                                                                                                	// excludes DAC access covered by cap.LINUX_IMMUTABLE.
                                                                                                                                                                	DAC_OVERRIDE
                                                                                                                                                                
                                                                                                                                                                	// DAC_READ_SEARCH allows a process to override all DAC restrictions
                                                                                                                                                                	// limiting the read and search of files and
                                                                                                                                                                	// directories. This excludes DAC access covered by
                                                                                                                                                                	// cap.LINUX_IMMUTABLE.
                                                                                                                                                                	DAC_READ_SEARCH
                                                                                                                                                                
                                                                                                                                                                	// FOWNER allows a process to perform operations on files, even
                                                                                                                                                                	// where file owner ID should otherwise need be equal to
                                                                                                                                                                	// the UID, except where cap.FSETID is applicable. It
                                                                                                                                                                	// doesn't override MAC and DAC restrictions.
                                                                                                                                                                	FOWNER
                                                                                                                                                                
                                                                                                                                                                	// FSETID allows a process to set the S_ISUID and S_ISUID bits of
                                                                                                                                                                	// the file permissions, even when the process' effective
                                                                                                                                                                	// UID or GID/supplementary GIDs do not match that of the
                                                                                                                                                                	// file.
                                                                                                                                                                	FSETID
                                                                                                                                                                
                                                                                                                                                                	// KILL allows a process to sent a kill(2) signal to any other
                                                                                                                                                                	// process - overriding the limitation that there be a
                                                                                                                                                                	// [E]UID match between source and target process.
                                                                                                                                                                	KILL
                                                                                                                                                                
                                                                                                                                                                	// SETGID allows a process to freely manipulate its own GIDs:
                                                                                                                                                                	//   - arbitrarily set the GID, EGID, REGID, RESGID values
                                                                                                                                                                	//   - arbitrarily set the supplementary GIDs
                                                                                                                                                                	//   - allows the forging of GID credentials passed over a
                                                                                                                                                                	//     socket
                                                                                                                                                                	SETGID
                                                                                                                                                                
                                                                                                                                                                	// SETUID allows a process to freely manipulate its own UIDs:
                                                                                                                                                                	//   - arbitraily set the UID, EUID, REUID and RESUID
                                                                                                                                                                	//     values
                                                                                                                                                                	//   - allows the forging of UID credentials passed over a
                                                                                                                                                                	//     socket
                                                                                                                                                                	SETUID
                                                                                                                                                                
                                                                                                                                                                	// SETPCAP allows a process to freely manipulate its inheritable
                                                                                                                                                                	// capabilities.  Linux supports the POSIX.1e Inheritable
                                                                                                                                                                	// set, as well as Bounding and Ambient Linux extension
                                                                                                                                                                	// vectors. This capability permits dropping bits from the
                                                                                                                                                                	// Bounding vector. It also permits the process to raise
                                                                                                                                                                	// Ambient vector bits that are both raised in the
                                                                                                                                                                	// Permitted and Inheritable sets of the process. This
                                                                                                                                                                	// capability cannot be used to raise Permitted bits, or
                                                                                                                                                                	// Effective bits beyond those already present in the
                                                                                                                                                                	// process' permitted set.
                                                                                                                                                                	//
                                                                                                                                                                	// [Historical note: prior to the advent of file
                                                                                                                                                                	// capabilities (2008), this capability was suppressed by
                                                                                                                                                                	// default, as its unsuppressed behavior was not
                                                                                                                                                                	// auditable: it could asynchronously grant its own
                                                                                                                                                                	// Permitted capabilities to and remove capabilities from
                                                                                                                                                                	// other processes arbitraily. The former leads to
                                                                                                                                                                	// undefined behavior, and the latter is better served by
                                                                                                                                                                	// the kill system call.]
                                                                                                                                                                	SETPCAP
                                                                                                                                                                
                                                                                                                                                                	// LINUX_IMMUTABLE allows a process to modify the S_IMMUTABLE and
                                                                                                                                                                	// S_APPEND file attributes.
                                                                                                                                                                	LINUX_IMMUTABLE
                                                                                                                                                                
                                                                                                                                                                	// NET_BIND_SERVICE allows a process to bind to privileged ports:
                                                                                                                                                                	//   - TCP/UDP sockets below 1024
                                                                                                                                                                	//   - ATM VCIs below 32
                                                                                                                                                                	NET_BIND_SERVICE
                                                                                                                                                                
                                                                                                                                                                	// NET_BROADCAST allows a process to broadcast to the network and to
                                                                                                                                                                	// listen to multicast.
                                                                                                                                                                	NET_BROADCAST
                                                                                                                                                                
                                                                                                                                                                	// NET_ADMIN allows a process to perform network configuration
                                                                                                                                                                	// operations:
                                                                                                                                                                	//   - interface configuration
                                                                                                                                                                	//   - administration of IP firewall, masquerading and
                                                                                                                                                                	//     accounting
                                                                                                                                                                	//   - setting debug options on sockets
                                                                                                                                                                	//   - modification of routing tables
                                                                                                                                                                	//   - setting arbitrary process, and process group
                                                                                                                                                                	//     ownership on sockets
                                                                                                                                                                	//   - binding to any address for transparent proxying
                                                                                                                                                                	//     (this is also allowed via cap.NET_RAW)
                                                                                                                                                                	//   - setting TOS (Type of service)
                                                                                                                                                                	//   - setting promiscuous mode
                                                                                                                                                                	//   - clearing driver statistics
                                                                                                                                                                	//   - multicasing
                                                                                                                                                                	//   - read/write of device-specific registers
                                                                                                                                                                	//   - activation of ATM control sockets
                                                                                                                                                                	NET_ADMIN
                                                                                                                                                                
                                                                                                                                                                	// NET_RAW allows a process to use raw networking:
                                                                                                                                                                	//   - RAW sockets
                                                                                                                                                                	//   - PACKET sockets
                                                                                                                                                                	//   - binding to any address for transparent proxying
                                                                                                                                                                	//     (also permitted via cap.NET_ADMIN)
                                                                                                                                                                	NET_RAW
                                                                                                                                                                
                                                                                                                                                                	// IPC_LOCK allows a process to lock shared memory segments for IPC
                                                                                                                                                                	// purposes.  Also enables mlock and mlockall system
                                                                                                                                                                	// calls.
                                                                                                                                                                	IPC_LOCK
                                                                                                                                                                
                                                                                                                                                                	// IPC_OWNER allows a process to override IPC ownership checks.
                                                                                                                                                                	IPC_OWNER
                                                                                                                                                                
                                                                                                                                                                	// SYS_MODULE allows a process to initiate the loading and unloading
                                                                                                                                                                	// of kernel modules. This capability can effectively
                                                                                                                                                                	// modify kernel without limit.
                                                                                                                                                                	SYS_MODULE
                                                                                                                                                                
                                                                                                                                                                	// SYS_RAWIO allows a process to perform raw IO:
                                                                                                                                                                	//   - permit ioper/iopl access
                                                                                                                                                                	//   - permit sending USB messages to any device via
                                                                                                                                                                	//     /dev/bus/usb
                                                                                                                                                                	SYS_RAWIO
                                                                                                                                                                
                                                                                                                                                                	// SYS_CHROOT allows a process to perform a chroot syscall to change
                                                                                                                                                                	// the effective root of the process' file system:
                                                                                                                                                                	// redirect to directory "/" to some other location.
                                                                                                                                                                	SYS_CHROOT
                                                                                                                                                                
                                                                                                                                                                	// SYS_PTRACE allows a process to perform a ptrace() of any other
                                                                                                                                                                	// process.
                                                                                                                                                                	SYS_PTRACE
                                                                                                                                                                
                                                                                                                                                                	// SYS_PACCT allows a process to configure process accounting.
                                                                                                                                                                	SYS_PACCT
                                                                                                                                                                
                                                                                                                                                                	// SYS_ADMIN allows a process to perform a somewhat arbitrary
                                                                                                                                                                	// grab-bag of privileged operations. Over time, this
                                                                                                                                                                	// capability should weaken as specific capabilities are
                                                                                                                                                                	// created for subsets of cap.SYS_ADMINs functionality:
                                                                                                                                                                	//   - configuration of the secure attention key
                                                                                                                                                                	//   - administration of the random device
                                                                                                                                                                	//   - examination and configuration of disk quotas
                                                                                                                                                                	//   - setting the domainname
                                                                                                                                                                	//   - setting the hostname
                                                                                                                                                                	//   - calling bdflush()
                                                                                                                                                                	//   - mount() and umount(), setting up new SMB connection
                                                                                                                                                                	//   - some autofs root ioctls
                                                                                                                                                                	//   - nfsservctl
                                                                                                                                                                	//   - VM86_REQUEST_IRQ
                                                                                                                                                                	//   - to read/write pci config on alpha
                                                                                                                                                                	//   - irix_prctl on mips (setstacksize)
                                                                                                                                                                	//   - flushing all cache on m68k (sys_cacheflush)
                                                                                                                                                                	//   - removing semaphores
                                                                                                                                                                	//   - Used instead of cap.CHOWN to "chown" IPC message
                                                                                                                                                                	//     queues, semaphores and shared memory
                                                                                                                                                                	//   - locking/unlocking of shared memory segment
                                                                                                                                                                	//   - turning swap on/off
                                                                                                                                                                	//   - forged pids on socket credentials passing
                                                                                                                                                                	//   - setting readahead and flushing buffers on block
                                                                                                                                                                	//     devices
                                                                                                                                                                	//   - setting geometry in floppy driver
                                                                                                                                                                	//   - turning DMA on/off in xd driver
                                                                                                                                                                	//   - administration of md devices (mostly the above, but
                                                                                                                                                                	//     some extra ioctls)
                                                                                                                                                                	//   - tuning the ide driver
                                                                                                                                                                	//   - access to the nvram device
                                                                                                                                                                	//   - administration of apm_bios, serial and bttv (TV)
                                                                                                                                                                	//     device
                                                                                                                                                                	//   - manufacturer commands in isdn CAPI support driver
                                                                                                                                                                	//   - reading non-standardized portions of PCI
                                                                                                                                                                	//     configuration space
                                                                                                                                                                	//   - DDI debug ioctl on sbpcd driver
                                                                                                                                                                	//   - setting up serial ports
                                                                                                                                                                	//   - sending raw qic-117 commands
                                                                                                                                                                	//   - enabling/disabling tagged queuing on SCSI
                                                                                                                                                                	//     controllers and sending arbitrary SCSI commands
                                                                                                                                                                	//   - setting encryption key on loopback filesystem
                                                                                                                                                                	//   - setting zone reclaim policy
                                                                                                                                                                	SYS_ADMIN
                                                                                                                                                                
                                                                                                                                                                	// SYS_BOOT allows a process to initiate a reboot of the system.
                                                                                                                                                                	SYS_BOOT
                                                                                                                                                                
                                                                                                                                                                	// SYS_NICE allows a process to maipulate the execution priorities
                                                                                                                                                                	// of arbitrary processes:
                                                                                                                                                                	//   - those involving different UIDs
                                                                                                                                                                	//   - setting their CPU affinity
                                                                                                                                                                	//   - alter the FIFO vs. round-robin (realtime)
                                                                                                                                                                	//     scheduling for itself and other processes.
                                                                                                                                                                	SYS_NICE
                                                                                                                                                                
                                                                                                                                                                	// SYS_RESOURCE allows a process to adjust resource related parameters
                                                                                                                                                                	// of processes and the system:
                                                                                                                                                                	//   - set and override resource limits
                                                                                                                                                                	//   - override quota limits
                                                                                                                                                                	//   - override the reserved space on ext2 filesystem
                                                                                                                                                                	//     (this can also be achieved via cap.FSETID)
                                                                                                                                                                	//   - modify the data journaling mode on ext3 filesystem,
                                                                                                                                                                	//     which uses journaling resources
                                                                                                                                                                	//   - override size restrictions on IPC message queues
                                                                                                                                                                	//   - configure more than 64Hz interrupts from the
                                                                                                                                                                	//     real-time clock
                                                                                                                                                                	//   - override the maximum number of consoles for console
                                                                                                                                                                	//     allocation
                                                                                                                                                                	//   - override the maximum number of keymaps
                                                                                                                                                                	//
                                                                                                                                                                	//
                                                                                                                                                                	SYS_RESOURCE
                                                                                                                                                                
                                                                                                                                                                	// SYS_TIME allows a process to perform time manipulation of clocks:
                                                                                                                                                                	//   - alter the system clock
                                                                                                                                                                	//   - enable irix_stime on MIPS
                                                                                                                                                                	//   - set the real-time clock
                                                                                                                                                                	SYS_TIME
                                                                                                                                                                
                                                                                                                                                                	// SYS_TTY_CONFIG allows a process to manipulate tty devices:
                                                                                                                                                                	//   - configure tty devices
                                                                                                                                                                	//   - perform vhangup() of a tty
                                                                                                                                                                	SYS_TTY_CONFIG
                                                                                                                                                                
                                                                                                                                                                	// MKNOD allows a process to perform privileged operations with
                                                                                                                                                                	// the mknod() system call.
                                                                                                                                                                	MKNOD
                                                                                                                                                                
                                                                                                                                                                	// LEASE allows a process to take leases on files.
                                                                                                                                                                	LEASE
                                                                                                                                                                
                                                                                                                                                                	// AUDIT_WRITE allows a process to write to the audit log via a
                                                                                                                                                                	// unicast netlink socket.
                                                                                                                                                                	AUDIT_WRITE
                                                                                                                                                                
                                                                                                                                                                	// AUDIT_CONTROL allows a process to configure audit logging via a
                                                                                                                                                                	// unicast netlink socket.
                                                                                                                                                                	AUDIT_CONTROL
                                                                                                                                                                
                                                                                                                                                                	// SETFCAP allows a process to set capabilities on files.
                                                                                                                                                                	SETFCAP
                                                                                                                                                                
                                                                                                                                                                	// MAC_OVERRIDE allows a process to override Manditory Access Control
                                                                                                                                                                	// (MAC) access. Not all kernels are configured with a MAC
                                                                                                                                                                	// mechanism, but this is the capability reserved for
                                                                                                                                                                	// overriding them.
                                                                                                                                                                	MAC_OVERRIDE
                                                                                                                                                                
                                                                                                                                                                	// MAC_ADMIN allows a process to configure the Mandatory Access
                                                                                                                                                                	// Control (MAC) policy. Not all kernels are configured
                                                                                                                                                                	// with a MAC enabled, but if they are this capability is
                                                                                                                                                                	// reserved for code to perform administration tasks.
                                                                                                                                                                	MAC_ADMIN
                                                                                                                                                                
                                                                                                                                                                	// SYSLOG allows a process to configure the kernel's syslog
                                                                                                                                                                	// (printk) behavior.
                                                                                                                                                                	SYSLOG
                                                                                                                                                                
                                                                                                                                                                	// WAKE_ALARM allows a process to trigger something that can wake the
                                                                                                                                                                	// system up.
                                                                                                                                                                	WAKE_ALARM
                                                                                                                                                                
                                                                                                                                                                	// BLOCK_SUSPEND allows a process to block system suspends - prevent the
                                                                                                                                                                	// system from entering a lower power state.
                                                                                                                                                                	BLOCK_SUSPEND
                                                                                                                                                                
                                                                                                                                                                	// AUDIT_READ allows a process to read the audit log via a multicast
                                                                                                                                                                	// netlink socket.
                                                                                                                                                                	AUDIT_READ
                                                                                                                                                                
                                                                                                                                                                	// PERFMON allows a process to enable observability of privileged
                                                                                                                                                                	// operations related to performance. The mechanisms
                                                                                                                                                                	// include perf_events, i915_perf and other kernel
                                                                                                                                                                	// subsystems.
                                                                                                                                                                	PERFMON
                                                                                                                                                                
                                                                                                                                                                	// BPF allows a process to manipulate aspects of the kernel
                                                                                                                                                                	// enhanced Berkeley Packet Filter (BPF) system. This is
                                                                                                                                                                	// an execution subsystem of the kernel, that manages BPF
                                                                                                                                                                	// programs. cap.BPF permits a process to:
                                                                                                                                                                	//   - create all types of BPF maps
                                                                                                                                                                	//   - advanced verifier features:
                                                                                                                                                                	//     - indirect variable access
                                                                                                                                                                	//     - bounded loops
                                                                                                                                                                	//     - BPF to BPF function calls
                                                                                                                                                                	//     - scalar precision tracking
                                                                                                                                                                	//     - larger complexity limits
                                                                                                                                                                	//     - dead code elimination
                                                                                                                                                                	//     - potentially other features
                                                                                                                                                                	//
                                                                                                                                                                	// Other capabilities can be used together with cap.BFP to
                                                                                                                                                                	// further manipulate the BPF system:
                                                                                                                                                                	//   - cap.PERFMON relaxes the verifier checks as follows:
                                                                                                                                                                	//     - BPF programs can use pointer-to-integer
                                                                                                                                                                	//       conversions
                                                                                                                                                                	//     - speculation attack hardening measures can be
                                                                                                                                                                	//       bypassed
                                                                                                                                                                	//     - bpf_probe_read to read arbitrary kernel memory is
                                                                                                                                                                	//       permitted
                                                                                                                                                                	//     - bpf_trace_printk to print the content of kernel
                                                                                                                                                                	//       memory
                                                                                                                                                                	//   - cap.SYS_ADMIN permits the following:
                                                                                                                                                                	//     - use of bpf_probe_write_user
                                                                                                                                                                	//     - iteration over the system-wide loaded programs,
                                                                                                                                                                	//       maps, links BTFs and convert their IDs to file
                                                                                                                                                                	//       descriptors.
                                                                                                                                                                	//   - cap.PERFMON is required to load tracing programs.
                                                                                                                                                                	//   - cap.NET_ADMIN is required to load networking
                                                                                                                                                                	//     programs.
                                                                                                                                                                	BPF
                                                                                                                                                                
                                                                                                                                                                	// CHECKPOINT_RESTORE allows a process to perform checkpoint
                                                                                                                                                                	// and restore operations. Also permits
                                                                                                                                                                	// explicit PID control via clone3() and
                                                                                                                                                                	// also writing to ns_last_pid.
                                                                                                                                                                	CHECKPOINT_RESTORE
                                                                                                                                                                )

                                                                                                                                                                  CHOWN etc., are the named capability values of the Linux kernel. The canonical source for each name is the "uapi/linux/capabilities.h" file. Some values may not be available (yet) where the kernel is older. The actual number of capabities supported by the running kernel can be obtained using the cap.MaxBits() function.

                                                                                                                                                                  func FromName

                                                                                                                                                                  func FromName(name string) (Value, error)

                                                                                                                                                                    FromName converts a named capability Value to its binary representation.

                                                                                                                                                                    func MaxBits

                                                                                                                                                                    func MaxBits() Value

                                                                                                                                                                      MaxBits returns the number of kernel-named capabilities discovered at runtime in the current system.

                                                                                                                                                                      func (Value) String

                                                                                                                                                                      func (v Value) String() string

                                                                                                                                                                        String converts a capability Value into its canonical text representation.

                                                                                                                                                                        type Vector

                                                                                                                                                                        type Vector uint

                                                                                                                                                                          Vector enumerates which of the inheritable IAB capability vectors is being manipulated.

                                                                                                                                                                          const (
                                                                                                                                                                          	Inh Vector = iota
                                                                                                                                                                          	Amb
                                                                                                                                                                          	Bound
                                                                                                                                                                          )

                                                                                                                                                                            Inh, Amb, Bound enumerate the IAB vector components. (Vector) Inh is equivalent to (Flag) Inheritable. They are named differently for syntax/type checking reasons.

                                                                                                                                                                            func (Vector) String

                                                                                                                                                                            func (v Vector) String() string

                                                                                                                                                                              String identifies a Vector value by its conventional I A or B string abbreviation.