libcap/cap Go package documentation cleanup.

Signed-off-by: Andrew G. Morgan <morgan@kernel.org>

6 files changed, 45 insertions, 23 deletions

diff --git a/cap/cap.go b/cap/cap.go
index 21c286b..cb9511f 100644
--- a/cap/cap.go
+++ b/cap/cap.go
@@ -13,8 +13,9 @@
 // described in that paper as well as supporting subsequent changes to
 // the kernel for other styles of inheritable Capability.
 //
-// See https://sites.google.com/site/fullycapable/ for recent updates
-// and information on how to file bugs.
+// See https://sites.google.com/site/fullycapable/ for recent updates,
+// some walk-through examples of ways of using 'cap.Set's etc and
+// information on how to file bugs.
 //
 // For CGo linked binaries, behind the scenes, the package
 // "kernel.org/pub/linux/libs/security/libcap/psx" is used to perform
@@ -45,10 +46,13 @@ import (
 // Value is the type of a single capability (or permission) bit.
 type Value uint
 
-// Flag is the type of one of the three Value vectors held in a Set.
+// Flag is the type of one of the three Value dimensions held in a Set.
+// It is also used in the API for changing the Bounding and Ambient Vectors.
+// For these, in addition to direct manipulation of these vectors see the
+// package supports an IAB abstraction.
 type Flag uint
 
-// Effective, Permitted, Inheritable are the three vectors of Values
+// Effective, Permitted, Inheritable are the three dimensions of Values
 // held in a Set.
 const (
 	Effective Flag = iota
@@ -90,7 +94,7 @@ var (
 	magic uint32
 
 	// words holds the number of uint32's associated with each
-	// capability vector for this session.
+	// capability dimension for this session.
 	words int
 
 	// maxValues holds the number of bit values that are named by
@@ -289,9 +293,10 @@ func (sc *syscaller) setProc(c *Set) error {
 	return sc.capwcall(syscall.SYS_CAPSET, &header{magic: magic}, c.flat)
 }
 
-// SetProc attempts to write the capability Set to the current
+// 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.
+// will be returned if the attempt fails. Should the attempt fail
+// no process capabilities will have been modified.
 func (c *Set) SetProc() error {
 	scwMu.Lock()
 	defer scwMu.Unlock()
@@ -329,11 +334,11 @@ func (sc *syscaller) dropBound(val ...Value) error {
 // 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 vector). 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
+// 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
-// from on error using GetBound().
+// using GetBound().
 func DropBound(val ...Value) error {
 	scwMu.Lock()
 	defer scwMu.Unlock()
@@ -400,8 +405,11 @@ func (sc *syscaller) 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. This is a workaround for situations
-// where the Ambient API is locked.
+// 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 by the
+// kernel.
 func ResetAmbient() error {
 	scwMu.Lock()
 	defer scwMu.Unlock()
diff --git a/cap/convenience.go b/cap/convenience.go
index 85c2a21..54e64c6 100644
--- a/cap/convenience.go
+++ b/cap/convenience.go
@@ -172,8 +172,10 @@ func (sc *syscaller) setMode(m Mode) error {
 // the desired mode.
 //
 // This function will raise cap.SETPCAP in order to achieve this
-// operation, and will completely lower the Effective vector of the
-// process before returning.
+// operation, and will completely lower the Effective dimension of
+// the process's 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 (m Mode) Set() error {
 	scwMu.Lock()
 	defer scwMu.Unlock()
@@ -226,7 +228,11 @@ func (sc *syscaller) setUID(uid int) error {
 // 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.
+// 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 dimension of the process' Set.
 func SetUID(uid int) error {
 	scwMu.Lock()
 	defer scwMu.Unlock()
@@ -273,7 +279,8 @@ func (sc *syscaller) setGroups(gid int, suppl []int) error {
 // 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 vector of the process before returning.
+// completely lower the Effective dimension of the process Set before
+// returning.
 func SetGroups(gid int, suppl ...int) error {
 	scwMu.Lock()
 	defer scwMu.Unlock()
diff --git a/cap/file.go b/cap/file.go
index 94dfa42..b6dc254 100644
--- a/cap/file.go
+++ b/cap/file.go
@@ -204,7 +204,7 @@ func (c *Set) packFileCap() ([]byte, error) {
 // (*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 vector in the
+// Note, Linux does not store the full Effective Value dimension in the
 // metadata for the file. Only a single Effective bit is stored in
 // this metadata. This single bit is non-zero if the Permitted vector
 // has any overlapping bits with the Effective or Inheritable vector
@@ -217,9 +217,9 @@ func (c *Set) packFileCap() ([]byte, error) {
 // this was the only way for Go programs to make use of capabilities.
 //
 // The preferred way a binary will actually manipulate its
-// file-acquired capabilities is carefully and deliberately using this
-// package (or libcap, assisted by libpsx, for threaded C/C++ family
-// code).
+// file-acquired capabilities is to carefully and deliberately using
+// this package (or libcap, assisted by libpsx, for threaded C/C++
+// family code).
 func (c *Set) SetFd(file *os.File) error {
 	if c == nil {
 		if _, _, err := multisc.r6(syscall.SYS_FREMOVEXATTR, uintptr(file.Fd()), uintptr(unsafe.Pointer(xattrNameCaps)), 0, 0, 0, 0); err != 0 {
diff --git a/cap/flags.go b/cap/flags.go
index d19d0c2..b800a2d 100644
--- a/cap/flags.go
+++ b/cap/flags.go
@@ -133,7 +133,8 @@ func (c *Set) ClearFlag(vec Flag) 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).
+// (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 (c *Set) Compare(d *Set) (uint, error) {
 	if c == nil || len(c.flat) == 0 || d == nil || len(d.flat) == 0 {
 		return 0, ErrBadSet
diff --git a/cap/iab.go b/cap/iab.go
index 4da4c61..e4c2ad6 100644
--- a/cap/iab.go
+++ b/cap/iab.go
@@ -173,7 +173,10 @@ func (sc *syscaller) iabSetProc(iab *IAB) (err error) {
 }
 
 // SetProc attempts to change the Inheritable, Ambient and Bounding
-// capabilty vectors of the current process.
+// capabilty vectors of the current process. The Bounding vector strongly
+// affects the potential for setting other bits, so this function
+// carefully performs the the combined operation in the most flexible
+// order.
 func (iab *IAB) SetProc() error {
 	scwMu.Lock()
 	defer scwMu.Unlock()
diff --git a/cap/launch.go b/cap/launch.go
index 3d9c81b..90aec85 100644
--- a/cap/launch.go
+++ b/cap/launch.go
@@ -11,6 +11,9 @@ import (
 // Launcher holds a configuration for launching a child process with
 // capability state different from (generally more restricted than)
 // the parent.
+//
+// Note, go1.10 is the earliest version of the Go toolchain that can
+// support this abstraction.
 type Launcher struct {
 	path string
 	args []string