auth

package
v0.0.0-...-ba09d25 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Dec 29, 2021 License: Apache-2.0, MIT Imports: 6 Imported by: 0

Documentation

Overview

Package auth implements an access control model that is a subset of Linux's.

The auth package supports two kinds of access controls: user/group IDs and capabilities. Each resource in the security model is associated with a user namespace; "privileged" operations check that the operator's credentials have the required user/group IDs or capabilities within the user namespace of accessed resources.

Index

Constants

View Source
const (
	// CtxCredentials is a Context.Value key for Credentials.
	CtxCredentials contextID = iota

	// CtxThreadGroupID is the current thread group ID when a context represents
	// a task context. The value is represented as an int32.
	CtxThreadGroupID contextID = iota
)
View Source
const (
	// NoID is uint32(-1). -1 is consistently used as a special value, in Linux
	// and by extension in the auth package, to mean "no ID":
	//
	// - ID mapping returns -1 if the ID is not mapped.
	//
	// - Most set*id() syscalls accept -1 to mean "do not change this ID".
	NoID = math.MaxUint32

	// OverflowUID is the default value of /proc/sys/kernel/overflowuid. The
	// "overflow UID" is usually [1] used when translating a user ID between
	// namespaces fails because the ID is not mapped. (We don't implement this
	// file, so the overflow UID is constant.)
	//
	// [1] "There is one notable case where unmapped user and group IDs are not
	// converted to the corresponding overflow ID value. When viewing a uid_map
	// or gid_map file in which there is no mapping for the second field, that
	// field is displayed as 4294967295 (-1 as an unsigned integer);" -
	// user_namespaces(7)
	OverflowUID = UID(65534)

	// OverflowGID is the group equivalent to OverflowUID.
	OverflowGID = GID(65534)

	// NobodyKUID is the user ID usually reserved for the least privileged user
	// "nobody".
	NobodyKUID = KUID(65534)

	// NobodyKGID is the group equivalent to NobodyKUID.
	NobodyKGID = KGID(65534)

	// RootKUID is the user ID usually used for the most privileged user "root".
	RootKUID = KUID(0)

	// RootKGID is the group equivalent to RootKUID.
	RootKGID = KGID(0)

	// RootUID is the root user.
	RootUID = UID(0)

	// RootGID is the root group.
	RootGID = GID(0)
)

Variables

View Source
var AllCapabilities = CapabilitySetOf(linux.CAP_LAST_CAP+1) - 1

AllCapabilities is a CapabilitySet containing all valid capabilities.

Functions

func ContextWithCredentials

func ContextWithCredentials(ctx context.Context, creds *Credentials) context.Context

ContextWithCredentials returns a copy of ctx carrying creds.

func ThreadGroupIDFromContext

func ThreadGroupIDFromContext(ctx context.Context) (tgid int32, ok bool)

ThreadGroupIDFromContext returns the current thread group ID when ctx represents a task context.

Types

type CapabilitySet

type CapabilitySet uint64

A CapabilitySet is a set of capabilities implemented as a bitset. The zero value of CapabilitySet is a set containing no capabilities.

func CapabilitySetOf

func CapabilitySetOf(cp linux.Capability) CapabilitySet

CapabilitySetOf returns a CapabilitySet containing only the given capability.

func CapabilitySetOfMany

func CapabilitySetOfMany(cps []linux.Capability) CapabilitySet

CapabilitySetOfMany returns a CapabilitySet containing the given capabilities.

type Credentials

type Credentials struct {
	// Real/effective/saved user/group IDs in the root user namespace. None of
	// these should ever be NoID.
	RealKUID      KUID
	EffectiveKUID KUID
	SavedKUID     KUID
	RealKGID      KGID
	EffectiveKGID KGID
	SavedKGID     KGID

	// Supplementary groups used by set/getgroups.
	//
	// ExtraKGIDs slices are immutable, allowing multiple Credentials with the
	// same ExtraKGIDs to share the same slice.
	ExtraKGIDs []KGID

	// The capability sets applicable to this set of credentials.
	PermittedCaps   CapabilitySet
	InheritableCaps CapabilitySet
	EffectiveCaps   CapabilitySet
	BoundingCaps    CapabilitySet

	// KeepCaps is the flag for PR_SET_KEEPCAPS which allow capabilities to be
	// maintained after a switch from root user to non-root user via setuid().
	KeepCaps bool

	// The user namespace associated with the owner of the credentials.
	UserNamespace *UserNamespace
}

