Mode cap package documentation updates.
Signed-off-by: Andrew G. Morgan <morgan@kernel.org>
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 @@
// 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 @@
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 @@
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 @@
// 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 @@
// 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 @@
// 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 @@
// 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 @@
// (*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 @@
// 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 @@
/* ** 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 @@
// 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 @@
// 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 @@
/* ** 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 (
