Mode cap package documentation updates.psx/v0.2.42-rc1cap/v0.2.42-rc1

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

8 files changed, 88 insertions, 24 deletions

diff --git a/cap/cap.go b/cap/cap.go
index b9838c9..e00affe 100644
--- a/cap/cap.go
+++ b/cap/cap.go
@@ -13,9 +13,28 @@
 // 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 cap.Differs(now.Compare(empty)) {
+//       log.Fatalf("failed to fully drop privilege: have=%q, wanted=%q", now, empty)
+//   }
+//
 // 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.
+// some more complete 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
@@ -23,16 +42,20 @@
 // uniformly over the whole Go (and CGo linked) process runtime.
 //
 // Note, if the Go runtime syscall interface contains the linux
-// variant syscall.AllThreadsSyscall() API (it is not in go1.15beta1
+// variant syscall.AllThreadsSyscall() API (it is not in go1.15rc1
 // for example, but see https://github.com/golang/go/issues/1435 for
 // current status) then this present package can use that to invoke
-// Capability setting system calls for pure Go binaries. In such an
+// Capability setting system calls in pure Go binaries. In such an
 // enhanced Go runtime, to force this behavior, use the CGO_ENABLED=0
 // environment variable and, for now, a build tag:
 //
 //   CGO_ENABLED=0 go build -tags allthreadssyscall ...
 //
+// ------------------------------------------------------------------
 // Copyright (c) 2019,20 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.
 package cap // import "kernel.org/pub/linux/libs/security/libcap/cap"
 
 import (
@@ -51,7 +74,7 @@ type Value uint
 // Bounding and Ambient Vectors.
 type Flag uint
 
-// Effective, Permitted, Inheritable are the three dimensions of Values
+// Effective, Permitted, Inheritable are the three Flags of Values
 // held in a Set.
 const (
 	Effective Flag = iota
@@ -79,7 +102,14 @@ func (f Flag) String() string {
 type data [Inheritable + 1]uint32
 
 // Set is an opaque capabilities container for a set of system
-// capbilities.
+// 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().
 type Set struct {
 	// mu protects all other members of a Set.
 	mu sync.RWMutex
@@ -108,7 +138,7 @@ var (
 	magic uint32
 
 	// words holds the number of uint32's associated with each
-	// capability dimension for this session.
+	// capability Flag for this session.
 	words int
 
 	// maxValues holds the number of bit values that are named by
diff --git a/cap/convenience.go b/cap/convenience.go
index 6498241..f094e52 100644
--- a/cap/convenience.go
+++ b/cap/convenience.go
@@ -172,7 +172,7 @@ 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 dimension of the
+// 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.
@@ -229,10 +229,10 @@ func (sc *syscaller) setUID(uid int) error {
 // 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
+// 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.
+// does not alter the Permitted Flag of the process' Set.
 func SetUID(uid int) error {
 	scwMu.Lock()
 	defer scwMu.Unlock()
@@ -279,7 +279,7 @@ 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 dimension of the process Set before
+// completely lower the Effective Flag of the process Set before
 // returning.
 func SetGroups(gid int, suppl ...int) error {
 	scwMu.Lock()
diff --git a/cap/file.go b/cap/file.go
index e5d6d5f..a3695b0 100644
--- a/cap/file.go
+++ b/cap/file.go
@@ -52,11 +52,18 @@ type vfsCaps3 struct {
 
 // ErrBadSize indicates the the loaded file capability has
 // an invalid number of bytes in it.
-var (
-	ErrBadSize  = errors.New("filecap bad size")
-	ErrBadMagic = errors.New("unsupported magic")
-	ErrBadPath  = errors.New("file is not a regular executable")
-)
+var ErrBadSize = errors.New("filecap bad size")
+
+// 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.
+var ErrBadMagic = errors.New("unsupported magic")
+
+// ErrBadPath indicates a failed attempt to set a file capability on
+// an irregular (non-executable) file.
+var ErrBadPath = errors.New("file is not a regular executable")
 
 // digestFileCap unpacks a file capability and returns it in a *Set
 // form.
@@ -219,7 +226,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 dimension in the
+// 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 Permitted vector
 // has any overlapping bits with the Effective or Inheritable vector
@@ -228,8 +235,9 @@ func (c *Set) packFileCap() ([]byte, error) {
 // 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 cap package,
-// this was the only way for Go programs to make use of capabilities.
+// capability manipulation, as it is provided in this "../libcap/cap"
+// package, 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 to carefully and deliberately using
diff --git a/cap/names.go b/cap/names.go
index 066fd70..d466719 100644
--- a/cap/names.go
+++ b/cap/names.go
@@ -2,13 +2,23 @@ package cap
 
 /* ** DO NOT EDIT THIS FILE. IT WAS AUTO-GENERATED BY LIBCAP'S GO BUILDER (mknames.go) ** */
 
-// NamedCount holds the number of capabilities with official names.
+// NamedCount holds the number of capability values with official
+// names at the time this libcap version, this package is part of, 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 kernel like this.
 const NamedCount = 40
 
 // CHOWN etc., are the named capability values of the Linux kernel. The
 // canonical source for each name is the "uapi/linux/capabilities.h"
 // file, a snapshot (from kernel.org) is hard-coded into this package.
 // 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.
 const (
 	// CHOWN allows a process to arbitrarily change the user and
 	// group ownership of a file.
diff --git a/cap/oslockluster.go b/cap/oslockluster.go
index 73aeb9e..0b2cf2e 100644
--- a/cap/oslockluster.go
+++ b/cap/oslockluster.go
@@ -19,7 +19,8 @@ import "syscall"
 //   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.
+// 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).
diff --git a/cap/oslocks.go b/cap/oslocks.go
index 6d57333..9754020 100644
--- a/cap/oslocks.go
+++ b/cap/oslocks.go
@@ -19,7 +19,8 @@ import "syscall"
 //   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.
+// 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).
diff --git a/go/mknames.go b/go/mknames.go
index b048e10..754d2f8 100644
--- a/go/mknames.go
+++ b/go/mknames.go
@@ -52,13 +52,23 @@ func main() {
 
 /* ** DO NOT EDIT THIS FILE. IT WAS AUTO-GENERATED BY LIBCAP'S GO BUILDER (mknames.go) ** */
 
-// NamedCount holds the number of capabilities with official names.
+// NamedCount holds the number of capability values with official
+// names at the time this libcap version, this package is part of, 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 kernel like this.
 const NamedCount = `, len(list), `
 
 // CHOWN etc., are the named capability values of the Linux kernel. The
 // canonical source for each name is the "uapi/linux/capabilities.h"
 // file, a snapshot (from kernel.org) is hard-coded into this package.
 // 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.
 const (
 `)
 	bits := make(map[string]string)
diff --git a/psx/psx.go b/psx/psx.go
index d46c2c3..7075362 100644
--- a/psx/psx.go
+++ b/psx/psx.go
@@ -35,7 +35,11 @@
 //
 //    export CGO_LDFLAGS_ALLOW="-Wl,-?-wrap[=,][^-.@][^,]*"
 //
+// ------------------------------------------------------------------
 // Copyright (c) 2019,20 Andrew G. Morgan <morgan@kernel.org>
+//
+// The psx package is licensed with a (you choose) BSD 3-clause or
+// GPL2. See LICENSE file for details.
 package psx // import "kernel.org/pub/linux/libs/security/libcap/psx"
 
 import (