Credentials contains information required to authorize privileged operations in a user namespace.

+stateify savable

func CredentialsFromContext

func CredentialsFromContext(ctx context.Context) *Credentials

CredentialsFromContext returns a copy of the Credentials used by ctx, or a set of Credentials with no capabilities if ctx does not have Credentials.

func NewAnonymousCredentials

func NewAnonymousCredentials() *Credentials

NewAnonymousCredentials returns a set of credentials with no capabilities in any user namespace.

func NewRootCredentials

func NewRootCredentials(ns *UserNamespace) *Credentials

NewRootCredentials returns a set of credentials with KUID and KGID 0 (i.e. global root) in user namespace ns.

func NewUserCredentials

func NewUserCredentials(kuid KUID, kgid KGID, extraKGIDs []KGID, capabilities *TaskCapabilities, ns *UserNamespace) *Credentials

NewUserCredentials returns a set of credentials based on the given UID, GIDs, and capabilities in a given namespace. If all arguments are their zero values, this returns the same credentials as NewRootCredentials.

func (*Credentials) Fork

func (c *Credentials) Fork() *Credentials

Fork generates an identical copy of a set of credentials.

func (*Credentials) HasCapability

func (c *Credentials) HasCapability(cp linux.Capability) bool

HasCapability returns true if c has capability cp in its user namespace.

func (*Credentials) HasCapabilityIn

func (c *Credentials) HasCapabilityIn(cp linux.Capability, ns *UserNamespace) bool

HasCapabilityIn returns true if c has capability cp in ns.

func (*Credentials) InGroup

func (c *Credentials) InGroup(kgid KGID) bool

InGroup returns true if c is in group kgid. Compare Linux's kernel/groups.c:in_group_p().

func (*Credentials) NewChildUserNamespace

func (c *Credentials) NewChildUserNamespace() (*UserNamespace, error)

NewChildUserNamespace returns a new user namespace created by a caller with credentials c.

func (*Credentials) SetGID

func (c *Credentials) SetGID(gid GID) error

SetGID translates the provided gid to the root user namespace and updates c's gids to it. This performs no permissions or capabilities checks, the caller is responsible for ensuring the calling context is permitted to modify c.

func (*Credentials) SetUID

func (c *Credentials) SetUID(uid UID) error

SetUID translates the provided uid to the root user namespace and updates c's uids to it. This performs no permissions or capabilities checks, the caller is responsible for ensuring the calling context is permitted to modify c.

func (*Credentials) UseGID

func (c *Credentials) UseGID(gid GID) (KGID, error)

UseGID checks that c can use gid in its user namespace, then translates it to the root user namespace.

func (*Credentials) UseUID

func (c *Credentials) UseUID(uid UID) (KUID, error)

UseUID checks that c can use uid in its user namespace, then translates it to the root user namespace.

The checks UseUID does are common, but you should verify that it's doing exactly what you want.

type GID

type GID uint32

GID is a group ID in an unspecified user namespace.

+marshal slice:GIDSlice

func (GID) Ok

func (gid GID) Ok() bool

Ok returns true if gid is not -1.

func (GID) OrOverflow

func (gid GID) OrOverflow() GID

OrOverflow returns gid if it is valid and the overflow GID otherwise.

type IDMapEntry

type IDMapEntry struct {
	// FirstID is the first ID in the range in the namespace.
	FirstID uint32

	// FirstParentID is the first ID in the range in the parent namespace.
	FirstParentID uint32

	// Length is the number of IDs in the range.
	Length uint32
}

An IDMapEntry represents a mapping from a range of contiguous IDs in a user namespace to an equally-sized range of contiguous IDs in the namespace's parent.

+stateify savable

type KGID

type KGID uint32

KGID is a group ID in the root user namespace.

func (KGID) In

func (kgid KGID) In(ns *UserNamespace) GID

In translates kgid into user namespace ns. If kgid is not mapped in ns, In returns NoID.

func (KGID) Ok

func (kgid KGID) Ok() bool

Ok returns true if kgid is not -1.

type KUID

type KUID uint32

KUID is a user ID in the root user namespace.

func (KUID) In

func (kuid KUID) In(ns *UserNamespace) UID

In translates kuid into user namespace ns. If kuid is not mapped in ns, In returns NoID.

func (KUID) Ok

func (kuid KUID) Ok() bool

Ok returns true if kuid is not -1.

type TaskCapabilities

type TaskCapabilities struct {
	// Permitted is a limiting superset for the effective capabilities that
	// the thread may assume.
	PermittedCaps CapabilitySet
	// Inheritable is a set of capabilities preserved across an execve(2).
	InheritableCaps CapabilitySet
	// Effective is the set of capabilities used by the kernel to perform
	// permission checks for the thread.
	EffectiveCaps CapabilitySet
	// Bounding is a limiting superset for the capabilities that a thread
	// can add to its inheritable set using capset(2).
	BoundingCaps CapabilitySet
	// Ambient is a set of capabilities that are preserved across an
	// execve(2) of a program that is not privileged.
	AmbientCaps CapabilitySet
}

TaskCapabilities represents all the capability sets for a task. Each of these sets is explained in greater detail in capabilities(7).

type UID

type UID uint32

UID is a user ID in an unspecified user namespace.

+marshal

func (UID) Ok

func (uid UID) Ok() bool

Ok returns true if uid is not -1.

func (UID) OrOverflow

func (uid UID) OrOverflow() UID

OrOverflow returns uid if it is valid and the overflow UID otherwise.

type UserNamespace

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

A UserNamespace represents a user namespace. See user_namespaces(7) for details.

+stateify savable

func NewRootUserNamespace

func NewRootUserNamespace() *UserNamespace

NewRootUserNamespace returns a UserNamespace that is appropriate for a system's root user namespace.

func (*UserNamespace) GIDMap

func (ns *UserNamespace) GIDMap() []IDMapEntry

GIDMap returns the group ID mappings configured for ns. If no mappings have been configured, GIDMap returns nil.

func (*UserNamespace) MapFromKGID

func (ns *UserNamespace) MapFromKGID(kgid KGID) GID

MapFromKGID translates kgid, a GID in the root namespace, to a GID in ns.

func (*UserNamespace) MapFromKUID

func (ns *UserNamespace) MapFromKUID(kuid KUID) UID

MapFromKUID translates kuid, a UID in the root namespace, to a UID in ns.

func (*UserNamespace) MapToKGID

func (ns *UserNamespace) MapToKGID(gid GID) KGID

MapToKGID translates gid, a GID in ns, to a GID in the root namespace.

func (*UserNamespace) MapToKUID

func (ns *UserNamespace) MapToKUID(uid UID) KUID

MapToKUID translates uid, a UID in ns, to a UID in the root namespace.

func (*UserNamespace) Root

func (ns *UserNamespace) Root() *UserNamespace

Root returns the root of the user namespace tree containing ns.

func (*UserNamespace) SetGIDMap

func (ns *UserNamespace) SetGIDMap(ctx context.Context, entries []IDMapEntry) error

SetGIDMap instructs ns to translate GIDs as specified by entries.

func (*UserNamespace) SetUIDMap

func (ns *UserNamespace) SetUIDMap(ctx context.Context, entries []IDMapEntry) error

SetUIDMap instructs ns to translate UIDs as specified by entries.

Note: SetUIDMap does not place an upper bound on the number of entries, but Linux does. This restriction is implemented in SetUIDMap's caller, the implementation of /proc/[pid]/uid_map.

func (*UserNamespace) UIDMap

func (ns *UserNamespace) UIDMap() []IDMapEntry

UIDMap returns the user ID mappings configured for ns. If no mappings have been configured, UIDMap returns nil.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL